Files
clean-architecture-backend-…/docs/jpa/support-matrix.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

125 lines
9.1 KiB
Markdown

# 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).
- 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.