새 개발자가 합류해서 로컬 개발환경을 세팅합니다. git clone까지는 잘 됐는데 앱이 실행되지 않습니다. 테이블 컬럼이 맞지 않는다는 에러입니다. 시니어한테 물어보니 "지난주에 컬럼 추가했어요, 직접 ALTER하세요"라고 합니다. 문서도 없고, 언제 무엇이 바뀌었는지도 모릅니다. 마이그레이션 도구 없이 스키마를 관리하면 팀 규모가 커질수록 이런 혼란이 반복됩니다.

확대

마이그레이션 없이 스키마를 관리하면 생기는 일

팀에서 마이그레이션 도구 없이 스키마를 변경하면 다음과 같은 문제가 발생합니다.

• 환경 불일치: 개발자 A는 컬럼을 추가했지만 개발자 B는 모름
• 재현 불가: 새 개발자가 합류했을 때 정확한 스키마 상태를 알 수 없음
• 배포 사고: 운영 DB에 변경사항 적용 순서가 잘못되어 데이터 손상
• 롤백 불가: 어떤 변경이 언제 이루어졌는지 추적이 어려움

Flyway vs Liquibase 비교

두 도구 모두 마이그레이션 이력을 DB 테이블에 저장하고 체크섬으로 변경 여부를 감지합니다. 선택 기준은 팀의 SQL 친숙도와 멀티 DBMS 지원 필요 여부입니다.

Flyway — SQL 파일 기반 버전 관리

Flyway는 가장 단순하고 직관적인 마이그레이션 도구입니다. SQL 파일에 버전 번호를 매겨 관리하며, flyway_schema_history 테이블에 실행 이력과 체크섬을 기록합니다.

파일 명명 규칙은 V{버전}__{설명}.sql 형식이며, R__ 접두사 파일은 내용이 변경될 때마다 재실행됩니다(뷰, 함수 재정의에 유용).

migrations/ 디렉토리 예시입니다.

• V1__create_users_table.sql
• V2__add_email_to_users.sql
• V3__create_orders_table.sql
• V3.1__add_order_status_index.sql
• R__create_user_summary_view.sql (반복 실행)

CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(100) NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

실행 완료 또는 조회 결과가 표시됩니다.

ALTER TABLE users ADD COLUMN email VARCHAR(255);
ALTER TABLE users ADD CONSTRAINT users_email_unique UNIQUE (email);

