본문으로 건너뛰기

데이터베이스 관리

경로: /database

외부 데이터베이스를 KIOPS와 연결하고 동기화·마이그레이션·백업/복원을 한 곳에서 관리하는 페이지입니다. 접근할 수 없다면 기관 관리자에게 데이터베이스 관리 권한을 요청하세요.

데이터베이스 관리 화면

무엇을 하는 곳인가​

  • DB 연결 관리: 여러 DB 연결 정보를 안전하게(비밀번호 암호화) 등록·테스트합니다. 연결 상태는 상태 사전을 참고하세요.
  • 동기화: 소스 DB의 데이터를 대상 DB로 반복 복제합니다(개발/테스트에 운영 데이터 복사 등). 수동 1회 또는 스케줄 자동 실행.
  • 마이그레이션: DB를 다른 환경으로 이전하는 일회성 작업입니다(동기화는 반복 복제).
  • 데이터 패키지: 보유한 SQL 덤프 파일을 KIOPS에 업로드해 보관하고 여러 환경에 재적용합니다.
  • DB 백업/복원: 인프라 백업(etcd, Docker)과 별개로 DB 데이터만 백업하고 특정 시점으로 복원합니다.

지원 DB: MySQL(5.7+), MariaDB(10.3+)를 우선 지원하며 동일 드라이버로 연결됩니다(MySQL↔MariaDB 호환). 연결 등록 시 선택 가능한 DB 타입은 MariaDB/MySQL/PostgreSQL입니다.

핵심 요소​

7개 탭: DB 연결 · 동기화 작업 · 마이그레이션 · 백업 관리 · DB 백업 저장소 · 데이터 패키지 · 실행 이력. 동기화/마이그레이션·DB 백업 저장소 탭은 해당 권한이 있는 사용자에게만 표시됩니다. 상단 통계 카드는 DB 연결/마이그레이션/백업/동기화 4개만 표시됩니다(데이터 패키지 제외). 실행 상태·연결 상태 표기는 상태 사전 참고.

연결 방식​

  • 연결 방식에서 인프라 종류를 선택합니다 — 직접 접속(호스트:포트로 바로 접속, 대부분의 경우) / Kubernetes(같은 클러스터의 DB에 kubectl exec) / Docker(백엔드 호스트의 컨테이너에 docker exec).
  • SSH 경유는 연결 폼의 켜기/끄기 토글이 아닙니다. 연결된 K8s/Docker 서비스에서 서비스 SSH 가져오기로 SSH 정보를 자동 채우거나, 연결 테스트 단계의 접속 방식 선택 모달에서 입력합니다. 대상이 VPN에 커버되면 이 단계에서 접속 방식(VPN/직접 SSH) 선택 모달이 뜹니다.
  • SSH 사용 시 DB 호스트 주소는 SSH 서버 기준으로 작성합니다(같은 머신이면 localhost, 내부망 다른 서버면 그 서버의 내부 IP). 경로: [KIOPS] → [SSH 터널] → [점프 서버] → [DB 서버].

마이그레이션 (Source 형태 2가지)​

  • 등록된 DB 연결 (스키마 비교): 소스·타겟 DB의 스키마(테이블·컬럼·인덱스·FK) 차이를 표로 비교하고 소스 구조를 타겟에 반영합니다. 두 DB 모두 연결 확인 상태여야 하며 최소 2개 필요. 마이그레이션 전 백업 스위치를 켜면 실행 전 타겟 DB를 자동 백업합니다(권장).
  • 보관된 데이터 패키지 (1회성 적용): 데이터 패키지 탭의 SQL 패키지를 타겟에 적용합니다. 엔진 정합성 자동 검사 — 같은 엔진(MySQL↔MariaDB 포함)만 변환 없이 적용 가능하며, 이종 DB(예: MySQL→PostgreSQL)는 "이종 DB — 마이그레이션 불가" 경고와 함께 적용 버튼이 비활성화됩니다. 적용 전 미리보기(포함 테이블·SQL 종류)와 dry-run 검증(타겟 DB를 실제로 바꾸지 않고 실행)으로 FK 위반·문법 오류·충돌을 확인할 수 있습니다.
  • 마이그레이션 탭에는 SQL 파일 업로드가 없습니다. 새 덤프를 가져오려면 데이터 패키지 탭의 SQL 파일 업로드를 사용하세요.

