본문으로 건너뛰기

데이터베이스 관리

경로: /database

외부 데이터베이스를 KIWI와 연결하고, 데이터 동기화 및 복원을 관리하는 페이지입니다. 여러 데이터베이스를 중앙에서 관리하고 자동화된 동기화 작업을 설정할 수 있습니다.

데이터베이스 관리 화면

권한 안내

이 페이지에 접근할 수 없다면 기관 관리자에게 데이터베이스 관리 권한을 요청하세요.

왜 데이터베이스 관리가 필요한가요?​

DevSecOps 환경에서는 개발, 테스트, 운영 등 여러 환경의 데이터베이스를 관리해야 합니다. KIWI의 데이터베이스 관리 기능을 사용하면:

  • 중앙 집중 관리: 여러 DB 연결 정보를 한 곳에서 안전하게 관리
  • 자동 동기화: 환경 간 데이터를 정기적으로 동기화하여 일관성 유지
  • 빠른 복구: 문제 발생 시 특정 시점으로 빠르게 복원
  • 보안 강화: SSH 터널링과 SSL 연결로 안전한 DB 접근

지원 데이터베이스​

KIWI에서 지원하는 데이터베이스 종류와 기능을 확인하세요.

  • MySQL (5.7 이상): 연결, 동기화, 복원을 모두 지원합니다. 가장 널리 사용되는 데이터베이스입니다.
  • MariaDB (10.3 이상): 연결, 동기화, 복원을 모두 지원합니다. MySQL과 호환됩니다.
  • PostgreSQL (12 이상): 연결, 동기화, 복원을 모두 지원합니다. 고급 기능을 지원합니다.
  • Oracle (12c 이상): 연결, 동기화를 지원하지만 복원은 미지원입니다.
MySQL과 MariaDB 호환성

MySQL과 MariaDB는 호환성이 높아 동일한 드라이버로 연결됩니다. 기존 MySQL용으로 개발된 애플리케이션은 대부분 MariaDB에서도 동작합니다.

주요 기능​

연결 관리​

데이터베이스 연결을 등록하고 관리하는 핵심 기능입니다.

  • 연결 등록: 새로운 DB 연결 정보를 저장합니다. 새 DB를 추가할 때 사용합니다.
  • 연결 테스트: 연결이 정상인지 즉시 확인합니다. 등록 전이나 문제 발생 시 사용합니다.
  • SSL/TLS 연결: 암호화된 보안 연결을 제공합니다. 외부 네트워크 통신 시 권장됩니다.
  • SSH 터널링: 방화벽 우회 연결을 제공합니다. 직접 접근이 불가능한 DB에 사용합니다.
SSH 터널링이란?

SSH 터널링은 SSH 연결을 통해 데이터베이스 트래픽을 전달하는 방식입니다. 점프 서버(bastion host)를 통해 내부망의 DB에 안전하게 접속할 수 있습니다.

동기화 작업​

소스 DB와 대상 DB 간의 데이터를 동기화합니다. 개발/테스트 환경에 운영 데이터를 복사하거나, 백업 용도로 활용할 수 있습니다.

  • 수동 동기화: 즉시 1회 실행합니다. 테스트 또는 긴급 상황에서 사용합니다.
  • 자동 동기화: 스케줄에 따라 반복 실행합니다. 정기적 데이터 갱신에 사용합니다.
  • 전체 동기화: 모든 테이블을 동기화합니다. 초기 설정 또는 전체 복제에 사용합니다.
  • 선택 동기화: 지정한 테이블만 동기화합니다. 특정 데이터만 필요할 때 사용합니다.
충돌 처리 정책 선택
  • 소스 우선: 소스 DB 데이터로 대상 DB를 덮어씁니다 (데이터 손실 가능)
  • 대상 우선: 충돌 시 대상 DB 데이터를 유지합니다 (소스 변경 무시)

운영 환경에서는 반드시 테스트 후 적용하세요!

데이터 복원​

백업 파일이나 스냅샷을 이용해 특정 시점으로 데이터를 복원합니다.

마이그레이션​

