문제 (재리뷰 round7 영속성 RR7-03-01~05) - 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가 "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의 이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에 다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다. docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서 멈춘다. - 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다. 가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다 커밋해 앞 문장이 남는다. - 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX … CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다. - LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면 SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은 "늘 거부"라고 쓴다. - ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고 안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개 (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도 모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be executed within a pipeline"으로 실패한다. 고른 방법 - 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에 "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드 확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의 실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고 flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고 postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어 실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기 Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다. - 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와 잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태). - 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와 상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은 PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이 맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라 그대로 둔다. - ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을 두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스 문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어 sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다 (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을 파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로 바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다. 위험·한계 - 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다. 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이 없다(업그레이드 안내 4.1에 적음). - runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라 성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이 지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다. - ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음). - Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라 UP-TO-DATE로 처리됐다. 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 기준73d39212+ 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시 메서드, + 임시 ledger V004): - persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중 2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log) - postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장 대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied, conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데 검사기는 통과 (red2-lockwait.log) - postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 — 옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version 2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김, runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음) (red2-concurrent.log) - ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기 IT "name it as an exception here", 다른 IT 둘 "cannot be executed within a pipeline" (red-ledger.log) GREEN — 이 커밋의 트리b49369e7: - :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0), :testQualityCheck rc=0 - postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0) - postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0) - -p optional-platforms :grpc:grpc-operation-ledger-jpa:check integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0) - :app-bootstrap:documentContractTest rc=0 (66건 실패 0) - 두 빌드의 verifyStrictLaneStages --dry-run rc=0 - ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고 메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면 rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent index statement"로 거부 - python3 scripts/check-work-docs.py --links docs: 깨진 링크 0 Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
# 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:**
|
|
|
|
1. Take the idempotency key or operation id of the failed request.
|
|
2. Check the idempotency record for that key.
|
|
3. Check the business row the use case would have written.
|
|
4. Check the outbox for a corresponding event.
|
|
5. If all three agree the write happened, stop — the request succeeded.
|
|
6. If all three agree it did not, the use case may be re-run.
|
|
7. 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.
|
|
|
|
1. Group the failures by operation. A single operation dominating means a hot row or an
|
|
inconsistent lock order.
|
|
2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a
|
|
code fix, not a tuning one.
|
|
3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required.
|
|
|
|
## Pool exhaustion
|
|
|
|
**Signal:** connection acquisition timeouts; `PoolMeasurement.pending` non-zero.
|
|
|
|
1. Check `REQUIRES_NEW` usage. It takes a second connection while pinning the first, so the pool
|
|
must satisfy `(threads x (1 + depth)) + 1`.
|
|
2. Check for streaming outside a bounded scope — a `Stream` returned past the transaction holds its
|
|
connection until the pool notices.
|
|
3. 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.
|
|
|
|
1. Read the reported error codes (the messages are deliberately not propagated).
|
|
2. `CHECKSUM_MISMATCH` — an applied migration was edited afterwards. Find which change is missing
|
|
from this database. **Do not run `repair`**: it rewrites history to match the scripts, which
|
|
resolves the symptom by deleting the evidence.
|
|
3. `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.
|
|
|
|
```sql
|
|
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 failed. The index is ignored by the planner and maintained by every write.
|
|
|
|
1. Confirm no build is currently running. An in-progress build looks identical in the catalog.
|
|
2. Run `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;` outside a migration.
|
|
3. If a migration built 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](../runbooks/migration-failed.md) "Recover a failed concurrent index
|
|
migration", which removes the cause and deletes that one row.
|
|
4. 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.
|