--- title: Runbook — MIGRATION_FAILED (DB 마이그레이션 실패) category: INTERNAL error_codes: [MIGRATION_FAILED] severity: P1 owner: oncall last_updated: 2026-11-07 status: 운영 --- # Runbook: MIGRATION_FAILED (`runbook://migration/failed`) ## 증상 - 컨테이너가 코드 70으로 끝난다(마이그레이션 실패 종료). - 구조화 로그 `error.code=MIGRATION_FAILED`, `startup.phase=migration`. - 앱이 뜨기를 거부한다(fail-fast). - JPA capability 어댑터가 활성화를 거부한다. 그 `capability_schema_registry.lifecycle_state`가 `ACTIVE`가 아니다. ## 진단 1. rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지 않는다. 2. `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`에서 정확한 stream을 찾는다. stream마다 `location`과 `history-table`이 따로 있다. 넓은 `classpath:db/migration` 스캔으로 소유를 짐작하지 않는다. 3. 권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 stream 상태를 남긴다. ```sql select installed_rank, version, description, success from order by installed_rank; select capability_id, installation_origin, core_epoch, feature_revision, lifecycle_state from capability_schema_registry where capability_id = ''; ``` 4. 성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만 비교한다. 상관없는 relation은 지우지 않는다. 5. 실패를 분류한다(Classify the failure). - 락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는 마이그레이션은 자기 `SET LOCAL lock_timeout`(5 s, SQLState `55P03` `lock_not_available`)이 지나면 포기하고 통째로 롤백한다. 그래서 이력은 그 버전 바로 아래에서 끝난다. 막는 쪽은 그 테이블을 건드린 뒤 아직 열려 있는 트랜잭션이다. 흔히 idle-in-transaction 세션이다. 그 테이블에 쥔 락으로 찾는다(``은 실패한 문장이 잠그는 테이블이다. `REFERENCES`면 참조하는 테이블도 본다). ```sql SELECT DISTINCT a.pid, a.state, a.xact_start, a.query FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE l.relation = '
'::regclass AND l.granted AND a.pid <> pg_backend_pid() ORDER BY a.xact_start; ``` `query`는 그 세션의 마지막 문장일 뿐 테이블을 건드린 문장이 아니므로, 거기서 테이블 이름을 찾지 않는다. 대신 긴 트랜잭션을 모두 나열하면 막는 쪽 옆에 상관없는 것(리포트, 배치)도 나온다. 막는 쪽을 끝낸 뒤 다시 돌린다(`docs/jpa/migration-guide.md` "Bound the lock wait"). - SQL·데이터 전제 조건: 전제 조건을 드러내는 새 forward 마이그레이션을 만든다. 중복된 outbox 순서 키가 V21(`ux_outbox_event_aggregate_order`)을 막는 것이 알려진 경우다. `outbox-dead-letter.md` §8로 정리하고 다시 돌린다. 마이그레이션은 그대로 둔다. - checksum 불일치: repair를 생각하기 전에 배포한 산출물과 이미 적용된 스크립트를 비교한다. - 동시 인덱스 마이그레이션 실패(Flyway가 트랜잭션 밖에서 돌린 `CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`): unique 인덱스의 중복 값, 교착, `statement_timeout`, 또는 열린 트랜잭션을 기다리다 취소된 문장이다. 트랜잭션 밖이라 아무것도 롤백되지 않았다. 마이그레이션은 무효 인덱스와, 그 버전의 `success = false` 이력 행을 남겼다. 그 행이 사라질 때까지 뒤의 배포는 모두 검증에서 실패한다("Detected failed migration to version …"). 인덱스만 지워서는 풀리지 않는다. 아래 「실패한 동시 인덱스 마이그레이션 복구」를 따른다. - 연결·TLS 실패: Flyway 이력을 바꾸지 않고 전송이나 자격 증명을 고친다. ## 조치 1. forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을 그 정확한 이력 테이블로 다시 돌린다. 2. 한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임 어댑터를 꺼 둔다. 3. 마이그레이션이 성공하면 확인한다. - 이력에 기대한 버전의 성공 행만 있다. - `core_epoch`와 `feature_revision`이 readiness registry와 같다. - 표시가 `INSTALLED_INACTIVE`다. - 소유 객체와 제약이 있다. 4. 맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를 `ACTIVE`로 바꾼다. 애플리케이션 코드를 끄거나 되돌리면 표시가 `INSTALLED_INACTIVE`로 바뀐다. 이력이나 소유 데이터는 지우지 않는다. 5. 승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음). ```bash ./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain ``` 6. 실패한 revision, stream·이력 테이블, 근본 원인, 복구 마이그레이션, 걸린 시간, 검증 산출물을 장애 기록에 남긴다. 하지 않을 것: - 이미 적용된 마이그레이션을 고친다. - 검증을 통과시키려고 Flyway 이력을 지우거나 다시 쓴다. 예외는 하나다. 실패한 동시 인덱스 마이그레이션의 실패 행을 아래 「실패한 동시 인덱스 마이그레이션 복구」대로 지운다. 그 행 말고는 아무것도 지우지 않는다. - checksum의 출처가 증명되고 검토되기 전에 `flyway repair`를 돌린다. - 첫 대응으로 `clean`, 파괴적 롤백, 스키마 전체 복원을 쓴다. - 마이그레이션과 어댑터 readiness가 성공하기 전에 capability를 `ACTIVE`로 표시한다. 장애 중에 커밋 결과를 알 수 없었으면, 업무 작업을 다시 하기 전에 애플리케이션의 `OperationId`·멱등성 참조로 맞춘다. 결과를 모르는 커밋을 그냥 다시 시도하지 않는다. ## 실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration) 이 runbook이 Flyway 이력을 바꾸는 유일한 경우다(소유자 결정, 2026-11-06). Flyway가 트랜잭션 밖에서 돌린 동시 인덱스 문장 하나만 담은 마이그레이션에 쓴다. 가이드가 요구하는 `executeInTransaction=false`로 돌렸거나, `CREATE`/`DROP INDEX CONCURRENTLY`라서 Flyway가 알아서 그렇게 돌린 경우다(`docs/jpa/migration-guide.md` "Concurrent index builds"). 그리고 stream 이력 테이블의 이 버전 행이 `success = false`여야 한다. 다른 문장을 섞은 마이그레이션은 그 문장을 이미 커밋했다. 그 상태는 DB 소유자와 함께 다시 맞춘다. 1. 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면 빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다. ```sql SELECT pid, relid::regclass AS table_name, index_relid::regclass AS index_name, phase FROM pg_stat_progress_create_index WHERE datname = current_database(); ``` 2. 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지 않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는 자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에 한다. 3단계의 `DROP INDEX CONCURRENTLY`도 같은 트랜잭션을 기다린다. 3. 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다. `CREATE [UNIQUE] INDEX CONCURRENTLY`가 이름 붙인 인덱스, 또는 `REINDEX … CONCURRENTLY`가 만든 사본이다. 사본은 인덱스 이름 끝에 `_ccnew`(또는 `_ccold`)가 붙는다 (`docs/jpa/runbooks.md` "An invalid index exists"가 그 목록을 준다). `BEGIN` 안이 아니라 따로 돌린다. `CONCURRENTLY`는 트랜잭션 블록을 거부한다. **실패한 문장이 `DROP INDEX CONCURRENTLY`면 이 단계를 건너뛴다.** 그것이 남긴 무효 인덱스는 마이그레이션이 지우는 인덱스이고, 5단계의 배포가 같은 문장을 돌려 그것을 지운다. 먼저 손으로 지우면 그 문장이 `42704` ("index … does not exist")로 실패하고 새 실패 행을 남긴다. ```sql DROP INDEX CONCURRENTLY IF EXISTS ; ``` 4. stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다. ``은 진단 쿼리가 보여 주는 실패 행의 `version` 칸이다(`V22_1__…`이면 `22.1`). 정확히 한 행을 지워야 한다. 한 행도 지우지 않으면 이 절이 다루는 실패가 아니므로 다시 분류한다. ```sql DELETE FROM WHERE version = '' AND NOT success; ``` 5. 다시 배포한다. Flyway가 같은 마이그레이션을 처음부터 돌린다. 인덱스를 만들거나, 다시 만들거나, 실패한 삭제가 남긴 인덱스를 지운다. 실패 행은 한 번도 적용되지 않은 버전의 기록이다. 그래서 지워도 적용된 모든 버전의 순서와 checksum은 그대로다. 이 일에 `flyway repair`를 쓰지 않는다. repair는 남은 행의 checksum과 description도 디스크의 스크립트에 맞춰 다시 쓰므로, checksum 불일치가 담은 증거를 지운다. `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`가 위의 SQL 블록 셋을 이 파일에서 읽어, 이 절이 다루는 문장마다 실제 PostgreSQL에 돌린다. 중복으로 실패하는 unique 빌드, 열린 트랜잭션을 기다리다 취소된 재빌드와 삭제다. 1~4단계를 차례로 돌리고(3단계는 빌드와 재빌드만), 다음 배포가 무효 인덱스 없이 그 버전을 적용하며 앞 버전의 checksum은 바뀌지 않는다. ## 에스컬레이션 - P1 즉시: 필요한 애플리케이션 revision이 ready가 되지 못한다. - Flyway 이력 repair, 파괴적 DDL, 시점 복구(PITR), primary failover 전에 DB 소유자에게 넘긴다. - R3 복원·PITR과 failover 예행연습에는 대상과 비슷한 백업 구성이 필요하다. 로컬 Testcontainers 증거로 대신하지 않는다. --- 이 runbook은 forward 방향만 다룬다. 감사 근거는 검토한 마이그레이션 산출물과 CI의 readiness lane JUnit 결과다.