데이터베이스를 다른 환경으로 이전하거나 업그레이드할 때 사용하는 기능입니다.

  • 스키마 마이그레이션: 테이블 구조, 인덱스, 제약조건 등 DB 구조를 이전합니다. 새 환경 구축이나 버전 업그레이드 시 사용합니다.
  • 데이터 마이그레이션: 실제 데이터를 소스 DB에서 대상 DB로 이전합니다. 대용량 데이터도 안전하게 처리됩니다.
  • 검증 기능: 마이그레이션 전후 데이터 정합성을 자동으로 검증합니다. 누락되거나 변경된 데이터가 없는지 확인할 수 있습니다.
  • 롤백 지원: 마이그레이션 실패 시 이전 상태로 되돌릴 수 있습니다. 백업 옵션을 활성화하면 자동으로 백업 후 진행됩니다.
마이그레이션 vs 동기화
  • 마이그레이션: 일회성 이전 작업입니다. 개발→스테이징→운영 환경 이전, DB 서버 교체 등에 사용합니다.
  • 동기화: 반복적인 데이터 복제입니다. 정기적으로 데이터를 최신 상태로 유지할 때 사용합니다.

DB 백업 관리​

데이터베이스를 직접 백업하고 복원하는 기능입니다. KIWI의 인프라 백업(etcd, Docker)과 별도로 DB 데이터만 백업할 수 있습니다.

  • 수동 백업: 즉시 백업을 생성합니다. 중요한 작업 전 현재 상태를 보존할 때 사용합니다.
  • 예약 백업: 지정된 스케줄에 따라 자동으로 백업합니다. 매일 새벽, 매주 일요일 등 원하는 주기를 설정할 수 있습니다.
  • 백업 보관 정책: 오래된 백업을 자동 삭제합니다. 보관 기간(예: 30일)이나 보관 개수(예: 최근 10개)를 설정할 수 있습니다.
  • 특정 시점 복원: 백업 목록에서 원하는 시점을 선택하여 복원합니다.
백업 전 확인사항
  • 백업 중에는 DB 성능이 일시적으로 저하될 수 있습니다.
  • 대용량 DB는 백업에 시간이 오래 걸릴 수 있으므로 여유 있는 시간에 실행하세요
  • 운영 DB는 서비스 영향이 적은 시간(새벽)에 백업하는 것을 권장합니다.

UI 구성​

데이터베이스 관리 페이지는 5개의 탭으로 구성되어 있습니다. 각 탭은 사용자 권한에 따라 표시 여부가 달라질 수 있습니다.

  • DB 연결: 데이터베이스 연결 정보를 등록하고 관리합니다. 연결 목록, 상태, 타입을 확인하고 새 연결을 추가할 수 있습니다.
  • 동기화 작업: 두 DB 간 데이터 동기화를 설정하고 실행합니다. 작업 목록, 스케줄, 다음 실행 시간을 확인할 수 있습니다. (동기화 권한 필요)
  • 마이그레이션: 데이터베이스 스키마와 데이터를 다른 환경으로 이전합니다. 스키마 비교 기능도 이 탭에서 제공됩니다. (마이그레이션 권한 필요)
  • 백업 관리: DB 백업을 생성하고 복원합니다. 정기 백업 스케줄 설정과 복원 이력을 관리할 수 있습니다.
  • 실행 이력: 동기화, 마이그레이션, 백업 등 모든 작업의 실행 기록을 조회합니다. 실행 시간, 결과, 오류 메시지를 확인할 수 있습니다.
권한에 따른 탭 표시

동기화 작업, 마이그레이션 탭은 해당 권한이 있는 사용자에게만 표시됩니다. 탭이 보이지 않는다면 기관 관리자에게 권한을 요청하세요.

연결 목록에서 확인할 수 있는 정보​

  • 이름: 연결을 쉽게 식별할 수 있는 이름 (예: "운영DB", "개발DB")
  • 타입: MySQL, MariaDB, PostgreSQL 등
  • 호스트: DB 서버 주소
  • 포트: DB 포트 번호
  • 연결 상태: 현재 연결 가능 여부 (초록색: 정상, 빨간색: 연결 불가)

사용 방법​

