PostgreSQL 무중단 스키마 변경을 위한 실무 가이드

PostgreSQL 스키마 변경은 구버전과 신버전 애플리케이션이 함께 동작하도록 단계적으로 배포하는 것이 핵심. 데이터베이스가 켜져 있어도 요청 지연과 오류, 쓰기 중단이 발생하면 무중단으로 볼 수 없음
확장-축소(expand-contract) 패턴으로 새 구조 추가, 기존 데이터 이전, 읽기와 쓰기 전환, 검증, 기존 구조 제거를 분리. 컬럼 이름 변경도 새 컬럼과 이중 쓰기를 거쳐 여러 릴리스에 걸쳐 진행

• 스키마 변경이
  잠금을 기다리는 동안에도 뒤따르는 쿼리가 막힐 수 있음. 짧은 lock_timeout

으로 대기를 제한하고, 동시 인덱스 생성과 제약 조건의 추가/검증 분리로 차단 시간을 줄임

• 기존 데이터를 채우는
  백필은 작은 배치로 나눠 커밋하고, 중단과 재개가 가능하도록 구성. 처리 속도를 제한하며 WAL과 복제 지연, 서비스 지표를 관찰하고 최신 데이터를 덮어쓰는 경합도 방지
• 완료 기준은 SQL 종료나 잔여 행 0개가 아니라
  신구 데이터의 일치와 실제 서비스 동작 검증. 기존 컬럼 삭제는 관찰 기간 뒤 별도로 진행하며, 컬럼을 다시 만들어도 삭제된 데이터가 복원되지는 않음

무중단의 기준은 서비스 동작과 데이터 정확성

• 개발 환경에서 즉시 끝나는 SQL도 프로덕션에서는 대형 테이블, 장기 트랜잭션, 잠금 대기열, 복제본, 연결 풀, 백그라운드 작업, 동시 쓰기 때문에 장애를 일으킬 수 있음
  무중단 마이그레이션의 성공 조건은 데이터베이스의 온라인 상태보다 넓음

• 요청 오류율이 유의미하게 증가하지 않고, p95/p99 지연 시간이 합의한 범위에 있어야 함

• 핵심 업무의 쓰기가 계속되고 복제 지연이 제한되어야 함

• 데이터 손실, 중복, 잘못된 변환이 없어야 함

• 배포 중 구버전과 신버전이 모두 유효하게 동작하며, 즉흥적인 대응 없이 중단하거나 되돌릴 수 있어야 함

• 목표는 잠금을 완전히 없애는 것이 아니라
  빠른 잠금 획득과 영향 제한임

• 제한적인 잠금을 보유한 채 오래 걸리는 작업을 수행하지 않아야 함

• 각 마이그레이션에 예상 잠금, 실행 시간, I/O 특성, 호환성 유지 기간, 관측 계획, 중단 조건, 정리 단계를 지정해야 함

SQL이 실행되기 전에도 잠금 대기열이 장애를 만들 수 있음

• 여러
  ALTER TABLE

형식은 일반적인 읽기와 쓰기 모두와 충돌하는 ACCESS EXCLUSIVE

잠금을 획득함

• 마이그레이션이 장기 트랜잭션의 잠금 해제를 기다리면, 이후 애플리케이션 쿼리도 그 뒤에 줄을 설 수 있음

• 스키마 변경이 실제로 시작되지 않았어도 장애 범위가 커질 수 있음

• 위험은
  실제 실행 및 잠금 동작을 기준으로 판단해야 하며, DDL과 데이터 마이그레이션이라는 분류만으로는 부족함

• PostgreSQL 버전, 연산과 데이터 타입, 테이블/인덱스 크기, 기존 트랜잭션 길이가 영향을 줌

• 쿼리 트래픽, 연결 제한, 외래 키와 종속 객체, 복제본과 논리 디코딩 슬롯도 확인해야 함

• 테이블 스캔/재작성 여부와 디스크, WAL, I/O, CPU 여유를 함께 평가해야 함

확장-축소로 변경을 독립적인 배포 단계로 나눔

