Files
clean-architecture-backend-…/docs/jpa/experimental-support-matrix.md
T
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `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 없음).
2026-11-07 17:56:34 +09:00

3.4 KiB

Experimental 지원 매트릭스

Experimental 코드는 dev.caskeleton.adapter.outbound.persistence.experimental의 라이브러리 코드다. 그것을 조립하는 것도, 켜는 설정도 없다. 이 중 하나를 원하는 배포는 자기 어댑터 코드에서 진입점을 만들고, 그 호출이 opt-in이다. 어느 것도 Stable 조립에 들어가지 않고, JpaModuleBoundaryTest가 Stable 패키지가 그것에 의존하지 못하게 막는다.

기능 진입점 증거(따로 적지 않으면 PostgreSQL lane) 상태
공유 schema multi-tenancy(열) tenant.TenantContext, tenant.TenantAwareRepositoryGuard TenantColumnIsolationTest Experimental
PostgreSQL RLS multi-tenancy rls.RlsTenantSessionBinder, rls.RlsPolicyVerifier RlsIsolationFailureTest Experimental
테넌트마다 schema schema.SchemaMultiTenantConnectionProvider, schema.SchemaTenantMigrationOrchestrator SchemaTenantMigrationContractTest Experimental
테넌트마다 DB의 풀 예산 database.TenantDataSourceRegistry, database.TenantPoolBudget TenantPoolCapacityContractTest Experimental
일관성을 아는 read replica replica.ConsistencyAwareDataSourceRouter(ReplicaLagMonitor는 직접 구현) ReadAfterWriteRoutingContractTest Experimental
Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 없음 — .github/workflows/jpa-next.yml의 probe가 NOT_EXECUTABLE을 기록 Jpa4CompatibilityTest, Hibernate8CompatibilityTest, PostgreSql19CompatibilityTest(unit lane의 버전 canary) 실행 불가

이력: 이것들 앞에 있던 backend.jpa.experimental.* 스위치와 ExperimentalFeatureGate는 2026-09-25에 지웠다. 어떤 코드도 설정에서 스위치를 읽지 않아서 켜도 아무 일이 없었고, gate는 호출자가 스스로 만든 map만 확인했다.

알려진 제약

  • 테넌트 context는 닫힌 채 실패한다. 공유 schema 배포에서 테넌트가 묶이지 않으면 테넌트 조건 없는 쿼리가 되고, 모든 테넌트의 행을 돌려준다.
  • Hibernate filter는 보안 경계가 아니다. native SQL, bulk DML, getReference, second-level cache에 적용되지 않는다.
  • RLS에는 셋이 모두 필요하다. ENABLE ROW LEVEL SECURITY, FORCE ROW LEVEL SECURITY(그렇지 않으면 소유자는 자기 정책에서 빠진다), BYPASSRLS 없는 런타임 역할.
  • 테넌트 묶기는 트랜잭션 로컬이다. 세션 로컬 설정은 연결이 풀로 돌아간 뒤에도 남는다.
  • readOnly=true만으로는 replica로 보내지 않는다. 쓰기 뒤 읽기는 일관성 token이나 primary를 쓴다.
  • replica 지연 증거를 얻을 수 없으면 primary다. 증거가 없다는 것은 최신이라는 증거가 아니다.
  • 테넌트별 풀은 전역으로 제한한다. 적당한 풀을 가진 테넌트 50개는 연결 100개를 허용하는 서버에 대한 연결 500개다.
  • 테넌트 id는 메트릭 태그가 되지 않는다. 테넌트 수는 정의상 상한이 없다.

lane은 Stable을 바꾸지 않는다

호환성 lane은 아무것도 게시하지 않고 어떤 Stable 계약도 바꾸지 않는다. Hibernate 8이 fetch-pagination gate에 다른 SQL을 만들면 그것은 Hibernate 8에 대한 발견이다. 7.x gate는 7.x가 해야 할 것을 계속 단언한다. 배포가 돌리는 것이 그것이기 때문이다.