1. DB 연결 등록하기​

새로운 데이터베이스 연결을 등록하는 방법입니다.

DB 연결 추가 모달

Step 1: 연결 추가 시작

  1. [데이터베이스 관리] 페이지로 이동합니다.
  2. 연결 관리 탭을 선택합니다.
  3. 우측 상단의 연결 추가 버튼을 클릭합니다.

Step 2: 기본 정보 입력

  • 연결 이름 (필수): 식별 가능한 이름입니다. 예: "운영-사용자DB"
  • DB 타입 (필수): 데이터베이스 종류입니다. 예: MySQL
  • 호스트 (필수): 서버 IP 또는 도메인입니다. 예: 192.168.1.100
  • 포트 (필수): DB 포트 번호입니다. 예: 3306
  • 데이터베이스 (필수): DB 이름(스키마)입니다. 예: kiwi_prod
  • 사용자명 (필수): DB 계정입니다. 예: admin
  • 비밀번호 (필수): DB 비밀번호입니다.
기본 포트 번호
  • MySQL / MariaDB: 3306
  • PostgreSQL: 5432
  • Oracle: 1521

기본 포트가 아닌 경우 실제 DB 서버에서 사용하는 포트를 입력하세요.

Step 3: 고급 설정 (선택)

  • SSL 사용: 암호화 연결이 필요한 경우 활성화
  • SSH 터널: 방화벽 뒤 DB 접속 시 설정
  • 연결 타임아웃: 느린 네트워크 환경에서는 값을 늘려주세요

Step 4: 연결 테스트 및 저장

  1. 연결 테스트 버튼을 클릭하여 연결 상태 확인
  2. "연결 성공" 메시지가 표시되면 저장 클릭
연결 테스트 실패 시
  • 호스트, 포트, 계정 정보가 정확한지 확인
  • DB 서버의 방화벽에서 해당 포트가 열려있는지 확인
  • DB 사용자에게 원격 접속 권한이 있는지 확인

2. SSH 터널 설정하기​

방화벽 뒤에 있는 DB에 접근할 때 SSH 터널링을 사용합니다.

언제 SSH 터널이 필요한가요?

  • DB 서버가 내부망에 있어 직접 접근이 불가능할 때
  • 보안 정책상 점프 서버(bastion host)를 통해서만 접근 가능할 때
  • 외부에서 사내 DB에 안전하게 접속해야 할 때

설정 방법:

  1. 연결 추가/편집 화면에서 SSH 터널 사용 체크박스 활성화

  2. SSH 서버 정보 입력:

    • SSH 호스트: 점프 서버 IP입니다. 예: 10.0.0.50
    • SSH 포트: SSH 포트입니다 (기본 22). 예: 22
    • SSH 사용자: SSH 접속 계정입니다. 예: deploy
    • 인증 방식: 비밀번호 또는 SSH 키를 선택합니다.
      • 비밀번호: SSH 비밀번호를 입력합니다.
      • SSH 키: SSH 개인 키 파일(.pem, .key)을 업로드합니다.

  3. DB 호스트 주소 입력 시 SSH 서버 기준으로 작성

    • DB가 SSH 서버와 같은 머신에 있다면: localhost 또는 127.0.0.1
    • DB가 내부망의 다른 서버에 있다면: 해당 서버의 내부 IP

  4. 연결 테스트 후 저장

SSH 터널 동작 원리
[KIWI] → [SSH 터널] → [점프 서버] → [DB 서버]
              암호화된 연결

SSH 터널을 사용하면 KIWI에서 점프 서버까지 암호화된 통로가 만들어지고, 그 통로를 통해 DB에 접근합니다.

3. 동기화 작업 생성하기​

두 데이터베이스 간 데이터를 동기화하는 작업을 설정합니다.

Step 1: 작업 추가

  1. 동기화 작업 탭 선택
  2. 작업 추가 버튼 클릭

Step 2: 기본 설정

  • 작업 이름: 알아보기 쉬운 이름 (예: "운영→개발 동기화")
  • 소스 DB: 데이터를 가져올 원본 DB 연결 선택
  • 대상 DB: 데이터를 저장할 목적지 DB 연결 선택

