PostgreSQL expand-contract로 NOT NULL 컬럼을 추가하는 migration 절차

무엇을 해결하나

큰 테이블에 새 필수 컬럼을 추가할 때 구·신 버전 애플리케이션 호환성을 유지하며 backfill과 constraint 검증을 나눌 때 사용합니다.

준비할 정보

• 실제 적용할 환경과 대상 범위를 먼저 적습니다.
• 현재 상태와 기대 결과를 숫자나 예시로 준비합니다.
• 운영 데이터, 개인정보, secret은 제거하거나 안전한 placeholder로 바꿉니다.
• 변경 작업이라면 승인자, backup, rollback 가능 여부를 확인합니다.

복사해서 쓰는 프롬프트

PostgreSQL {{VERSION}} migration을 설계해줘.
현재 schema·row count: {{SCHEMA_SIZE}}
새 컬럼·기본값: {{CHANGE}}
동시 실행 app 버전: {{APP_COMPAT}}
트래픽·replication: {{TRAFFIC_REPLICA}}

nullable 추가, dual write/read, batch backfill, constraint validate, contract의 SQL과 lock 위험·중단 조건을 단계별로 제시해줘.

실행 순서

1. placeholder를 실제 환경 정보로 바꾸되 secret 값은 입력하지 않습니다.
2. 먼저 조회와 미리보기로 대상 범위, 권한, 현재 상태를 확인합니다.
3. 결과가 예상과 맞을 때만 가장 작은 단위로 실행하거나 초안을 생성합니다.
4. 변경 전후의 수치와 화면을 같은 조건에서 비교해 기록합니다.
5. 이상이 있으면 작업을 넓히지 말고 중단 조건과 rollback 절차를 따릅니다.

결과 확인

dev에서 production 유사 데이터로 lock·실행 시간을 측정하고 batch별 null count, replication lag, application error를 확인합니다. contract 전 구버전 종료를 검증합니다.

검수 결과에는 확인한 사실, 아직 확인하지 못한 가정, 다음 행동을 분리해서 남깁니다. 다른 사람이 같은 입력으로 재현할 수 있도록 환경과 확인 시각도 함께 기록하면 좋습니다.

주의사항

한 transaction에서 컬럼 추가·전체 update·NOT NULL을 몰아서 실행하지 않습니다. rollback 가능한 단계와 data가 생겨 roll-forward만 가능한 시점을 구분합니다.

AI가 만든 설명과 명령은 초안입니다. 실제 제품 버전과 조직 정책, 공식 문서를 대조하고 영향이 있는 작업은 dev나 격리 환경에서 먼저 검증하세요.