적용 모드 (패키지 적용 시)​

  • 신규 임포트 (append): CREATE/INSERT를 그대로 적용합니다(기본값·안전). PK/UK 충돌 시 실패할 수 있습니다.
  • 전체 초기화 후 임포트 (replace): 대상 스키마/데이터를 비우고 패키지 내용으로 채웁니다. 되돌릴 수 없어 위험 — 선택 시 적용 전 자동 백업이 강제 활성화되고 별도 위험 확인을 거칩니다. 단, 이 자동 백업은 SSH/K8s/Docker 대상만 지원하며 직접 TCP(direct) 대상은 사전 백업이 생략된 채 replace가 진행되므로, 반드시 수동으로 먼저 백업하세요. 운영 DB는 사전 백업 후 적용을 강력히 권장합니다.

데이터 패키지 저장소​

보유한 SQL 덤프(.sql/.sql.gz, 파일당 최대 1GB)를 업로드해 보관하고 재적용·다운로드·삭제하는 저장소입니다. SQL 파일 업로드 버튼이 KIOPS로 덤프를 가져오는 유일한 입구입니다. 업로드 시점에는 적용되지 않고 보관만 됩니다. 컬럼은 이름·DB 타입·크기·상태·생성일·작업입니다. 상태 표기는 상태 사전을 참고하세요. 목록은 적용이 진행되는 동안 약 5초 주기로 갱신되고, 업로드·적용·삭제 후에도 자동으로 갱신됩니다(수동 새로고침 버튼은 없습니다). 업로드한 .sql.gz는 자동으로 압축이 풀려 .sql로 보관·다운로드됩니다.

  • 30일 보관 정책: 타겟에 적용 완료된 임포트 패키지는 적용 시점으로부터 30일 후 자동 정리됩니다(파일 삭제 + 삭제 처리). 업로드만 한 준비 상태 패키지와 엑스포트 패키지는 대상이 아닙니다. 장기 보존이 필요하면 다운로드해 두세요.
  • 기관당 5GB 한도: 업로드/적용 시점에 초과되면 거부됩니다.

DB 백업​

수동 백업(즉시), 예약 백업(매일/매주/매월 스케줄), 특정 시점 복원을 지원합니다. 보관 정책은 보관 기간 또는 개수 기준으로 오래된 백업을 정리할 수 있습니다(실제 정책은 운영 환경에 따라 다름). 복원은 원본과 다른 DB로도 가능하며, 기존 데이터 삭제 후 복원 또는 병합을 선택합니다. 백업 중 DB 성능이 일시 저하되고 대용량은 오래 걸리므로 운영 DB는 새벽 등 서비스 영향이 적은 시간에 실행하세요.

사용 방법​

DB 연결 등록​

  1. DB 연결 탭에서 연결 추가를 클릭합니다.
  2. 연결 이름·DB 타입·호스트·포트·데이터베이스(스키마)·사용자명·비밀번호를 입력합니다. 모두 필수 항목입니다.
  3. 연결 테스트가 성공하면 저장합니다.

기본 포트는 MySQL·MariaDB가 3306, PostgreSQL이 5432입니다. 연결 테스트가 실패하면 호스트·포트·계정이 정확한지, DB 서버 방화벽에서 포트가 열려 있는지, DB 사용자에게 원격 접속 권한이 있는지 확인하세요.

DB 연결 추가 모달