확장-축소, 또는 병렬 변경(parallel change)은 기존 계약을 한 번에 교체하지 않고 호환 가능한 새 구조를 도입한 뒤 점진적으로 이전하는 방식임
확장: 기존 코드를 깨뜨리지 않는 새 스키마를 추가함
이전: 기존 데이터를 백필하고 두 표현을 함께 지원함
전환: 읽기와 쓰기를 새 표현으로 이동함
검증: 정확성을 확인하고 충분한 프로덕션 운영 기간을 관찰함
축소: 기존 코드, 컬럼, 인덱스, 호환성 경로를 제거함

• 각 단계는
  별도 배포와 관측이 가능해야 하며, 롤링 배포 중 신구 애플리케이션 인스턴스가 함께 동작해야 함
• 축소 단계의 담당자와 일정을 미리 정하지 않으면 임시 컬럼, 이중 쓰기, 사용하지 않는 인덱스가 영구적인 복잡성으로 남음

실행 전 점검과 타임아웃 설정

잠금과 작업량을 실제 배포 버전의 문서와 테스트로 확인해야 함

• 짧은 메타데이터 변경도 충돌하는 트랜잭션 때문에 무기한 대기할 수 있음
• 테이블 스캔은 대량 I/O와 긴 실행 시간을, 재작성은 임시 디스크와 WAL, 복제 트래픽, 백업 부하를 요구할 수 있음

프로덕션 규모와 의존성을 기준으로 리허설해야 함

• 스테이징은 행 수, 인덱스 크기, 쓰기 동시성, 데이터 편향, 장기 트랜잭션을 충분히 재현하지 못하는 경우가 많음
• 프로덕션 메타데이터와 대표성 있는 복원본을 사용하고, N과 N+1 버전이 함께 동작하는지 확인해야 함
• 뷰, 함수, 트리거, 외래 키, 분석, ETL, CDC 커넥터, 내보내기, BI 도구, 수동 관리 연동을 점검해야 함

중단 조건과 권한을 실행 전에 정해야 함

• 잠금 대기, 지연 시간, 오류, 복제 지연, CPU, 디스크, WAL, 대기열 깊이에 임계값을 지정함

• DDL을 되돌려도 변환된 데이터나 외부 부작용은 복원되지 않으므로, 무조건적인 역방향 마이그레이션보다 전진 복구가 안전할 수 있음

• 곧바로 잠금을 획득해야 하는 작업에는 짧은
  lock_timeout

을 적용함

• 예시는
  lock_timeout = '2s'

, statement_timeout = '15s'

로 설정한 뒤 accounts

에 risk_tier text

를 추가함

• 값은 워크로드별로 정하되, 안전하게 잠금을 얻지 못한 경우와 정상적으로 시작한 작업에 시간이 더 필요한 경우를 구분해야 함

• 재시도는 통제된 시간대에 제한된 대기 간격으로 수행하며, 성공할 때까지 타임아웃을 늘려서는 안 됨

• 별도 세션과 명시적인 트랜잭션 범위로 설정 누출을 방지함

• 시도, 데이터베이스, 마이그레이션 버전, 애플리케이션 릴리스, 실패 원인을 기록함

• 재시도 전에 차단 세션과 장기 트랜잭션을 확인하며, 오래된
  idle in transaction

세션이 실제 결함일 수 있음

컬럼 추가와 제약 조건 검증을 분리함

• 최신 PostgreSQL에서 변동성 기본값이 없는
  NULL 허용 컬럼 추가는 대체로 빠른 메타데이터 작업이지만, 여전히 잠금이 필요함
• 최종적으로 필수 값이 될 컬럼은 단계적으로 도입함
• NULL 허용 컬럼 추가 → 기존 행을 읽고 새 필드를 쓰는 코드 배포 → 작은 배치로 백필 → NULL이 없음을 확인함
• 동등한 검사 제약 조건을 추가하고 검증한 뒤, 해당 버전에서 가장 안전한 방식으로
  NOT NULL

을 적용함

• 임시 호환성 코드는 나중에 제거하며, 스키마 확장과 전체 백필, 제약 조건 강제를 한 트랜잭션에 묶지 않음

기본값의 의미도 모든 쓰기 경로에서 확인해야 함

• 데이터베이스 기본값은 컬럼을 생략할 때 적용되며, 애플리케이션이 명시적으로
  NULL

을 쓰는 경우까지 반드시 적용되는 것은 아님

