본문으로 건너뛰기

데이터베이스 관리

데이터베이스는 서비스의 핵심입니다. KIWI를 사용하면 여러 데이터베이스를 한 곳에서 관리하고, 데이터 동기화와 마이그레이션을 안전하게 수행할 수 있습니다.

DB 관리 페이지

DB 등록 폼 모달

왜 KIWI로 데이터베이스를 관리하나요?​

수동 작업과 KIWI 사용 비교
  • 연결 관리: 수동으로는 각 서버에 접속해서 확인해야 하지만, KIWI에서는 웹 UI에서 상태를 한눈에 확인할 수 있습니다.
  • 데이터 동기화: 수동으로는 스크립트 작성과 cron 설정이 필요하지만, KIWI에서는 클릭 몇 번으로 설정할 수 있습니다.
  • 마이그레이션: 수동으로는 덤프/복원을 직접 해야 하지만, KIWI에서는 자동화된 안전한 이관이 가능합니다.
  • 모니터링: 수동으로는 별도 모니터링 도구가 필요하지만, KIWI에서는 대시보드에서 통합 관리할 수 있습니다.

지원 데이터베이스​

  • MySQL (5.7 이상): 동기화, 마이그레이션, 백업 기능을 지원합니다.
  • MariaDB (10.3 이상): 동기화, 마이그레이션, 백업 기능을 지원합니다.
  • PostgreSQL (12 이상): 동기화, 마이그레이션, 백업 기능을 지원합니다.
  • Oracle (12c 이상): 동기화, 마이그레이션 기능을 지원합니다.
버전 확인 방법
-- MySQL/MariaDB
SELECT VERSION();

-- PostgreSQL
SELECT version();

데이터베이스 연결 등록하기​

운영 중인 데이터베이스를 KIWI에 등록합니다. 한 번 등록하면 연결 상태 모니터링, 동기화, 마이그레이션을 웹 UI에서 수행할 수 있습니다.

Step 1: 연결 추가 시작​

좌측 메뉴에서 **[데이터베이스 관리]**를 클릭하고, 연결 추가 버튼을 클릭합니다.

Step 2: 데이터베이스 유형 및 연결 정보 입력​

데이터베이스 유형을 선택하고 연결 정보를 입력합니다:

  • 연결 이름: 식별하기 쉬운 이름입니다. (예: production-mysql)
  • 호스트: 데이터베이스 서버 주소입니다. (예: db.company.com)
  • 포트: 데이터베이스 포트입니다. (MySQL: 3306, PostgreSQL: 5432)
  • 데이터베이스명: 연결할 DB 이름입니다. (예: myapp)
  • 사용자명: 접속 계정입니다. (예: admin)
  • 비밀번호: 접속 비밀번호입니다.

Step 3: 고급 설정 (선택사항)​

필요한 경우 고급 설정을 구성합니다:

  • SSL 사용: 암호화된 연결을 사용합니다. 운영 환경이나 외부 네트워크에서 권장됩니다.
  • SSH 터널: SSH를 통해 접근합니다. 방화벽 뒤의 DB에 접근할 때 사용합니다.
  • 연결 풀 크기: 동시 연결 수를 설정합니다. 기본값은 10이며 부하에 따라 조정합니다.
  • 타임아웃: 연결 제한 시간을 설정합니다. 기본값은 30초입니다.
SSL 연결 권장

운영 환경에서는 반드시 SSL 연결을 사용하세요. 데이터베이스 자격 증명과 데이터가 암호화되어 전송됩니다.

Step 4: 연결 테스트 및 저장​

연결 테스트 버튼을 클릭하여 연결을 확인합니다. 성공하면 데이터베이스 버전과 연결 정보가 표시됩니다. 저장을 클릭하여 등록을 완료합니다.

연결 실패 시 확인사항
  • 데이터베이스 서버가 해당 IP에서 접속을 허용하는지 확인
  • 방화벽에서 데이터베이스 포트가 열려 있는지 확인
  • 사용자 권한이 원격 접속을 허용하는지 확인

데이터베이스 동기화 작업 설정하기​

