# JPA 플랫폼 runbook 이 플랫폼이 숨기지 않고 드러내도록 설계한 실패에 대한 운영자 절차다. ## 트랜잭션이 완료를 모른다고 보고했다 **신호:** 쓰기 use case가 `TransactionPort`에서 커밋 단계 오류(연결 끊김, `57P01`, class `08`)로 실패했다. **뜻:** 커밋이 됐을 수도 안 됐을 수도 있다. 롤백이 아니다. use case를 다시 돌리지 **않는다**. 플랫폼이 같은 이유로 자동으로 하기를 거부한 일이다. **절차:** 1. 실패한 요청의 멱등 키나 operation id를 꺼낸다. 2. 그 키의 멱등성 기록을 확인한다. 3. use case가 썼을 업무 행을 확인한다. 4. outbox에 그에 맞는 이벤트가 있는지 확인한다. 5. 셋이 모두 쓰기가 일어났다고 하면 멈춘다. 요청은 성공했다. 6. 셋이 모두 일어나지 않았다고 하면 use case를 다시 돌려도 된다. 7. 서로 다르거나 결론이 나지 않으면 넘긴다. 결론 없음은 정당한 결과다. 짐작은 아니다. ## 교착이나 직렬화 실패 비율이 오른다 **신호:** 영속성 오류 코드에서 `DB_DEADLOCK`·직렬화 실패가 오른다. `SpringTransaction`은 다시 시도하지 않으므로 하나하나가 호출자에게 닿는다. 1. 실패를 operation별로 묶는다. operation 하나가 압도하면 hot row나 어긋난 잠금 순서다. 2. 교착이면 두 operation이 같은 행을 반대 순서로 잡는지 확인한다. 그것은 조정이 아니라 코드를 고칠 일이다. 3. `SERIALIZABLE`에서의 직렬화 실패면 그 격리 수준이 정말 필요한지 확인한다. ## 풀 고갈 **신호:** 연결 획득 시간 초과. `PoolMeasurement.pending`이 0이 아니다. 1. `REQUIRES_NEW` 사용을 확인한다. 첫 연결을 쥔 채 두 번째 연결을 잡으므로, 풀은 `(threads x (1 + depth)) + 1`을 채워야 한다. 2. 상한 있는 범위 밖의 streaming을 확인한다. 트랜잭션 밖으로 돌려준 `Stream`은 풀이 알아챌 때까지 연결을 쥔다. 3. DB 트랜잭션 안의 외부 호출을 확인한다. 설계가 그것을 금지하는 이유가 바로 그것이다. 그러면 HTTP 시간 초과가 그 시간 내내 연결을 쥔다. ## 기동할 때 Flyway 검증이 실패했다 배포가 맞지 않는 스키마에서 돌고 있다. 닫힌 채 실패했고, 그것이 맞다. 1. 보고된 오류 코드를 읽는다(메시지는 일부러 전달하지 않는다). 2. `CHECKSUM_MISMATCH` — 적용된 마이그레이션을 나중에 고쳤다. 이 DB에 어느 변경이 빠졌는지 찾는다. **`repair`를 돌리지 않는다.** repair는 이력을 스크립트에 맞춰 다시 써서, 증거를 지워 증상을 없앤다. 3. `MISSING_SCRIPT` — 여기 적용된 마이그레이션이 이 빌드에 없다. 보통 옛 산출물로 되돌린 것이다. ## 무효 인덱스가 있다 (An invalid index exists) **신호:** 이 쿼리가 행을 돌려준다. ```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; ``` 동시 빌드, 재빌드, 삭제가 실패했다. planner는 그 인덱스를 무시하고, 모든 쓰기는 그것을 유지한다. 1. 지금 도는 빌드가 없는지 확인한다. 진행 중인 빌드도 카탈로그에서는 똑같이 보인다. 2. 마이그레이션이 그것을 빌드, 재빌드, 삭제하던 중이었으면, Flyway는 그 버전을 실패(`success = false`)로 기록했고 그 행이 사라질 때까지 뒤의 모든 배포를 거부한다. 인덱스를 지워도 풀리지 않는다. 다음 단계 대신 [migration-failed.md](../runbooks/migration-failed.md) 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)」를 따른다. 그 절차는 원인을 없애고, 실패한 빌드나 재빌드가 남긴 인덱스를 지우고, 그 한 행을 지운다. 실패한 `DROP INDEX CONCURRENTLY`가 남긴 인덱스는 다시 배포가 지우도록 남긴다. 손으로 지우면 그 문장이 인덱스를 찾지 못해 다시 실패한다. 3. 그렇지 않으면 마이그레이션 밖에서 `DROP INDEX CONCURRENTLY IF EXISTS ;`를 돌리고, 인덱스 마이그레이션을 다시 적용한다. 플랫폼은 이것을 자동으로 지우지 않는다. rolling deploy에서는 모든 인스턴스가, 다른 인스턴스가 곧 빌드를 끝낼 인덱스를 지우려고 경주한다. ## 런타임 역할이 검증에 실패했다 런타임 자격 증명이 `CREATE`를 가지거나 `search_path`에 승인하지 않은 schema가 있어서 기동이 거부됐다. 돌아갈 오탐이 아니다. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 지킬 수 없다.