# JPA 영속성 플랫폼 — 지원 매트릭스 **이 문서는 렌더링이다. 기계가 읽는 정본은 [`src/adapter/outbound/persistence-jpa/release/release-registry.json`](../../src/adapter/outbound/persistence-jpa/release/release-registry.json)이다.** registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다. - `JpaReleaseRenderingTest`가 DB 표, gate 표, `.gitea/workflows/release.yml`의 JPA matrix를 registry와 비교한다. 릴리스 이미지 job은 그 matrix job 전부를 `needs`로 기다린다. 그래서 같은 실행·같은 커밋에서 모든 Stable major가 통과해야 이미지가 나간다. - `jpaReleaseQualification` 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 그래프를 만들 때 실패한다. - `.gitea/workflows/main.yml`의 nightly `jpa-postgresql` matrix도 같은 비교를 받는다. Experimental major는 `.gitea/workflows`의 어떤 lane이 그것을 대상으로 기록해야 하고(지금 `main.yml`의 `jpa-next` job), Stable lane은 그것을 돌리면 안 된다. > 이력: 전에는 `JpaReleaseManifest`가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 `PostgreSQL NN`이 지원 > 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 > 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. > 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. nightly workflow는 자기 > 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 | [`main.yml`](../../.gitea/workflows/main.yml)의 `jpa-next` job — `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`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.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](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). - 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.