DB 종류가 다를 때의 주의사항
소스 덤프를 만든 DB와 적용할 target DB의 종류가 다르면(예: PostgreSQL 덤프를 MySQL DB에 적용) SQL 문법이 호환되지 않아 적용이 실패할 수 있습니다. 이 가이드는 KIOPS가 엔진 호환성을 어떻게 다루는지, 그리고 현재 UI에서 무엇이 가능하고 무엇이 불가능한지를 정리합니다.
시작하기 전에: 알아둘 용어
- 소스(source) DB: 원본 덤프를 만든 DB 입니다. 파일 자체에는 소스 DB 의 문법이 그대로 들어 있습니다.
- target DB: 덤프를 풀어 넣을 목적지 DB 입니다.
- 엔진 호환 그룹: SQL 문법이 서로 호환되는 DB 묶음입니다. KIOPS 는 MySQL 과 MariaDB 를 같은 그룹으로, PostgreSQL 을 별도 그룹으로 봅니다.
- 이종 DB: 호환 그룹이 다른 두 DB 입니다 (예: MySQL ↔ PostgreSQL).
- 스키마 변환:
CREATE TABLE같은 DDL 문장의 컬럼 타입·기본값·옵션을 다른 엔진의 문법으로 바꾸는 작업입니다.
핵심 정리: 현재 KIOPS 에서 가능한 것
KIOPS 백엔드에는 MySQL/MariaDB ↔ PostgreSQL 덤프 변환 로직이 구현되어 있지만, 현재 화면(UI)에서는 변환 옵션을 켤 수 있는 진입점이 없습니다. 데이터 패키지 적용 화면(PackageApplyModal)과 마이그레이션 탭의 패키지 적용 경로 모두 변환 옵션을 제공하지 않습니다.
현재 KIOPS 에서 SQL 덤프를 적용할 수 있는 조합은 다음과 같습니다.
| 소스 덤프 엔진 | target DB 엔진 | 적용 가능 여부 |
|---|---|---|
| MySQL / MariaDB | MySQL / MariaDB | 가능 (같은 호환 그룹) |
| PostgreSQL | PostgreSQL | 가능 (같은 엔진) |
| MySQL / MariaDB | PostgreSQL | 적용 불가 |
| PostgreSQL | MySQL / MariaDB | 적용 불가 |
MySQL 과 MariaDB 는 같은 호환 그룹이므로 서로 변환 없이 적용할 수 있습니다.
이종 DB 조합에서 KIOPS 의 동작은 적용 경로에 따라 다릅니다. 마이그레이션 탭의 패키지 적용은 엔진 정합성을 검사해 적용 버튼을 비활성화하여 사전에 막아 줍니다. 데이터 패키지 적용 화면(PackageApplyModal)에는 사전 차단 가드가 없어, 이종 조합으로 적용을 시도하면 SQL 문법 불일치로 적용이 실패합니다. 어느 경로든 결과적으로 이종 DB 에는 변환 없이 적용할 수 없습니다.
사전 준비
- DB 연결 등록: 적용할 target DB 가 DB 연결 탭에 등록되어 있어야 합니다.
- 엔진 일치 확인: 보유한 덤프의 엔진과 target DB 의 엔진이 같은 호환 그룹인지 미리 확인하세요.
마이그레이션 탭은 이종 DB 적용을 차단합니다
마이그레이션 탭에서 "Source 형태"를 "보관된 데이터 패키지 (1회성 적용)"로 선택하면, 선택한 패키지의 DB 타입과 target DB 의 엔진 정합성을 자동으로 검사합니다.
- 같은 호환 그룹(MySQL↔MariaDB 포함): "엔진 정합성 OK" 안내가 표시되고 적용 버튼이 활성화됩니다.
- 이종 DB: "이종 DB — 마이그레이션 불가" 경고가 표시되고 적용 버튼이 비활성화됩니다. 엔진이 다르면 SQL 문법이 호환되지 않아 적용이 실패하기 때문입니다.
따라서 PostgreSQL 덤프를 MySQL DB 에, 또는 그 반대로 변환 없이 적용하려는 시도는 KIOPS 가 사전에 막아 줍니다.
이종 DB 사이에서 데이터를 옮겨야 한다면
DB 종류가 다른 환경 사이에서 데이터를 옮겨야 한다면, 현재 KIOPS 화면 안에서 자동 변환으로 처리할 수는 없습니다. 다음 방법을 검토하세요.
- target 엔진에 맞는 덤프를 외부에서 준비: 소스 DB 담당자에게 target 엔진 문법으로 만든 덤프를 요청하거나, 외부 변환 도구로 미리 변환한
.sql파일을 만든 뒤 KIOPS 에 업로드합니다. - 반복 데이터 복제는 동기화 작업 활용: 두 DB 사이에 데이터를 주기적으로 맞춰야 한다면 [데이터베이스 관리] > 동기화 작업 탭의 기능 적용 범위를 확인하세요.
- 변환 기능 노출 여부는 운영팀에 문의: 백엔드 변환 로직 자체는 존재하므로, 이종 DB 변환을 화면에서 사용해야 한다면 KIOPS 운영팀에 기능 활성화 가능 여부를 문의하세요.
참고: 백엔드 변환 로직의 범위
다음 내용은 KIOPS 백엔드에 구현된 변환 로직의 범위입니다. 현재 UI 에서는 직접 호출되지 않으므로, 운영팀이 변환 기능을 별도로 활성화한 환경에서만 의미가 있습니다. 일반 사용자는 이 단락을 건너뛰어도 됩니다.
MySQL/MariaDB → PostgreSQL (스키마만)
이 방향은 스키마만 변환되고 데이터 행(INSERT)은 변환되지 않습니다. 주요 매핑은 다음과 같습니다.
| 원본 (MySQL/MariaDB) | 변환 결과 (PostgreSQL) |
|---|---|
백틱 식별자 `col` | 백틱 제거 |
int + AUTO_INCREMENT | SERIAL |
bigint + AUTO_INCREMENT | BIGSERIAL |
smallint + AUTO_INCREMENT | SMALLSERIAL |
tinyint(1) | BOOLEAN |
그 외 tinyint(n) | SMALLINT |
int(N) / bigint(N) / smallint(N) | display width 제거 후 INTEGER / BIGINT / SMALLINT |
datetime | TIMESTAMP |
blob / longblob / mediumblob / tinyblob | BYTEA |
longtext / mediumtext / tinytext | TEXT |
longtext + CHECK(json_valid(...)) | JSONB |
ENGINE=..., DEFAULT CHARSET=..., COLLATE=... 테이블 옵션 | 제거 |
current_timestamp() | CURRENT_TIMESTAMP |
KEY / UNIQUE KEY 정의 | 별도 CREATE INDEX 문으로 분리 |
INSERT 데이터 행은 변환되지 않으므로, 이 방향으로는 변환된 스키마 위에 데이터를 별도로 적재해야 합니다.
PostgreSQL → MySQL/MariaDB (스키마 + 선택적 데이터)
이 방향은 스키마 변환과 함께, 옵션을 켜면 COPY 데이터 블록까지 변환할 수 있습니다. 주요 매핑은 다음과 같습니다.
| 원본 (PostgreSQL) | 변환 결과 (MySQL/MariaDB) |
|---|---|
public. 스키마 prefix | 제거 |
SERIAL | INT AUTO_INCREMENT |
BIGSERIAL | BIGINT AUTO_INCREMENT |
SMALLSERIAL | SMALLINT AUTO_INCREMENT |
BOOLEAN | TINYINT(1) |
TIMESTAMP (시간대 없음/있음) | DATETIME |
BYTEA | LONGBLOB |
JSONB | JSON |
CHARACTER VARYING(n) | VARCHAR(n) |
'foo'::text 같은 cast | cast 제거 |
DEFAULT nextval(...) | 제거 |
| 테이블 옵션 | ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci 추가 |
COPY 데이터 블록 | 옵션을 켜면 INSERT 문으로 변환 |
사용자 정의 함수·트리거·시퀀스·extension·VIEW 등은 변환 대상이 아닙니다.
변환된 결과를 적용했다면 반드시 검증하세요
엔진 간 변환은 자동화되어 있어도 100% 완벽하지 않습니다. 변환된 덤프를 적용한 경우 적용 직후 다음을 확인하세요.
- 테이블 개수와 컬럼 수: 소스 DB 와 비교해 누락된 테이블이 없는지 확인합니다.
- 컬럼 타입: 핵심 비즈니스 컬럼(금액·날짜·JSON 등)이 의도한 타입으로 만들어졌는지 확인합니다.
- 인덱스와 제약조건: PK / UK / FK / NOT NULL 이 그대로 옮겨졌는지 확인합니다.
- 기본값:
CURRENT_TIMESTAMP, 시퀀스 기반 기본값이 올바르게 들어갔는지 확인합니다. - 샘플 쿼리: 자주 쓰이는 SELECT/INSERT 문장이 정상적으로 실행되는지 점검합니다.
- 데이터 행: MySQL→PG 방향은 데이터가 비어 있는 것이 정상입니다. PG→MySQL 방향에서 데이터까지 옮겼다면 행 수를 비교합니다.
변환 결과는 스테이징 환경에 먼저 풀어 위 체크리스트를 한 번 돌린 뒤 운영에 적용하세요. 특히 사용자 정의 함수·트리거·시퀀스·extension 등은 자동 변환 대상이 아닙니다.
다음에 할 일
- 같은 엔진끼리 덤프를 옮기는 단순 흐름 → SQL 덤프 파일 업로드
- 보관한 덤프를 여러 환경에 적용 → 데이터 패키지 저장소 활용
- 반복 데이터 복제 → [데이터베이스 관리] > 동기화 작업 탭
관련 가이드
- 페이지 참조: [데이터베이스 관리] 페이지 가이드 (
pages/database) - 운영 백업 흐름: 백업/복구 시나리오