동기화 작업 생성·실행​

  1. 동기화 작업 탭에서 작업 추가를 클릭합니다.
  2. 소스 DB와 대상 DB를 지정하고, 전체 동기화와 선택 동기화 중 하나를 선택합니다.
  3. 충돌 처리를 선택합니다. 소스 우선은 소스 내용으로 덮어쓰므로 대상 데이터가 사라질 수 있고, 대상 우선은 대상을 그대로 둡니다.
  4. 스케줄을 지정합니다. N시간마다, 매일 지정 시각, cron 중에서 선택합니다.

cron 형식은 분(0-59) 시(0-23) 일(1-31) 월(1-12) 요일(0-6, 0=일)입니다. 0 3 * * *는 매일 3시, 0 */6 * * *는 6시간마다, 0 0 * * 0은 매주 일요일 자정입니다.

즉시 실행하려면 작업의 실행 버튼을 클릭합니다. 동기화는 대상 데이터를 변경하고 대용량은 오래 걸리므로, 운영 DB는 새벽에 실행하세요.

충돌 처리 정책

운영 환경에서는 반드시 테스트 후 적용하세요. 소스 우선은 대상 데이터를 덮어쓰므로 데이터 손실이 발생할 수 있습니다.

데이터 패키지 사용​

  • 업로드(보관만): 데이터 패키지 탭에서 SQL 파일 업로드를 클릭하고 .sql·.sql.gz 파일을 선택하면 즉시 업로드됩니다(최대 1GB).
  • 적용: 행의 적용 버튼을 클릭해 패키지 적용 모달에서 target DB와 적용 모드(기본 append)를 선택합니다. 비밀번호(target/SSH/Jump)를 입력하면 진행 상황이 상태 태그로 표시됩니다.
  • 다운로드: 로컬 PC에 저장합니다. 장기 보관하거나 다른 환경으로 옮길 때 사용합니다.
  • 삭제: 확인 팝업을 거친 뒤 영구 삭제됩니다.

덤프 파일 생성 요청 — 덤프 파일(pg_dump/mysqldump) 생성이 어렵다면 소스 DB의 IT 담당자·DB 관리자에게 요청해, 받은 .sql/.sql.gz를 업로드하세요.

마이그레이션 실행​

마이그레이션 탭에서 Source 형태를 선택한 뒤 진행합니다.

  • ① 등록 DB 비교: 소스·타겟 선택 → 마이그레이션 전 백업 켜기(권장) → 스키마 비교 → 차이가 발견되면 마이그레이션 실행. 기존 데이터가 있는 테이블이 포함되면 손실 경고가 표시됩니다.
  • ② 보관 패키지 적용: 패키지·타겟 선택 → 엔진 정합성 확인 → 미리보기·dry-run(선택) → 적용 모드 선택 → 패키지 적용.

대용량 마이그레이션은 오래 걸리고 서비스에 영향을 줍니다. 운영 DB는 점검 시간에 실행하고, 마이그레이션 전 백업을 반드시 활성화하세요.

DB 백업·복원​

백업 관리 탭 → 백업 생성(대상 DB·이름·포함 항목 선택) 또는 스케줄 설정(주기·보관 정책). 복원은 백업 목록의 복원 버튼 → 대상 DB·기존 데이터 처리 방식 선택 → 복원 시작.

운영 데이터 복원 주의

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

실패 원인 확인​

실패한 작업은 실행 이력 탭에서 클릭해 상세 오류를 확인합니다. 일반적인 원인은 다음과 같습니다.

  • 연결 실패: 네트워크 또는 방화벽 문제입니다.
  • 권한 오류: DB 사용자 권한이 모자랍니다.
  • 스키마 불일치: 구조가 달라서 생깁니다. 마이그레이션 검증을 먼저 수행하세요.
  • 용량 부족: 대상 서버 디스크가 모자랍니다.

이종 DB 관련 제약은 DB 종류가 다를 때의 주의사항 가이드를 참고하세요.