문제: `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 없음).
8.9 KiB
JPA 영속성 플랫폼 — 지원 매트릭스
이 문서는 렌더링이다. 기계가 읽는 정본은
src/adapter/outbound/persistence-jpa/release/release-registry.json이다.
registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다.
JpaReleaseRenderingTest가 DB 표, gate 표,release.yml의 JPA matrix와 승격 목록을 registry와 비교한다.jpaReleaseQualification집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 그래프를 만들 때 실패한다.jpa-nightly.yml의 matrix도 같은 비교를 받는다. Experimental major는.github/workflows의 어떤 lane이 그것을 대상으로 기록해야 하고, Stable lane은 그것을 돌리면 안 된다.
이력: 전에는
JpaReleaseManifest가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든PostgreSQL NN이 지원 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다.jpa-nightly.yml은 자기 matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다.
데이터베이스
| Database | Support | Evidence |
|---|---|---|
| PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 19 | Experimental | jpa-next.yml — NOT_EXECUTABLE: postgres:19-alpine이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 |
| H2 | Local convenience | PostgreSQL 동작의 증거가 절대 아니다 |
major마다 자기 릴리스 job이 있다. release.yml의 jpa-release-gate job이 major마다 job 하나로 펼치고, 승격 job은 세
major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래서 major 하나가 빠지면 그 증거가 아니라 릴리스가 빠진다.
JpaPlatformContractSupport.start()는 여러 버전 선택을 아예 거부한다.
이력: 한동안 그렇지 않았다. 릴리스 lane이
-Pjpa.matrix.versions=16,17,18을selectedVersions().get(0)을 쓰는JpaPlatformContractSupport.start()에 넘겼으므로, 통합 suite 전체가 PostgreSQL 16에만 돌았다. 이 표는 단언 셋짜리 smoke test를 근거로 17과 18을 전부 덮었다고 적었다.
provider 기준선. gate는 Spring Boot BOM이 푸는 Hibernate 버전 7.1.8.Final에서 돈다. registry는 그것을
stable-tested-baseline으로 기록한다. 7.4는 compatibility-target으로 기록하고, 전체 lane이 실제로 그 버전에서 돈 뒤에
기준선이 된다.
이력: 이 문서는 전에 7.4를 Stable 기준선이라 불렀고 페이지네이션 gate 이름도
hibernate-7.4-fetch-pagination이었다. 그래서 그 gate를 돌릴 때마다 한 번도 돌려 보지 않은 provider 이름이 붙은 증거가 나왔다.
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
SKIP LOCKED는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 CLAUDE.md는 측정을 기록한다.
H2 2.4.240은 FOR UPDATE SKIP LOCKED를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. 측정한 버전에서 관찰한
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다. 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
없으므로 모든 동시성 계약은 여전히 실제 PostgreSQL에서 돈다.
명세와 provider
| 구성 요소 | Stable | Experimental |
|---|---|---|
| Jakarta Persistence | 3.2 | 4.0 (lane) |
| Hibernate ORM | 7.4 선언 기준선 | 8 (lane) |
| Spring Boot | 저장소 BOM | — |
Hibernate 줄에는 설명이 필요하다. 설계서는 7.4를 Stable provider로 선언하고, 이 저장소의 Spring Boot BOM은 7.1.x를 푼다.
HibernateProviderPolicy가 둘을 다 가진다. 선언 기준선은 상수로, 풀린 버전은 Hibernate 자신에게서 읽는다.
driftsFromDeclaredBaseline()이 상수를 상수와 비교하는 대신 그 차이를 드러낸다.
repository-adaptation.md §4를 본다.
capability 지원 수준
수준은 jpaplatform actuator 엔드포인트가 JpaPlatformReport.platformCapabilities()로 보고하는 값이다. 마지막 세
줄(기술 감사, multi-tenancy, read replica)은 그 보고에 없고 이 문서가 정한다. Advanced와 Experimental 줄은 서비스가 직접
부르는 라이브러리 코드다(src/adapter/outbound/persistence-jpa/README.md 「라이브러리 API」).
| capability | 수준 |
|---|---|
| Keyset pagination | Stable |
| Flyway schema gate | Stable |
| Runtime role verification | Stable |
| Commit completion evidence | Advanced |
| JDBC batch | Advanced |
| Observability (query metrics, redaction) | Advanced |
| PostgreSQL JSONB | Advanced |
| PostgreSQL array and range | Advanced |
| Bulk DML | Advanced |
Hibernate StatelessSession |
Advanced |
PostgreSQL COPY |
Advanced (admin 자격 증명 필요) |
| Hibernate second-level cache | Advanced |
| Hibernate Envers | Advanced |
기술 감사 — audit/AuditableEntity |
Stable (canonical) |
| Multi-tenancy (column, RLS, schema, database) | Experimental |
| 일관성을 아는 read replica | Experimental |
릴리스 gate
줄마다, 플랫폼이 테스트를 통과하고도 운영에서 틀릴 수 있는 길 하나다.
| Gate | Kind | 막는 것 |
|---|---|---|
postgresql-contract |
gate | DB 증거가 H2에서만 나온 릴리스 |
completion-unknown-no-retry |
gate | 이미 커밋됐을 수 있는 쓰기를 자동으로 다시 돌림 |
osiv-disabled |
gate | view 계층에서의 lazy loading, 렌더링한 행마다 쿼리 하나 |
flyway-validate |
gate | Hibernate가 배포된 스키마를 바꾸거나, 맞지 않는 스키마에서 돎 |
runtime-role-no-ddl |
gate | 애플리케이션 자신의 자격 증명으로 스키마 객체를 바꾸거나 지울 수 있음 |
collection-fetch-pagination |
gate | 페이지 단위 collection fetch가 몰래 테이블 전체를 읽고 메모리에서 페이지를 나눔 |
감사 방식
감사 방식은 audit/AuditableEntity 하나다. created_*/updated_*, 256자 actor이고, repository 어댑터가 명시적으로
찍는다. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. 두 번째 방식인 Spring Data listener 기반
(auditing/AuditMetadata)은 한 번도 조립되지 않아서 지웠다. JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism이
그것이 엔티티에 돌아오지 못하게 막는다.
이 방식은 bulk·native update에 닿지 않는다. 어댑터의 보통 save에서 찍으므로, DB로 바로 가는 문장은 감사 열을 앞 save의
값으로 남긴다. 그래서 감사 대상 엔티티의 bulk update는 문장 안에서 감사 열을 설정해야 하고,
JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit가 운영 그래프에서 그것을 확인한다.
지원하지 않는다고 밝힌 것
- Reactive JPA. JPA는 blocking 명세다. 그 위의 reactive facade는 blocking 호출을 없애는 게 아니라 event loop로 옮긴다.
- 운영 스키마를 쓰는 Hibernate.
ddl-auto는 배포된 스키마를 절대 바꾸지 않는다. - 플랫폼이 가진 generic CRUD repository. 도메인이 자기 repository를 가진다(설계서 §10.1).
- 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.