CREATE TABLE orders (
    id           BIGSERIAL PRIMARY KEY,
    user_id      BIGINT NOT NULL REFERENCES users(id),
    total_amount NUMERIC(12, 2) NOT NULL,
    status       VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_orders_user_id ON orders(user_id);

Flyway가 flyway_schema_history 테이블에 기록한 이력을 조회하면 다음과 같습니다. 체크섬 컬럼을 통해 이미 적용된 파일이 수정되었는지 감지합니다.

SELECT version, description, checksum, success, installed_on
FROM flyway_schema_history
ORDER BY installed_rank;

한 번 적용된 마이그레이션 파일을 수정하면 Flyway는 체크섬 불일치를 감지하고 실행을 즉시 중단합니다. 이미 적용된 파일은 절대 수정하지 않고 새 버전 파일을 추가해야 합니다.

Spring Boot 통합은 application.yml에 다음을 추가하면 애플리케이션 시작 시 자동으로 마이그레이션을 적용합니다.

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    validate-on-migrate: true

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

Liquibase — XML/YAML 기반 changeset 방식

Liquibase는 XML, YAML, JSON, SQL 형식으로 변경사항을 표현할 수 있습니다. 각 changeset에 rollback 블록을 함께 정의할 수 있어, Flyway 대비 롤백 전략을 구조적으로 관리할 수 있습니다.

databaseChangeLog:
  - changeSet:
      id: 1
      author: alice
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: BIGINT
                  autoIncrement: true
                  constraints:
                    primaryKey: true
              - column:
                  name: name
                  type: VARCHAR(100)
                  constraints:
                    nullable: false
              - column:
                  name: created_at
                  type: TIMESTAMP WITH TIME ZONE
                  defaultValueComputed: NOW()
                  constraints:
                    nullable: false

  - changeSet:
      id: 2
      author: bob
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: email
                  type: VARCHAR(255)
        - addUniqueConstraint:
            tableName: users
            columnNames: email
            constraintName: users_email_unique
      rollback:
        - dropColumn:
            tableName: users
            columnName: email

Prisma Migrate

Prisma는 ORM과 마이그레이션이 통합된 방식을 제공합니다. prisma migrate dev로 개발 환경에서 마이그레이션 파일을 생성하고, prisma migrate deploy로 운영 환경에 적용합니다.

npx prisma migrate dev --name add_email_to_users
npx prisma migrate deploy
npx prisma migrate status

위 명령으로 생성된 마이그레이션 파일의 내용은 다음과 같습니다.

ALTER TABLE "users" ADD COLUMN "email" TEXT;
ALTER TABLE "users" ADD CONSTRAINT "users_email_unique" UNIQUE ("email");

flyway migrate(또는 liquibase update) 한 번이면 팀 전원의 DB가 같은 스키마로 맞춰집니다. 그런데 도구는 "이 DB에 무엇이 이미 적용됐고 무엇을 더 실행해야 하는지"를 어떻게 알까요? 비밀은 도구가 DB 안에 만들어 두는 적용 이력 테이블과, 매 실행마다 그 이력과 파일을 대조하는 5단계 절차에 있습니다. 이 흐름을 알면 체크섬 오류·부분 적용·버전 충돌이 어느 단계에서 나는지 바로 짚을 수 있습니다.

[CI / 앱 시작]  flyway migrate
   │
   ① 버전 파일 스캔·정렬   (migrations/ 의 V1__, V2__, V3__ … 을 버전 번호 순으로 나열)
   │
   ② 적용 이력 테이블 조회  (flyway_schema_history 에서 '어디까지 적용됐는지' + 각 파일 체크섬 읽기)
   │
   ③ 미적용분만 순차 실행   (이력에 없는 버전만, 낮은 버전 → 높은 버전 순으로 DDL 실행)
   │                        → 각 파일을 트랜잭션으로 감싸 실행(DDL 트랜잭션 지원 DB)
   │
   ④ 이력 기록             (성공한 파일마다 version · checksum · success=true 를 이력에 추가)
   │
   ⑤ 실패 시 중단          (한 파일이 실패하면 그 지점에서 멈춤 → 이후 버전 미적용, 실패 행은 dirty)
   ▼
[결과]  개발·스테이징·운영이 같은 순서로 같은 스키마에 수렴

각 단계에서 무슨 일이 일어나고, 어디서 어긋나나:

즉 마이그레이션 도구의 핵심은 ②이력 대조와 ④이력 기록입니다 — "어디까지 적용됐는지"를 DB가 스스로 기억하기에 개발·스테이징·운영이 같은 순서로 수렴합니다. 그래서 사고는 대개 코드가 아니라 규율에서 납니다: 적용된 파일 수정(②체크섬), 팀 간 버전 번호 중복(①), down을 안 만들어 되돌릴 수 없는 상태(⑤). 문제가 생기면 flyway_schema_history의 success 컬럼과 체크섬부터 보면 대부분 원인이 잡힙니다.

배포 시간이 새벽 2시입니다. 컬럼 이름을 변경하는 마이그레이션을 실행했는데 5분이 지나도 끝나지 않습니다. 그 사이 서비스 API가 타임아웃으로 응답하지 않습니다. 수백만 건의 대용량 테이블에서 ALTER TABLE이 잠금을 잡고 있었던 겁니다. 결국 마이그레이션을 강제 중단했고 데이터 정합성이 깨졌습니다. DDL 변경은 올바른 순서와 패턴 없이 운영 환경에 적용하면 장애로 이어집니다.

확대

DDL 변경의 위험성

운영 환경에서 DDL(CREATE, ALTER, DROP) 변경은 세 가지 위험을 가집니다. 첫째, ALTER TABLE은 대용량 테이블에서 수분간 테이블 잠금을 유발합니다. 둘째, 컬럼 삭제나 타입 변경은 롤백이 불가능합니다. 셋째, 구버전 애플리케이션이 삭제된 컬럼을 참조하면 즉시 오류가 발생합니다. 이 세 가지 문제를 모두 해결하는 패턴이 Expand-Contract입니다.

Expand-Contract 패턴

운영 중인 서비스에서 스키마를 변경할 때는 Expand-Contract(확장-수축) 패턴을 사용합니다. 이 패턴은 하나의 변경을 3단계로 나눠서 서비스 중단 없이 진행합니다.

시나리오: users.username 컬럼을 users.display_name으로 이름 변경

3단계로 나눕니다. 1단계에서는 새 컬럼을 추가하면서 기존 컬럼은 그대로 유지합니다. 그다음 애플리케이션 코드를 display_name에 쓰고 username에서 읽는 호환 로직으로 배포합니다. 2단계에서는 기존 데이터를 새 컬럼으로 이전하고, display_name만 사용하는 코드로 전환 배포합니다. 3단계에서는 구 컬럼이 더 이상 참조되지 않음을 확인한 뒤 삭제합니다.

ALTER TABLE users ADD COLUMN display_name VARCHAR(100);

UPDATE users SET display_name = username WHERE display_name IS NULL;

ALTER TABLE users DROP COLUMN username;

NOT NULL 컬럼 추가 시 주의사항

기존 데이터가 있는 테이블에 NOT NULL 컬럼을 즉시 추가하면 기존 행이 NULL 상태가 되어 제약 위반 오류가 발생합니다. 올바른 방법은 3단계로 나누는 것입니다.

ALTER TABLE orders ADD COLUMN shipping_address TEXT;

UPDATE orders SET shipping_address = '주소 미등록' WHERE shipping_address IS NULL;

ALTER TABLE orders ALTER COLUMN shipping_address SET NOT NULL;

-- (실패) 기존 행 shipping_address가 NULL인 상태에서 바로 NOT NULL
ALTER TABLE orders ALTER COLUMN shipping_address SET NOT NULL;

-- (안전) 1) nullable로 컬럼 추가  2) 기존 행 백필  3) 그제서야 NOT NULL
ALTER TABLE orders ADD COLUMN shipping_address TEXT;          -- 1
UPDATE orders SET shipping_address = '주소 미등록'
  WHERE shipping_address IS NULL;                              -- 2