두 데이터베이스 간 데이터를 동기화하는 방법입니다.

사전 조건: 소스와 대상 데이터베이스가 모두 KIWI에 등록되어 있어야 합니다.

Step 1: 동기화 탭 이동​

[데이터베이스 관리] 페이지에서 상단의 동기화 탭을 클릭합니다.

Step 2: 새 동기화 작업 생성​

동기화 작업 추가 버튼을 클릭합니다.

Step 3: 소스 및 대상 설정​

다음 정보를 설정합니다:

  • 작업 이름: 이 동기화 작업을 식별할 수 있는 이름입니다.
  • 소스 DB: 데이터를 가져올 데이터베이스입니다.
  • 대상 DB: 데이터를 저장할 데이터베이스입니다.
  • 동기화 방향: 단방향(소스→대상) 또는 양방향 중 선택합니다.

Step 4: 동기화 대상 테이블 선택​

동기화할 테이블을 선택합니다:

  • 전체 테이블: 모든 테이블을 동기화합니다.
  • 선택 테이블: 특정 테이블만 선택하여 동기화합니다.
  • 제외 테이블: 특정 테이블을 제외하고 나머지를 동기화합니다.

Step 5: 동기화 옵션 설정​

동기화 동작을 설정합니다:

  • 충돌 처리: 데이터 충돌 시 소스 우선 또는 대상 우선을 선택합니다.
  • 삭제 동기화: 소스에서 삭제된 데이터를 대상에서도 삭제할지 선택합니다.
  • 배치 크기: 한 번에 처리할 레코드 수입니다. 기본값은 1000입니다.

Step 6: 스케줄 설정 (선택사항)​

동기화 실행 주기를 설정합니다:

  • 수동: 수동으로만 실행합니다.
  • 실시간: CDC(Change Data Capture) 기반으로 변경 사항을 실시간 동기화합니다.
  • 정기: cron 스케줄 기반으로 정기 동기화합니다.

Step 7: 저장 및 실행​

저장 버튼을 클릭합니다. 지금 실행 버튼으로 즉시 동기화를 실행할 수 있습니다.

데이터베이스 마이그레이션 실행하기​

데이터베이스 스키마와 데이터를 새 서버로 이관하는 방법입니다.

Step 1: 마이그레이션 탭 이동​

[데이터베이스 관리] 페이지에서 상단의 마이그레이션 탭을 클릭합니다.

Step 2: 새 마이그레이션 생성​

마이그레이션 생성 버튼을 클릭합니다.

Step 3: 마이그레이션 유형 선택​

이관 범위를 선택합니다:

  • 스키마만: DDL(테이블 구조)만 이관합니다. 개발 환경 복제에 적합합니다.
  • 데이터만: 데이터만 이관합니다. 스키마가 이미 존재하는 경우 사용합니다.
  • 전체: 스키마와 데이터를 모두 이관합니다. 완전한 복제에 사용합니다.

Step 4: 소스/대상 설정​

다음 정보를 설정합니다:

  • 소스 DB: 원본 데이터베이스입니다.
  • 대상 DB: 이관 대상 데이터베이스입니다.
  • 대상 스키마: 대상 DB의 스키마명입니다. (선택사항)

Step 5: 마이그레이션 옵션 설정​

마이그레이션 동작을 설정합니다:

  • 외래키 검사: 마이그레이션 중 FK 검사를 비활성화하여 속도를 높입니다.
  • 인덱스 재생성: 마이그레이션 후 인덱스를 재생성합니다.
  • 트리거 포함: 트리거와 프로시저를 포함할지 선택합니다.
  • 병렬 처리: 동시 처리 스레드 수를 설정합니다.

Step 6: 마이그레이션 미리보기​

미리보기 버튼을 클릭하여 다음 정보를 확인합니다:

  • 이관될 테이블 목록
  • 예상 데이터 크기
  • 예상 소요 시간

Step 7: 마이그레이션 실행​

마이그레이션 시작 버튼을 클릭합니다. 진행률과 로그를 실시간으로 확인할 수 있습니다.