• 일부 외래 키와 검사 제약 조건은
  NOT VALID

로 추가해 기존 전체 데이터를 즉시 스캔하지 않고 신규 또는 변경 행부터 검사할 수 있음

• 예시는
  payments

에 CHECK (amount_minor >= 0) NOT VALID

를 추가함

• 기존 위반 데이터를 수정한 뒤 별도 시점에
  VALIDATE CONSTRAINT

를 실행함

• PostgreSQL ALTER TABLE 문서에 따르면, 신규 쓰기를 이미 검사하므로 별도 검증에는 추가와 검증을 한 번에 수행할 때보다 덜 제한적인 잠금을 사용할 수 있음
• 두 명령을 같은 트랜잭션에 넣으면 최초 잠금이 커밋까지 유지되어 운영상 이점이 크게 줄어듦
  CHECK (column IS NOT NULL) NOT VALID

를 추가하고 검증하는 방식은 최종 NOT NULL

변경에 앞서 기존 행의 유효성을 확보할 수 있으나, 최적화 동작은 PostgreSQL 버전별로 확인해야 함

동시 인덱스 생성의 이점과 비용

• 일반
  CREATE INDEX

는 생성 중 테이블 쓰기를 차단하므로, 큰 고부하 테이블에서는 CREATE INDEX CONCURRENTLY

의 적합성을 검토해야 함

• 예시는
  orders (customer_id, created_at DESC)

에 인덱스를 생성함

• 동시 생성은 정상 쓰기를 허용하지만 더 오래 걸리고 추가 작업을 수행하며, 일반 트랜잭션 블록 안에서 실행할 수 없음

• I/O, CPU, WAL, 복제 지연이 증가할 수 있음

• 실패하면
  유효하지 않은 인덱스가 남을 수 있으므로, 원인을 확인하고 의도적으로 제거하거나 재구축한 뒤 재시도해야 함

• 생성 후에는 유효/준비 상태, 의도한 정의, 프로덕션과 유사한 매개변수에서의 실행 계획 사용 여부를 확인함

• 쓰기 지연과 저장 공간이 허용 범위인지, 나중에 제거할 중복 또는 불필요한 인덱스가 있는지도 점검함

• 적합한 고유 인덱스를 동시 생성한 뒤
  ADD CONSTRAINT ... USING INDEX

로 고유 제약 조건이나 기본 키에 연결할 수 있음

• 인덱스 구축 중 테이블 업데이트 차단을 피하는 방법이지만, 인덱스는 이후 모든 쓰기에서 유지 비용을 발생시킴

컬럼 이름 변경은 여러 릴리스에 걸쳐 수행함

• 직접 이름을 바꾸면 기존 이름을 사용하는 코드, 작업, 연동이 깨지므로
  보조 컬럼을 통한 이전을 사용함
  users.name

을 display_name

으로 바꾸는 예시는 다섯 릴리스로 진행함
릴리스 1: NULL을 허용하는 display_name

을 추가하고 name

은 유지함
릴리스 2: 모든 변경에서 두 컬럼에 쓰고, 읽기는 name

을 유지하거나 row.display_name ?? row.name

으로 대체 경로를 둠

• 백그라운드에서 기존 값을 제한된 배치로 복사하고 진행 상황을 기록함
  릴리스 3: display_name

읽기로 전환하되 대체 경로와 모니터링을 일시적으로 유지하며 두 표현을 비교함
릴리스 4: 새 컬럼을 기준으로 삼고 기존 컬럼 쓰기를 중단한 뒤 합의된 기간 동안 관찰함
릴리스 5: 기존 컬럼 의존성을 제거한 뒤 별도 마이그레이션에서 name

을 삭제함

이중 쓰기의 책임 위치를 명확히 정해야 함

• 애플리케이션 구현은 이해하기 쉽지만 모든 쓰기 주체를 수정해야 함

• 임시 데이터베이스 트리거는 알지 못하는 쓰기 주체도 포괄하지만 숨은 동작을 추가하므로 신중한 테스트가 필요함

• 단일 이름 변경 명령보다 오래 걸리지만
  롤링 배포, 롤백, 검증을 지원함

타입 변경은 변환의 의미까지 검증함

