Django 무중단 마이그레이션: Concurrent Index와 NOT VALID를 나누는 이유
코드 배포는 몇 초 만에 끝났는데 migrate가 쓰기 요청을 막는다. 테이블이 커지면 스키마 변경은 단순한 배포 부속 단계가 아니다. 잠금, 기존 데이터 검증, 실패 후 재개 상태를 가진 운영 작업이다.
기준: Django 5.2 · PostgreSQL 17. 예제의 앱·모델·의존 마이그레이션 이름은 실제 프로젝트에 맞춰 바꿔야 한다. “무중단”은 도구가 자동 보장하는 속성이 아니다.
먼저 코드 호환 기간을 만든다
컬럼 이름을 바꾸거나 필수 필드를 추가할 때는 구버전 앱과 신버전 앱이 함께 실행되는 시간을 고려한다. 새 구조를 추가하고, 양쪽 구조를 이해하는 코드를 배포하고, 데이터를 채운 뒤, 읽기 경로를 전환하고, 마지막에 옛 구조를 제거하는 순서가 기본이다.
DB 변경을 되돌리는 것과 코드 롤백은 다르다. 구버전 코드가 새 스키마에서 실행 가능한지 확인해야 한다. 배포 중에 데이터가 새 구조로만 기록되기 시작했다면 단순 컬럼 삭제로 원상 복구할 수 없다.
인덱스는 Concurrent 작업으로 분리한다
from django.db import migrations, models
from django.contrib.postgres.operations import AddIndexConcurrently
class Migration(migrations.Migration):
atomic = False
dependencies = [("orders", "0041_previous")]
operations = [
AddIndexConcurrently(
model_name="order",
index=models.Index(
fields=["tenant", "-created_at", "-id"],
name="order_feed_idx",
),
),
]
PostgreSQL의 concurrent index 생성은 트랜잭션 블록 안에서 실행할 수 없으므로 atomic = False가 필요하다. 다른 DDL이나 데이터 변경을 잔뜩 섞지 않고 실패 범위를 작게 유지한다. Django PostgreSQL 마이그레이션 연산
CONCURRENTLY는 잠금이 전혀 없다는 뜻이 아니다. 쓰기를 허용하면서 인덱스를 만들기 위한 추가 스캔과 대기가 발생하고 오래된 트랜잭션의 종료를 기다릴 수 있다. 실패하면 invalid index가 남을 수 있으므로 재실행 전 카탈로그와 작업 상태를 확인한다. 같은 이름이 있다는 사실만으로 유효한 인덱스가 만들어졌다고 판단하면 안 된다. PostgreSQL concurrent index 주의점
체크 제약 추가와 검증도 나눈다
기존 모든 행을 검사하는 비용을 한 번에 치르고 싶지 않다면 PostgreSQL의 NOT VALID 체크 제약을 고려할 수 있다. 기존 데이터의 검증을 나중으로 미루며, 새로 삽입·갱신하는 행에는 제약이 적용된다.
from django.db import migrations, models
from django.contrib.postgres.operations import AddConstraintNotValid
class Migration(migrations.Migration):
dependencies = [("orders", "0042_order_feed_idx")]
operations = [
AddConstraintNotValid(
model_name="order",
constraint=models.CheckConstraint(
condition=models.Q(total__gte=0),
name="order_total_nonnegative",
),
),
]
기존 위반 행을 조사·수정한 뒤 별도 마이그레이션에서 ValidateConstraint("order", "order_total_nonnegative")를 수행한다. 두 작업을 같은 atomic migration에 넣으면 비용 분리의 목적이 사라진다. Django 문서는 두 연산을 별도 마이그레이션으로 수행하도록 안내한다. 제약 검증 연산
이 예제는 total이 NULL을 허용하지 않는 모델을 전제로 한다. SQL CHECK에서 NULL의 의미는 “음수가 아님”과 “값이 반드시 있음”이 다르다. 필수 값 보장까지 필요하면 NULL 허용 여부를 별도로 설계한다. NOT VALID를 모든 제약 종류에 통용되는 옵션처럼 사용하지도 않는다.
운영 실행 전에 중단 조건을 정한다
잠금 획득을 오래 기다리는 DDL은 뒤따르는 요청의 대기를 키울 수 있다. 프로젝트 배포 연결에 맞는 lock timeout과 statement timeout을 정하고, 실패하면 무작정 재시도하지 않도록 한다. 실제 값은 쿼리 지연 목표와 테이블 규모에 따라 정한다.
검증 환경에서 운영과 비슷한 크기의 데이터와 오래 열린 트랜잭션을 준비한다. 작업 중 읽기·쓰기 지연, 잠금 대기, 복제 지연, 디스크 사용량을 관찰한다. 성공뿐 아니라 작업 취소 후 상태도 확인한다.
DB 상태와 Django 상태를 일치시킨다
수동 SQL로 만든 인덱스나 컬럼을 Django migration state가 모르면 다음 makemigrations가 예상치 못한 변경을 만들 수 있다. 가능한 한 전용 연산을 쓰고, SeparateDatabaseAndState가 필요한 경우에는 DB 연산과 상태 연산을 함께 검수한다. 잘못 맞추면 이후 마이그레이션이 깨질 수 있다. Migration Operations
스키마 변경의 완료 증거는 명령의 종료 코드만이 아니다. 실제 인덱스 유효성, 제약 검증 상태, 신·구 코드 호환성, 운영 지연까지 함께 확인해야 한다.
댓글
댓글 쓰기