데이터베이스 모니터링 확인하기​

등록된 데이터베이스의 상태를 확인하는 방법입니다.

Step 1: 연결 상태 확인​

[데이터베이스 관리] 페이지의 연결 목록에서 각 데이터베이스의 연결 상태를 확인합니다:

  • 연결됨: 정상적으로 연결된 상태입니다.
  • 연결 끊김: 연결이 실패한 상태입니다. 네트워크 또는 인증 정보를 확인하세요.
  • 대기 중: 연결을 시도하는 중입니다.

Step 2: 상세 모니터링 보기​

연결 항목을 클릭하면 상세 정보를 확인할 수 있습니다:

  • 연결 풀 상태
  • 쿼리 실행 통계
  • 마지막 활동 시간

SSH 터널을 통한 데이터베이스 연결​

방화벽 뒤에 있는 데이터베이스에 접근하는 방법입니다.

사전 조건: SSH 접근이 가능한 서버가 **[장비 관리]**에 등록되어 있어야 합니다.

Step 1: 데이터베이스 연결 추가​

[데이터베이스 관리] 페이지에서 연결 추가 버튼을 클릭합니다.

Step 2: SSH 터널 활성화​

SSH 터널 사용 체크박스를 선택합니다.

Step 3: SSH 설정 입력​

SSH 터널 정보를 입력합니다:

  • SSH 호스트: 터널링에 사용할 SSH 서버 주소입니다. (예: gateway.company.com)
  • SSH 포트: SSH 포트입니다. (기본값: 22)
  • SSH 사용자: SSH 접속 계정입니다.
  • 인증 방식: 비밀번호 또는 SSH 키를 선택합니다.
    • 비밀번호: SSH 접속 비밀번호를 입력합니다.
    • SSH 키: SSH 개인 키 파일(.pem, .key)을 업로드합니다.
  • 로컬 포트: 터널 포트입니다. 자동으로 할당됩니다.

Step 4: 데이터베이스 연결 정보 입력​

데이터베이스 호스트는 SSH 서버 기준의 내부 주소를 사용합니다. (예: localhost 또는 192.168.x.x)

Step 5: 연결 테스트 및 저장​

SSH 터널과 데이터베이스 연결이 모두 성공해야 저장할 수 있습니다.

자주 묻는 질문​

데이터베이스 연결이 실패합니다​

  • "Connection refused": 포트가 차단되었거나 서비스가 중지되었습니다. 방화벽 및 DB 서비스 상태를 확인하세요.
  • "Access denied": 인증에 실패했습니다. 사용자명/비밀번호 및 권한을 확인하세요.
  • "Host not allowed": 원격 접속이 허용되지 않았습니다. DB에서 해당 IP 접속을 허용하세요.
  • "Connection timeout": 네트워크 문제입니다. 네트워크 연결 및 방화벽을 확인하세요.

동기화가 느립니다​

원인 및 해결 방법:

  1. 배치 크기 조정: 기본값 1000에서 더 크게(5000~10000) 설정
  2. 인덱스 확인: 대상 테이블에 적절한 인덱스가 있는지 확인
  3. 네트워크 속도: 데이터 센터 간 동기화는 네트워크 속도의 영향을 크게 받음
  4. 병렬 처리: 동시 처리 스레드 수 증가

마이그레이션 중 오류가 발생합니다​

마이그레이션 오류 해결
  1. 외래키 오류: "외래키 검사 비활성화" 옵션 활성화
  2. 데이터 타입 불일치: 마이그레이션 미리보기에서 타입 매핑 확인
  3. 용량 부족: 대상 DB의 디스크 공간 확인
  4. 타임아웃: 대용량 테이블은 배치 크기를 줄여서 처리

SSL 연결이 안 됩니다​

  • 데이터베이스 서버에서 SSL이 활성화되어 있는지 확인
  • 인증서 파일(CA, 클라이언트 인증서)이 올바른지 확인
  • 자체 서명 인증서인 경우 "TLS 인증서 검증 비활성화" 옵션 사용

관련 가이드​

추천 다음 단계