• 일부 타입 변경은 메타데이터만 바꾸지만, 다른 변경은 테이블을 재작성하거나 애플리케이션의 전제를 깨뜨림
• 위험도가 높으면 목표 타입의
  새 컬럼을 만들고 확장-축소로 이전함
• 예시는
  events

에 occurred_at_v2 timestamptz

를 추가함

• 이중 쓰기를 배포하고, 명시적으로 테스트한 변환을 배치로 실행하며 안전하게 변환할 수 없는 값은 격리함

• 신구 표현을 비교한 뒤 기능 플래그로 읽기를 전환하고, 기존 필드 쓰기 중단과 삭제는 후속 릴리스로 분리함

문법적으로 성공한 형변환도 의미상 잘못될 수 있음

• 통화, 식별자, 시간대, JSON 구조, 열거형, 정밀도 변경에서 특히 중요함
• 금융 데이터는 반올림, 통화 단위, 과거 데이터 해석, 대사 방식을 먼저 정의해야 함
• 핀테크 MVP 구축 가이드에서도 다루듯, 원장과 금액의 의미는 초기부터 명확히 해야 함

백필을 제한 가능한 프로덕션 워크로드로 운영함

백필은 고객 트래픽과 CPU, 버퍼, I/O, WAL, 잠금, vacuum 처리 여력, 복제 대역폭을 두고 경쟁하므로 대형 테이블 전체에 무제한 업데이트를 실행하지 않음

• 안정적인 키로 작은 배치를 선택하고
  배치마다 커밋함
• 예시는
  risk_tier IS NULL

인 행을 id

순으로 최대 1,000개 선택하고 FOR UPDATE SKIP LOCKED

를 사용해 갱신함

• 실제 쿼리는 동시성과 값 도출 로직에 맞춰야 함

• 백필 작업은
  멱등성과 재개 가능성을 갖춰야 함

• 체크포인트를 저장하거나 남은 작업을 안전하게 계산하고, 배치 사이에 처리 속도를 제한함

• 서비스 지표 악화 시 자동으로 일시 중지하며, 완료/남음/실패/재시도 행 수를 노출함

• WAL, 복제 지연, 죽은 튜플, vacuum을 감시하고, 여러 작업자는 검증된 분할 방식이 있을 때만 허용함

• 오프셋 페이지네이션은 동시 변경과 큰 오프셋 때문에 진행 추적이 불안정하므로
  키 범위, 커서, 작업 선점 방식을 사용함

• 값 도출에 쓰는 원본 필드가 바뀔 수 있다면 애플리케이션 쓰기와 백필의 경합 규칙이 필요함

• 이중 쓰기 코드, 행 버전, 조건부 업데이트가 필요할 수 있음

이중 쓰기의 불일치를 측정함

이중 쓰기 자체는 일관성을 보장하지 않음

• 한 데이터베이스 트랜잭션에서 두 컬럼에 쓰는 경우와 PostgreSQL 및 별도 서비스/브로커/데이터베이스에 쓰는 경우는 다름

• 외부 전파에는 트랜잭셔널 아웃박스나 로그 기반 CDC를 검토해 업무 상태와 이벤트 발행이 독립적인 두 커밋에 의존하지 않도록 함

• CDC 가이드는 아웃박스, 멱등성, 순서, 재생, 대사를 다룸

마이그레이션 중 데이터 불일치를 계측함

• 기존 값과 변환된 새 값이 다르거나 한쪽만 채워진 경우를 추적함
• 구버전의 쓰기, 백필의 최신 값 덮어쓰기, 하위 소비자의 기존 스키마 조회를 확인함
• 불일치가 0이 되거나 모든 예외를 이해하기 전에는
  축소 단계로 넘어가지 않음

컬럼과 테이블 삭제는 마지막에 수행함

파괴적 변경은 해당 객체 사용을 중단하는 릴리스와 분리해야 함

• 읽기, 모든 쓰기, 백그라운드 작업을 중단하고 ORM 매핑과
  SELECT *

가정을 제거함

• 뷰, 함수, 트리거, 보고서, 내보내기, 연동을 점검하고 일정 기간 데이터베이스 접근을 관찰함

• 백업/보존 정책에 따라 데이터를 보관하며 종속 제약 조건과 인덱스를 의도적으로 제거함

