Files
clean-architecture-backend-…/docs/jpa/support-matrix.md
T
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00

8.2 KiB

JPA Persistence Platform — Support Matrix

This document is a rendering. The machine-readable source is src/config/jpa/release-registry.json.

JpaReleaseManifest used to parse this file with regular expressions: every PostgreSQL NN it mentioned became a supported version, whatever table or sentence produced the match. An Experimental major joined the Stable list, a version named once in prose counted as supported, and demoting a major changed nothing so long as the string survived somewhere in the document. Now the registry declares a support level per major as a field, each gate names the Gradle task that produces its evidence, and this document describes what the registry says.

Being a rendering used to be a claim rather than a mechanism: the tables below were still typed by hand, so a major demoted in the registry stayed Stable here and kept its full release job. JpaReleaseRenderingTest now compares the database table, the gate table and release.yml's JPA matrix and promotion lists to the registry, and the jpaReleaseQualification aggregate depends on every blocking gate's task, so a gate naming a task that does not exist fails when the task graph is built. Edit the registry; these tables follow, or the build fails.

Two renderings stayed outside that comparison until they were added to it. jpa-nightly.yml runs its own matrix and nothing checked it, so a demotion corrected the release lane and left the nightly lane certifying the major. And an Experimental major's "compatibility lane only" named no file: the lane existed, but the registry, this document and the release workflow could each be read end to end without establishing that, so a reader looking for it concluded there was none. An Experimental major now has to be recorded as the target of a lane in .github/workflows, and a Stable lane may not run it.

Database

Database Support Evidence
PostgreSQL 16 Stable full contract suite, release lane (own matrix job)
PostgreSQL 17 Stable full contract suite, release lane (own matrix job)
PostgreSQL 18 Stable full contract suite, release lane (own matrix job)
PostgreSQL 19 Experimental jpa-next.yml — NOT_EXECUTABLE: no postgres:19-alpine is published, so no container of that major has been started; promotion requires an ADR
H2 Local convenience never evidence of PostgreSQL behaviour

Each major gets its own release job, because for a while it did not. The release lane passed -Pjpa.matrix.versions=16,17,18 to a JpaPlatformContractSupport.start() that used selectedVersions().get(0), so the whole integration suite ran against PostgreSQL 16 and this table recorded 17 and 18 as fully covered on the strength of a three-assertion smoke test. start() now refuses a multi-version selection outright, the jpa-release-gate job in release.yml fans out to one job per major, and a promotion job requires all three majors' evidence to carry the same commit SHA — so a removed major removes the release, not the evidence for it.

Provider baseline. The gates run against the Hibernate version the Spring Boot BOM resolves — 7.1.8.Final — which the registry records as stable-tested-baseline. This document previously called 7.4 the Stable baseline and the pagination gate was named hibernate-7.4-fetch-pagination, so every run of that gate produced evidence labelled with a provider it had never executed against. 7.4 is recorded as compatibility-target; it becomes the baseline when a full lane has actually run on it.

H2 is not a second production target. It reports different SQLSTATEs for the same violation, no JSONB operators, no range types, and no concurrent index builds. A green H2 run is evidence that the code compiles and runs, and nothing more.

SKIP LOCKED needs its own sentence, because two documents said different things about it. The module's CLAUDE.md records a measurement: H2 2.4.240 accepts FOR UPDATE SKIP LOCKED and does genuinely skip locked rows, which is why the outbox claim SQL is identical on both vendors. This document previously said H2 has no such guarantee. Both are right about different questions, and the distinction is the point: observed behaviour in the version we measured is not a production guarantee, and it is never PostgreSQL contract evidence. The measurement is why the claim SQL needs no vendor branch; the absence of a guarantee is why every concurrency contract still runs against a real PostgreSQL.

Specification and provider

Component Stable Experimental
Jakarta Persistence 3.2 4.0 (lane)
Hibernate ORM 7.4 declared baseline 8 (lane)
Spring Boot repository BOM —

The Hibernate row needs a note. The design declares 7.4 as the Stable provider; this repository's Spring Boot BOM resolves 7.1.x. HibernateProviderPolicy holds both — the declared baseline as a constant, the resolved version read from Hibernate itself — and driftsFromDeclaredBaseline() makes the difference visible instead of asserting a constant against itself. See repository-adaptation.md §4.

Capability support levels

The levels are the ones JpaPlatformAutoConfiguration.capabilities() reports through the jpaplatform actuator endpoint. Advanced and Experimental rows are library code a service calls itself (src/adapter/outbound/persistence-jpa/README.md "라이브러리 API").

Capability Level
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 Admin (J4)
Hibernate second-level cache Advanced
Hibernate Envers Advanced
Technical auditing — audit/AuditableEntity Stable (canonical)
Multi-tenancy (column, RLS, schema, database) Experimental
Consistency-aware read replica Experimental

Release gates

Each row is a way the platform could pass its tests and still be wrong in production.

Gate Kind What it prevents
postgresql-contract gate a release whose only database evidence came from H2
completion-unknown-no-retry gate automatically re-running a write that may already have committed
osiv-disabled gate lazy loading from the view layer, one query per rendered row
flyway-validate gate Hibernate mutating a deployed schema, or running against one it was not built for
runtime-role-no-ddl gate the application's own credential being able to alter or drop schema objects
collection-fetch-pagination gate a paged collection fetch silently reading the whole table and paginating in memory

The audit mechanism

audit/AuditableEntity is the only one: created_*/updated_*, a 256-character actor, stamped explicitly by the repository adapter. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. A second, Spring Data listener-based mechanism (auditing/AuditMetadata) was never composed and has been removed; JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism keeps it from coming back on an entity.

The mechanism does not reach a bulk or native update. It stamps on an ordinary save in the adapter, so a statement that goes straight to the database leaves the audit columns showing the previous save. A bulk update of an audited entity must therefore set the audit column in the statement, which JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit checks over the production graph.

Explicitly unsupported

  • Reactive JPA. JPA is a blocking specification; a reactive facade over it moves the blocking call onto an event loop rather than removing it.
  • Hibernate as the production schema writer. ddl-auto never mutates a deployed schema.
  • A platform-owned generic CRUD repository. Domains own their repositories (design §10.1).
  • Automatic reconciliation of a completion-unknown transaction. The platform records; the domain resolves.