ALTER TABLE orders ALTER COLUMN shipping_address SET NOT NULL; -- 3

-- 백필 누락 검증: 0이어야 3단계가 성공한다
SELECT count(*) FROM orders WHERE shipping_address IS NULL;

-- 즉시 SET NOT NULL
ERROR:  column "shipping_address" of relation "orders" contains null values

-- 3단계 후 검증
 count
-------
     0

PostgreSQL 11 이상에서는 DEFAULT 값이 있는 NOT NULL 컬럼을 즉시 추가해도 테이블 재작성 없이 처리됩니다.

ALTER TABLE orders
    ADD COLUMN shipping_address TEXT NOT NULL DEFAULT '주소 미등록';

대용량 테이블 인덱스 CONCURRENTLY

일반 CREATE INDEX는 테이블 전체 잠금을 걸어 수백만 건 이상의 테이블에서는 수분간 서비스가 중단될 수 있습니다. 운영 환경에서는 항상 CONCURRENTLY 옵션을 사용합니다.

CONCURRENTLY는 트랜잭션 블록 내에서 사용할 수 없으므로 BEGIN/COMMIT 밖에서 단독으로 실행해야 합니다. 실패 시 INVALID 상태의 인덱스가 남을 수 있으며, 이 경우 DROP INDEX CONCURRENTLY로 정리한 후 재시도합니다.

CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);

DROP INDEX CONCURRENTLY idx_orders_user_id;

Flyway에서 무중단 마이그레이션 — 배치 업데이트 예시

컬럼을 추가한 뒤 기존 데이터를 채울 때 한 번에 전체 행을 업데이트하면 테이블 잠금이 발생할 수 있습니다. 아래는 1,000건씩 나눠서 처리하는 배치 방식입니다.

ALTER TABLE users ADD COLUMN tier VARCHAR(20);

DO $$
DECLARE
    batch_size INT := 1000;
    updated    INT;
BEGIN
    LOOP
        UPDATE users
        SET tier = 'standard'
        WHERE id IN (
            SELECT id FROM users
            WHERE tier IS NULL
            ORDER BY id
            LIMIT batch_size
        );

        GET DIAGNOSTICS updated = ROW_COUNT;
        EXIT WHEN updated = 0;
        PERFORM pg_sleep(0.1);
    END LOOP;
END $$;

ALTER TABLE users ALTER COLUMN tier SET NOT NULL;
ALTER TABLE users ALTER COLUMN tier SET DEFAULT 'standard';

체크리스트: 운영 마이그레이션 전 확인 사항

앞의 배치 백필 예제는 한 번에 다 바꾸지 말고 수천 건씩이라고 했습니다. 왜 그래야 하는지 한 단계 더 들어가 보면, 마이그레이션이 락을 안 잡아도 다른 방식으로 서비스를 흔들 수 있음을 알게 됩니다.

• UPDATE는 행을 덮어쓰지 않습니다: PostgreSQL은 MVCC라 한 행을 UPDATE하면 새 버전을 쓰고 옛 버전을 dead tuple로 남깁니다. 5천만 행을 한 UPDATE로 바꾸면 5천만 개의 dead tuple이 한꺼번에 생깁니다. 테이블은 순식간에 부풀고, 이후 순차 스캔이 죽은 공간까지 읽느라 느려집니다.
• 긴 트랜잭션은 autovacuum을 무력화합니다: 그 거대한 UPDATE가 도는 동안(그리고 커밋될 때까지) xmin horizon이 묶여 autovacuum이 dead tuple을 회수하지 못합니다. 끝난 뒤에도 autovacuum이 수천만 행을 정리하느라 몇 시간 CPU·I/O를 잡아, 그 시간 내내 운영 쿼리와 자원을 다툽니다.
• 복제본이 뒤처집니다: 대량 변경은 그만큼의 WAL을 폭발적으로 만들고, 복제본은 이를 대체로 직렬로 재생합니다. 그 결과 read replica가 몇 분씩 지연돼, 쓰고 바로 읽기가 복제본으로 가는 요청에서 stale read가 번집니다(Master-Slave 복제(Replication) 구축과 DB 고가용성(HA) 아키텍처). 마이그레이션 하나가 읽기 경로 전체의 신선도를 흔드는 것입니다.
• 그래서 배치로 나눕니다: 수천 건씩 끊어 커밋하면 트랜잭션이 짧아 xmin horizon이 자주 풀리고, autovacuum이 사이사이 dead tuple을 회수하며, WAL과 복제 지연이 완만해집니다. 배치 사이 짧은 pg_sleep은 복제본과 autovacuum이 따라올 여유를 줍니다. 느리게 하는 게 아니라 흔들지 않게 하는 것입니다.

핵심은, 마이그레이션의 위험이 락만이 아니라는 점입니다. 락을 피해도 dead tuple·autovacuum·복제 지연이라는 청구서가 뒤따라오며, 배치는 그 청구서를 잘게 쪼개는 장치입니다.