문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.
고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
`` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
- support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
`JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
- repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
`src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
`composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
`JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
- experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.
버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.
위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
`JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
`PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# 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 <invalid_index>;`를 돌리고, 인덱스 마이그레이션을
|
|
다시 적용한다.
|
|
|
|
플랫폼은 이것을 자동으로 지우지 않는다. rolling deploy에서는 모든 인스턴스가, 다른 인스턴스가 곧 빌드를 끝낼 인덱스를
|
|
지우려고 경주한다.
|
|
|
|
## 런타임 역할이 검증에 실패했다
|
|
|
|
런타임 자격 증명이 `CREATE`를 가지거나 `search_path`에 승인하지 않은 schema가 있어서 기동이 거부됐다.
|
|
|
|
돌아갈 오탐이 아니다. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션
|
|
자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 지킬 수 없다.
|