Files
clean-architecture-backend-…/docs/jpa/runbooks.md
T
donghyeon-kaandClaude Opus 5.5 0579935746 review-followup Wave 3 라운드 3(P28·P29): fileserver use case·file:* 권한, 보안 파일 primitive 공용화, jvm-test-suite
- 결정 32: fileserver transport 연산 21개를 `port.in` use case로, 쓰기·읽기에 `file:*` 권한(소유자·tenant 정책은 유지),
  inbound 서비스 이름 `*UseCase`, port 구현 이름 `<Tech><Port>` 규칙(S2-#13b, 24개)
- 디렉터리 descriptor 파일 primitive를 `adapter:outbound:support`로(S4-lead-2 일부 — fileserver는 번역만),
  persistence-fileserver를 scan·클래스별 조건 대신 명시적 `@Bean` 설정으로(S2-#8a 일부), `FileVerifier`를 adapter로
- 호출자 0인 `poster.image-attached` 이벤트 삭제, SES SDK client를 레지스트리 종료 때 close, fileserver migration V1–V5 고정
- P29: auxiliary 레인 → Gradle `jvm-test-suite`(BUILD-O3-5, build-logic 16,768 → 5,851줄), redis-sdk가 runtime을 api로(P22-new-3)
- 통합: JPA API surface 기준선 재승인(이름 규칙 변경), migration lane에 V19 반영, messaging 통합 테스트가 jar 안 migration 목록 조회(ORCH-new-5)
- P28·P29 에이전트가 세션 재시작으로 중단 — 커밋된 것만 합치고 결과 파일은 오케스트레이터가 확정, S6-#10a는 P30으로

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck architectureCheck verifyPublicPathSnapshot
:app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest
:sample-portfolio:systemTest integrationCheck · -p build-logic test · -p optional-platforms ci · releaseCheck qualificationBootJar 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 14:54:06 +09:00

3.7 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:

  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.

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. 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.