ORM 없이 레거시 DB 마이그레이션: 구조와 실천

## ORM 없는 레거시 프로젝트를 위한 데이터베이스 마이그레이션 시스템

ORM이 없는 레거시 시스템에서 DDL/DML 스크립트 마이그레이션을 관리하려면 엄격한 통제가 필요합니다. 이 방법은 리포지토리를 체계적으로 구성하고 상태 테이블을 활용해 테스트와 프로덕션 환경에서 변경 사항을 일관되게 적용합니다. ACID 준수 관계형 데이터베이스에서 추적 가능성, 데이터 무결성, 예측 가능한 배포를 보장합니다.

이 접근법은 스크립트의 보일러플레이트 코드를 줄이고 검증 및 로깅을 자동화합니다. 스크립트는 초기화, 베이스라인, 버전 관리, 반복 실행 네 가지 유형으로 나뉩니다. 각 유형은 중복 방지와 버전 단조 증가를 위한 특정 규칙을 따릅니다.

Git 리포지토리 구조

스크립트는 유형별로 그룹화되며 고정된 순서로 적용됩니다:

• 환경 초기화 — 사용자, 역할, 데이터베이스, 스키마를 생성하기 위해 한 번만 실행. 환경별(테스트/프로덕션)로, psql을 통해 실행.
• 베이스라인 — 빈 스키마에 한 번 실행해 초기 프로덕션 버전과 제어 테이블을 설정.
• 버전 관리 — 오름차순 정수 버전으로 순차 적용, 한 번만 실행되며 타임스탬프와 사용자를 로그로 기록하는 트랜잭션 내에서.
• 반복 실행 — SHA256이 변경되거나 기록이 없으면 버전 관리 스크립트 이후에 적용. 데이터 변경 없는 뷰/프로시저/트리거용.

객체 유형:

• 초기화: 사용자, 역할, 데이터베이스, 스키마.
• 베이스라인: 테이블, 데이터, 뷰, 프로시저, 트리거.
• 버전 관리: 스키마 변경, 데이터 마이그레이션.
• 반복 실행: 뷰, 프로시저, 트리거.

이 구조는 Flyway에서 영감을 얻었으나 외부 도구 없이 수동 프로세스에 맞게 조정되었습니다.

스키마 내 상태 테이블

각 스키마에 변경 추적을 위한 서비스 테이블이 생성됩니다:

• dbmigration_versions (version_id, is_baseline, created_at, created_by, created_from) — 베이스라인과 버전 관리 스크립트 이력 추적.
• dbmigration_repeatable (sha256sum, relative_path, created_at, created_by, created_from) — 반복 실행 스크립트 추적, 변경 시 재적용 가능.

이 테이블들은 스크립트 실행 전 체크를 강제합니다: 기록이 없거나 체크섬이 변경된 경우에만 실행. 로그에는 사용자와 타임스탬프가 기록되어 완전한 감사 추적을 제공합니다.

개발 배포

CI/CD(GitLab 파이프라인)에서 변경 브랜치를 클론한 후 각 스키마에 대해:

$ git clone <데이터베이스 스키마 변경이 포함된 URL>
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema1 ./db/schema1
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema2 ./db/schema2

이 과정에서 보류된 스크립트가 자동 적용되며 데이터는 보존됩니다.

프로덕션 프로세스

제로 다운타임 핫 배포를 지원합니다. UAT에서 사전 테스트와 스모크 테스트를 거칩니다.

단계:

• 아카이브 추출: tar xzvf system-x.y.z.tar.gz.
• 스키마로 이동: cd system-x.y.z/schema1.
• 마이그레이션 스크립트 생성: USER_PASSWORD=topsecret123 dbmigration.py verify --host <host> --port <port> --dbname <db> --user <user_name> --build-update-script ./schema1_migrate.sql schema1 ./db/schema1.
• schema1_migrate.sql을 검토해 파괴적 변경 확인.
• 적용: PGPASSWORD=topsecret123 psql -h <host> -p <port> -U <user> -d <database> -v schema_name=<schema1> -f "schema1_migrate.sql".

각 스키마에 반복. 검증 모드는 변경 사항을 미리보기만 합니다.

주요 관행

• 앞으로 수정(Fix forward): 롤백 대신 새로운 마이그레이션으로 오류 수정, 데이터 보존.
• 비파괴적 변경: 테이블/컬럼 먼저 추가, 사용되지 않을 때 릴리스 후 제거. 동일 DB에서 멀티버전 공존 가능.
• 스키마 수준 추적: 데이터베이스가 아닌 스키마별 버전 관리.
• 사전 체크: 검토용 스크립트 생성.
• 데이터 보존: 드롭/재생성 피하는 증분 업데이트.

주요 요약

• 자동 추적으로 수동 보일러플레이트와 스크립트 오류 제거.
• 트랜잭션 기반 단조 버전으로 일관된 상태 보장.
• 버전 관리 스크립트로 프로덕션/UAT/개발 간 핫픽스 지원.
• 테이블 기반 완전 감사 추적: 누가/언제/무엇을 적용했는지.
• 모든 ACID 준수 RDBMS에서 작동.

— Editorial Team