Step 3: 동기화 옵션 선택

  • 전체 동기화: 모든 테이블을 동기화합니다.
  • 선택 동기화: 필요한 테이블만 선택하여 동기화합니다.
  • 충돌 처리:
    • 소스 우선 - 충돌 시 소스 데이터로 덮어씀
    • 대상 우선 - 충돌 시 대상 데이터 유지

Step 4: 스케줄 설정 (자동 동기화)

  • 시간 단위: 예를 들어 6시간마다 설정하면 매 6시간마다 실행됩니다.
  • 일 단위: 예를 들어 매일 03:00으로 설정하면 매일 오전 3시에 실행됩니다.
  • cron 표현식: 예를 들어 0 3 * * 1로 설정하면 매주 월요일 오전 3시에 실행됩니다.
cron 표현식 형식
분(0-59) 시(0-23) 일(1-31) 월(1-12) 요일(0-6, 0=일요일)

자주 사용하는 예시:

  • 0 3 * * * - 매일 오전 3시
  • 0 */6 * * * - 6시간마다.
  • 0 0 * * 0 - 매주 일요일 자정

Step 5: 저장 설정을 검토하고 저장 버튼을 클릭합니다.

4. 동기화 즉시 실행하기​

설정된 동기화 작업을 바로 실행합니다.

  1. 동기화 작업 탭에서 실행할 작업을 찾습니다.
  2. 해당 작업의 실행 버튼을 클릭합니다.
  3. 확인 팝업에서 확인을 클릭합니다.
  4. 진행률 표시줄로 진행 상황을 확인합니다.
  5. 완료 후 동기화 이력 탭에서 결과를 확인합니다.
동기화 실행 전 확인사항
  • 대상 DB의 데이터가 변경됩니다.
  • 대용량 테이블은 동기화에 시간이 오래 걸릴 수 있습니다.
  • 운영 DB 동기화는 서비스 영향이 적은 시간(새벽)에 실행하세요

5. 마이그레이션 실행하기​

데이터베이스를 새 환경으로 이전합니다.

Step 1: 마이그레이션 시작

  1. 마이그레이션 탭을 선택합니다.
  2. 새 마이그레이션 버튼을 클릭합니다.

Step 2: 소스/대상 설정

  • 소스 DB: 데이터를 가져올 원본 DB를 선택합니다.
  • 대상 DB: 데이터를 저장할 새 환경 DB를 선택합니다.

Step 3: 마이그레이션 옵션 선택

  • 스키마만 마이그레이션: 테이블 구조만 이전하고 데이터는 제외합니다. 새 환경 초기 구축 시 사용합니다.
  • 데이터 포함: 구조와 데이터를 함께 이전합니다. 전체 환경 복제 시 사용합니다.
  • 백업 후 진행: 마이그레이션 전 대상 DB를 자동 백업합니다. 문제 발생 시 롤백이 가능하므로 권장합니다.

Step 4: 검증 및 실행

  1. 스키마 검증 버튼으로 호환성을 미리 확인합니다.
  2. 문제가 없으면 마이그레이션 시작을 클릭합니다.
  3. 진행 상황을 실시간으로 확인할 수 있습니다.
마이그레이션 주의사항
  • 대용량 DB는 마이그레이션에 시간이 오래 걸릴 수 있습니다.
  • 운영 중인 DB는 서비스 영향을 최소화하기 위해 점검 시간에 실행하세요
  • 반드시 백업 후 진행 옵션을 활성화하세요

6. DB 백업 생성하기​

데이터베이스를 백업하여 안전하게 보관합니다.

수동 백업 생성:

  1. 백업 관리 탭을 선택합니다.
  2. 백업 생성 버튼을 클릭합니다.
  3. 백업 대상 DB 연결을 선택합니다.
  4. 백업 옵션을 설정합니다:
    • 백업 이름: 식별하기 쉬운 이름 (예: "운영DB-2024-03-15")
    • 포함 항목: 전체 또는 특정 테이블 선택
  5. 백업 시작을 클릭합니다.

