멱등 마이그레이션과 부분 실패 복구

운영 DB는 새로 만들 때처럼 한 번에 바꿀 수 없습니다. 기존 행을 보존하면서 여러 번 실행해도 같은 상태에 수렴하고, 실패 시 원인을 남긴 채 안전하게 재시도해야 합니다.

1. expand/contract 순서

1. 새 컬럼·인덱스를 호환 형태로 추가합니다.
2. 구 코드와 신 코드가 모두 읽고 쓸 수 있게 배포합니다.
3. 백필·검증 후 새 경로를 기본으로 전환합니다.
4. 사용하지 않는 옛 계약과 제약은 별도 정리 단계에서 제거합니다.

콘텐츠의 content_kind=note도 이 방식으로 구형 blog/edu CHECK를 보정합니다. 기존 데이터를 삭제하지 않고 새 계약을 추가하며, 관리 트랜잭션이 실패하면 전체 변경을 rollback합니다.

2. 시드의 멱등성

안정 키를 (language, content_kind, category_slug, slug)와 (series_slug, language, slug)처럼 명시하고 ON CONFLICT를 사용합니다. upsert 때 게시일이나 사용자가 입력한 소요시간을 무심코 덮어쓰지 않는 것도 멱등성의 일부입니다. 파일 하나가 실패하면 오류 목록을 반환하고 전체 실행을 성공으로 포장하지 않습니다.

3. 인덱스는 쿼리와 함께 설계

공개 목록은 언어·종류·발행 상태·시간으로 정렬하고, 카테고리·인기·키워드 조회는 각각 실제 조건에 맞는 인덱스를 사용합니다. 배열 키워드 검색은 GIN 인덱스와 keywords @> ARRAY[$1]::text[]를 맞춥니다. 추가 뒤에는 대표 쿼리의 EXPLAIN (ANALYZE, BUFFERS)를 staging 데이터에서 비교합니다.

4. 복구 기준

• 같은 마이그레이션을 두 번 실행해도 오류 없이 no-op입니다.
• 일부 파일 오류는 상태 코드·파일 경로·재실행 방법으로 관측됩니다.
• 실패한 트랜잭션 뒤에도 같은 명령으로 정상화할 수 있습니다.
• 백업 복원 후 스키마 보정 → 기준 데이터 → 파일 시드 순서가 유지됩니다.

데이터베이스를 직접 지우거나 볼륨을 재생성하는 방식은 복구 검증이 아닙니다. 별도 복원 대상과 읽기 전용 확인을 사용해야 합니다.