• 실제 삭제에는 짧은 잠금 타임아웃을 사용함

• 컬럼 삭제는 즉시 모든 행을 재작성하지 않아 논리적으로 빠를 수 있지만,
  잠금과 종속 객체는 여전히 중요함

• 디스크 공간은 후속 행 재작성이나 유지보수 전까지 회수되지 않을 수 있음

• 위험도가 낮은 환경에서 먼저 폐기 예정 이름으로 바꾸면 숨은 의존성을 찾을 수 있음

• 프로덕션에서는 그 이름 변경 자체가 호환성을 깨뜨리는 DDL이므로 별도로 계획해야 함

관측은 데이터베이스, 애플리케이션, 데이터를 함께 봄

• 주요 마이그레이션에는
  전용 대시보드 또는 실행 현황 화면이 필요함
  데이터베이스 지표는 잠금 대기와 차단 세션, 활성/장기 트랜잭션과 경과 시간, CPU, I/O 지연, 버퍼 활동, 디스크 여유를 포함함
• WAL 생성/아카이브 처리량, 복제 지연과 복제 슬롯 보존량, 죽은 튜플과 vacuum 진행률도 확인함
• 연결 풀 포화와 노출 가능한 인덱스/테이블 작업 진행 상황을 추적함

애플리케이션 지표는 요청량, 오류율, 지연 백분위수, 데이터베이스 타임아웃과 직렬화 오류를 포함함

• 대기열/작업 지연, 쓰기 실패와 재시도, 신구 코드 인스턴스 수, 기능 플래그 상태를 확인함

데이터 지표는 백필 잔여 행, 신구 표현 불일치, NULL/유효하지 않은 값, 업무 수준의 대사 합계, 소비자 진행 상황과 오래된 데이터 읽기를 포함함

• 모든 지표를
  마이그레이션 단계와 릴리스 버전에 연결해야 하며, SQL 종료가 아니라 애플리케이션 동작과 데이터 정확성 검증을 완료 기준으로 삼음

프로덕션과 유사한 조건에서 호환성을 시험함

• 정책이 허용하면 보호되고 적절히 익명화된 최근 프로덕션 스냅샷을 사용함
• 테이블/인덱스 크기, 현실적인 데이터 분포, 동시 읽기/쓰기, 장기 트랜잭션을 재현함
• 복제본 또는 대표성 있는 WAL 소비, 제한된 디스크/I/O 여유, N과 N+1의 동시 실행을 포함함
• 재시도, 취소, 부분 완료도 테스트함

잠금 획득 시간과 작업 실행 시간을 별도로 측정함

• 유휴 스테이징에서 빠르게 끝났다는 사실만으로 바쁜 프로덕션 테이블의 안전성을 판단하기 어려움

• CI의
  호환성 테스트 순서는 다음 조합을 포함해야 함

• 기존 애플리케이션과 기존 스키마를 테스트함

• 기존 애플리케이션과 확장된 스키마를 테스트함

• 새 애플리케이션과 확장된 스키마를 테스트함

• 이중 쓰기 중 신구 애플리케이션의 혼합 실행을 테스트함

• 백필 후 새 애플리케이션을 테스트함

• 축소 후 새 애플리케이션을 테스트함

• 이 순서는 마이그레이션과 애플리케이션을
  동시에 배포해야만 동작하는 오류를 찾아냄

롤백과 전진 복구의 경계를 미리 정함

확장 단계에서는 기존 스키마가 남아 있어 애플리케이션 롤백이 대체로 쉬움

• 이중 쓰기 중에도 롤백이 필요하다면 기존 표현에 계속 유효한 값을 기록해야 함

파괴적 축소 이후에는 복구가 훨씬 어려워짐

• 컬럼을 다시 만들어도 데이터는 돌아오지 않으며, 전체 백업 복원은 이후 발생한 프로덕션 쓰기를 버릴 수 있음

• 복구 수단으로 새 읽기 경로의 기능 플래그 비활성화, 백필 중단/감속, 호환성 수정의 전진 배포를 준비함

• 멱등 변환 재실행, 보존 원본이나 아카이브에서 선택적 데이터 복원도 고려함

