문제 (재리뷰 round8 RR8-03-01) - migration-failed.md "Recover a failed concurrent index migration"은 CREATE·DROP·REINDEX 동시 문장 셋을 대상으로 두고, 2단계에서 "빌드가 남긴 무효 인덱스를 지운다"고 한다. 실패한 DROP INDEX CONCURRENTLY가 남긴 무효 인덱스는 그 마이그레이션이 지우려던 인덱스다. 절차대로 지우고 실패 행을 지운 뒤 다시 배포하면 같은 문장이 42704(index does not exist)로 실패하고 실패 행이 다시 생긴다. 운영자는 처음과 같은 막힌 상태로 돌아간다. - 고치다 같은 절에서 하나 더 찾았다. 2단계(DROP INDEX CONCURRENTLY)가 3단계(원인 정리) 앞이다. 취소·timeout이 원인이면 그 열린 트랜잭션이 운영자의 DROP INDEX CONCURRENTLY도 붙잡아, 2단계가 3단계를 기다린다. - runbook을 실행하는 IT는 중복으로 실패한 unique CREATE 한 경우만 돌렸다. 고른 방법 - 리뷰 권장안: 무효 인덱스를 지우는 단계를 문장 종류로 나눈다. CREATE는 그 인덱스를, REINDEX는 _ccnew(또는 _ccold) 사본을 지운다. DROP INDEX CONCURRENTLY면 이 단계를 건너뛴다. 다시 배포한 같은 문장이 그 인덱스를 지운다(PostgreSQL은 중간에 실패한 DROP INDEX CONCURRENTLY의 재시도를 받는다). 5단계 문장도 "builds the index"에서 세 경우로 고친다. - 단계 순서를 "빌드 확인 → 원인 정리 → 무효 인덱스 삭제 → 실패 행 삭제 → 재배포"로 바꾼다. 실패 행만 지운다는 소유자 결정(2026-11-06)은 그대로다. - IT에 두 경우를 더한다. 열린 쓰기를 기다리다 취소된 REINDEX와 열린 읽기를 기다리다 취소된 DROP에 runbook SQL을 runbook에서 읽어 돌리고, 재배포 뒤 이력 [1 true, 2 true], 무효 인덱스 없음, V1 checksum 그대로를 단언한다. 대기를 30초 기다리지 않고, 문장이 잠금을 기다리는 것을 본 즉시 취소하는 도우미(cancelledOnceItWaits)를 둔다. - 같은 절차를 요약한 곳을 같이 고친다: docs/jpa/runbooks.md "An invalid index exists", migration-guide "Concurrent index builds"(DROP이 무엇을 기다리는지 포함), 학습 문서 8.2절, ConcurrentIndexMigrationInspector의 Javadoc과 실패 메시지, 업그레이드 안내 5절 행(그 범위가 아직 main에 없어 행을 최종 동작으로 고치고 머리 목록에 더함). - 버린 대안: 가이드와 검사기가 DROP INDEX CONCURRENTLY에 IF EXISTS를 요구한다. 이미 배포된 파일은 고칠 수 없어 새 파일에만 통하고, 서비스의 기존 마이그레이션 검사를 새로 실패시킨다. 위험·한계 - 운영자가 실패한 문장의 종류를 마이그레이션 파일에서 읽어야 한다. runbook이 이력 행만으로는 알 수 없는 것을 요구한다. - REINDEX가 swap 뒤에 실패해 _ccold가 남는 경우는 문서로만 다뤘다(실행 재현 없음). PostgreSQL 문서의 권장 복구와 같다. - 단계 번호가 바뀌었다. 리뷰 기록이 옛 번호(2단계 = drop)로 적은 곳은 그때의 기록이라 두었다. RED (desktop, 기준3eb3b067+ 임시 테스트, 로그 ~/r9-g3-logs/red-concurrent.log) - postgresqlConcurrentIndexMigrationIntegrationTest rc=1, 9건 중 2건 실패 - redAFailedConcurrentDropIsRecoveredByTheBaseRunbook: 기준 runbook 1·2·4단계 뒤 재배포가 "42704 ERROR: index "ix_probe_id" does not exist"로 실패, 이력 [1 true, 2 false] 그대로 - redTheBaseRunbookDropsBeforeItEndsTheTransaction: 기준 순서의 2단계 (_ccnew drop)가 열린 쓰기 트랜잭션을 기다려 취소됨 - 나머지 7건(기존) 통과 검증 (desktop, 이 커밋의 트리7cfaa83c, --no-build-cache, 로그 ~/r9-g3-logs/) - :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0 - postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 9건(새 2건 포함) - :adapter:outbound:persistence-jpa:testQualityCheck rc=0 - :app-bootstrap:documentContractTest rc=0, 67건(RunbookCoverageContractTest 포함) - -p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest rc=0, 47건(검사기 사본이 바뀌어서) - FROM-CACHE 0 - 상대 링크(노트북): python3 scripts/check-work-docs.py --links로 바꾼 문서 5개(migration-failed.md, jpa/runbooks.md, migration-guide.md, 학습 문서, 업그레이드 안내) rc=0, 깨진 링크 0 Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-01 Fixes:6ec0c4f7fa("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
4.3 KiB
JPA Platform Runbooks
Operator procedures for the failures this platform is designed to surface rather than hide.
A transaction reported completion unknown
Signal: a write use case failed with a commit-phase error (connection lost, 57P01, class
08) from TransactionPort.
What it means: the commit may or may not have happened. It is not a rollback.
Do not re-run the use case. That is what the platform refused to do automatically, for the same reason.
Procedure:
- Take the idempotency key or operation id of the failed request.
- Check the idempotency record for that key.
- Check the business row the use case would have written.
- Check the outbox for a corresponding event.
- If all three agree the write happened, stop — the request succeeded.
- If all three agree it did not, the use case may be re-run.
- If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; guessing is not.
Deadlock or serialization rate rising
Signal: DB_DEADLOCK / serialization failures rising in the persistence error codes.
SpringTransaction does not retry, so each one reaches the caller.
- Group the failures by operation. A single operation dominating means a hot row or an inconsistent lock order.
- For deadlocks, check whether two operations take the same rows in opposite orders — that is a code fix, not a tuning one.
- For serialization failures under
SERIALIZABLE, confirm the isolation is actually required.
Pool exhaustion
Signal: connection acquisition timeouts; PoolMeasurement.pending non-zero.
- Check
REQUIRES_NEWusage. It takes a second connection while pinning the first, so the pool must satisfy(threads x (1 + depth)) + 1. - Check for streaming outside a bounded scope — a
Streamreturned past the transaction holds its connection until the pool notices. - Check for external calls inside a DB transaction. The design forbids them precisely because an HTTP timeout then holds a connection for its whole duration.
Flyway validation failed at startup
The deployment is running against a schema it was not built for. It failed closed, which is correct.
- Read the reported error codes (the messages are deliberately not propagated).
CHECKSUM_MISMATCH— an applied migration was edited afterwards. Find which change is missing from this database. Do not runrepair: it rewrites history to match the scripts, which resolves the symptom by deleting the evidence.MISSING_SCRIPT— a migration applied here is not in this build. Usually a rollback to an older artifact.
An invalid index exists
Signal: this query returns rows.
select n.nspname || '.' || i.relname as invalid_index
from pg_index x
join pg_class i on i.oid = x.indexrelid
join pg_namespace n on n.oid = i.relnamespace
where not x.indisvalid;
A concurrent build, rebuild or drop failed. The index is ignored by the planner and maintained by every write.
- Confirm no build is currently running. An in-progress build looks identical in the catalog.
- If a migration was building, rebuilding or dropping it, Flyway recorded that version as failed
(
success = false) and refuses every later deploy until that row is gone: dropping the index does not clear it. Follow migration-failed.md "Recover a failed concurrent index migration" instead of the next step. It removes the cause, drops the index a failed build or rebuild left, and deletes that one row. It leaves the index a failedDROP INDEX CONCURRENTLYleft, for the deploy again to drop: dropped by hand, that statement finds no index and fails again. - Otherwise run
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;outside a migration, and re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to drop an index another instance was about to finish building.
The runtime role failed verification
Startup refused because the runtime credential holds CREATE, or search_path contains an
unapproved schema.
This is not a false positive to be worked around. Re-provision from
infra/jpa/roles/runtime-roles.sql; the application's credential having DDL is the condition that
makes every other schema guarantee unenforceable.