예약 백업 설정:

  1. 백업 관리 탭에서 스케줄 설정 버튼을 클릭합니다.
  2. 백업 대상 DB를 선택합니다.
  3. 스케줄을 설정합니다:
    • 매일: 매일 지정 시간에 실행 (예: 03:00)
    • 매주: 특정 요일에 실행 (예: 일요일 02:00)
    • 매월: 특정 일에 실행 (예: 1일 01:00)
  4. 보관 정책을 설정합니다:
    • 보관 기간: 예를 들어 30일 후 자동 삭제
    • 보관 개수: 예를 들어 최근 10개만 유지
  5. 저장을 클릭합니다.

7. DB 복원하기​

백업에서 데이터를 복원합니다.

  1. 백업 관리 탭을 선택합니다.
  2. 백업 목록에서 복원할 백업을 찾습니다.
  3. 해당 백업의 복원 버튼을 클릭합니다.
  4. 복원 대상 DB를 선택합니다 (원본과 다른 DB도 가능)
  5. 복원 옵션을 설정합니다:
    • 기존 데이터 처리: 삭제 후 복원 / 병합
  6. 복원 시작을 클릭합니다.
복원 시 주의

복원 작업은 대상 DB의 기존 데이터를 변경합니다. 운영 환경에서 복원 전 반드시 현재 상태를 백업하세요!

실행 이력 상태​

동기화, 마이그레이션, 백업/복원 등 모든 작업의 진행 상태를 실행 이력 탭에서 확인할 수 있습니다.

  • completed (완료): 작업이 정상적으로 완료되었습니다.
  • running (실행중): 작업이 현재 진행 중입니다.
  • failed (실패): 작업 중 오류가 발생했습니다 (상세 내용 확인 필요)
  • pending (대기중): 스케줄에 따라 실행을 대기 중입니다.
실패한 작업 해결 방법
  1. 실행 이력 탭에서 실패한 작업을 클릭합니다.
  2. 상세 오류 메시지를 확인합니다.
  3. 일반적인 원인과 해결 방법:
    • 연결 실패: 네트워크 상태 또는 방화벽 설정을 확인하세요
    • 권한 오류: DB 사용자에게 필요한 권한이 있는지 확인하세요
    • 스키마 불일치: 소스와 대상의 테이블 구조가 다릅니다. 마이그레이션 검증을 먼저 실행하세요
    • 용량 부족: 대상 서버의 디스크 공간을 확인하세요

용어 설명​

처음 접하는 용어들을 쉽게 설명합니다.

  • 스키마(Schema): 데이터베이스의 논리적 구조(테이블, 관계 등)입니다. MySQL에서는 데이터베이스와 같은 의미로 사용됩니다.
  • SSL/TLS: 네트워크 통신을 암호화하는 보안 프로토콜입니다. HTTPS에서 사용하는 것과 동일합니다.
  • SSH 터널링: SSH 연결을 통해 다른 서비스의 트래픽을 안전하게 전달하는 기술입니다.
  • cron 표현식: Unix 계열 OS에서 정기 작업 스케줄을 지정하는 표준 문법입니다.
  • 덤프(Dump): 데이터베이스의 구조와 데이터를 SQL 파일로 내보내는 것입니다.
  • 점프 서버: 외부에서 내부망에 접근하기 위한 중계 서버입니다 (bastion host라고도 합니다).

베스트 프랙티스​

안전하고 효율적인 데이터베이스 관리를 위한 권장 사항입니다.

보안 권장사항
  • SSL 연결 사용: 특히 외부 네트워크 통신 시 필수
  • 전용 계정 사용: 동기화 전용 DB 계정을 만들어 최소 권한 부여
  • 비밀번호 관리: 모든 DB 비밀번호는 암호화되어 저장됩니다.
운영 권장사항
  • 동기화 시간: 운영 DB는 서비스 영향이 적은 새벽 시간에 동기화
  • 연결 테스트: 중요한 작업 전 항상 연결 테스트 실행
  • 이력 모니터링: 정기적으로 동기화 이력을 확인하여 실패 여부 체크
  • 백업 후 복원: 복원 전 현재 상태를 반드시 백업