• 운영상 롤백이 더는 필요하지 않을 때까지 파괴적 정리를 미룸

쉽게 되돌릴 수 없는 시점을 문서화하고, 그 경계를 넘기 전에 명시적인 승인을 받아야 함

지속적 배포에서 담당자와 실행 도구를 명확히 함

• 위험한 변경은 SQL 지식 부족뿐 아니라
  책임과 절차의 모호함에서도 발생함
• 기술 동작 책임자, 애플리케이션 호환성 책임자, 고위험 작업을 검토할 데이터베이스/플랫폼 담당자를 지정함
• 중단 권한이 있는 운영자, 정리 담당자와 기한, 다음 단계 진입에 필요한 증거를 정함

마이그레이션 도구는 변경 불가능한 버전 이력, 단일 실행 주체 또는 자문 잠금, 모의 실행/SQL 검토를 지원해야 함

• 금지 연산 검사, 마이그레이션별 트랜잭션 제어, 잠금/실행 타임아웃, 구조화 로그와 지표가 필요함

• 스키마 변경과 장시간 데이터 작업을 분리해야 함

• 모든 애플리케이션 복제본이 시작할 때 마이그레이션을 경쟁적으로 실행하게 하지 않음

• 동시성을 통제하고 상태를 확인할 수 있는
  별도 릴리스 작업으로 수행해야 함

반복되는 실패 패턴

애플리케이션 시작 시 자동 DDL은 복제본 간 경쟁을 만들고 위험한 변경을 서비스 복구와 결합하므로 별도 릴리스 작업으로 분리함
모든 단계를 하나의 트랜잭션으로 묶으면 장기 백필과 제약 조건 검증이 잠금과 행 버전을 유지하고 진행을 전부 성공 또는 전부 실패로 만듦

• 잠금 타임아웃이 없으면 대기열이 생기며, 고부하 테이블의 일반 인덱스 생성은 구축 시간 동안 쓰기를 멈춤
• 같은 배포에서 파괴적으로 이름을 바꾸면 롤링 배포 중 구버전과 백그라운드 작업이 실패함
• 속도 제한 없는 백필은 고객 트래픽, 복제본, vacuum이 사용할 자원을 빼앗음
  잔여 행 0개만으로 성공을 선언하면 잘못 변환된 값을 놓칠 수 있으므로 업무 불변 조건과 신구 표현을 대조해야 함
• 축소를 끝내지 않으면 임시 호환성 코드가 영구 구조가 되므로 확장 전에 정리 책임을 지정함

실무 실행 순서와 완료 조건

변경 분류 → 리허설 → 확장 → 호환성 코드 배포 순으로 준비함

• 잠금, 스캔/재작성, 크기, 의존성, 호환성, 업무 중요도를 분류함
• 실제 규모와 동시 트래픽에서 실행 시간, 자원, WAL, 잠금, 실패 동작을 기록함
• 제한된 타임아웃으로 최소한의 하위 호환 스키마를 추가하고, 양쪽 스키마 지원과 기능 플래그, 계측, 혼합 버전 검증을 준비함

백필 → 전환 → 관찰 → 축소 순으로 마무리함

• 멱등적이고 재개 가능하며 속도를 제한할 수 있는 작업으로 데이터를 이전함

• 읽기나 쓰기를 점진적으로 옮기고 결과를 비교하면서 빠른 애플리케이션 수준 롤백을 유지함

• 대표성 있는 트래픽과 운영 기간을 관찰해 알지 못했던 소비자가 기존 구조를 사용하지 않는지 확인함

• 백업과 보존 상태를 검증한 뒤 호환성 코드와 기존 스키마를 별개의 통제된 변경으로 제거함

• 이 방식은 서비스 분리, 데이터 소유권 변경, 레거시 코드의 점진적 교체와 함께 진행하는 소프트웨어 현대화 및 마이그레이션에도 적용할 수 있음

• 안전한 PostgreSQL 마이그레이션의 기반은
  호환성과 검증 증거이며, 개별 SQL 명령보다 릴리스 순서가 더 중요함

• 체계적인 확장-축소 절차는 데이터베이스 변경을 정기 점검 시간에만 수행하는 작업에서 일상적인 지속적 배포로 바꿀 수 있음

댓글과 토론