DongHyeonkaandClaude Opus 5
0e61f86eb5
Implements the Stable and Experimental JPA persistence platform designs against real PostgreSQL, adapted to this repository's fail-closed 19-leaf registry. The design models the platform as 25 Gradle projects. `src/settings.gradle` throws unless the registry holds exactly 19 leaves, so the plan's modules become packages inside `:adapter:outbound:persistence-jpa` (starter in `:app-bootstrap`, testkit in its own source set). The full mapping, the renames this repository's naming gate required, and every deliberate substitution are recorded in `docs/jpa/repository-adaptation.md`. Seven Docker-backed lanes replace the plan's seven JVM test suites. Each fails closed: a lane that discovers nothing, or a container that cannot start, is an error rather than a skip. Three defects the contracts found against a real server: - `CommitFailureClassifier` treated only SQLSTATE 40003, class 08, and transport breaks as completion-unknown. A backend terminated mid-commit reports 57P01, and the commit record may already be in the WAL — so a possibly-committed transaction could be re-run. 57P01/57P02/57P03 now classify as completion-unknown. - `SchemaTenantMigrationOrchestrator` recorded `MigrateResult`'s target version, which is empty for a tenant already current, reporting migrated tenants as unmigrated during a partial rollout. It now reads the applied version back from the tenant's schema history. - `JpaStreamExecutor` checked only the declared return type for reactive publishers, and `RegisteredPostgreSqlCopyLoader` passed the COPY timeout to `SET`, which is parsed before parameter binding. `JpaModuleBoundaryTest` enforces the plan's module map as package rules; `verifyCleanArchitectureDependencies` governs edges between leaves and cannot see these. Its first assertion is that the import is non-empty, because every rule under it is a `noClasses()` rule and would pass vacuously on an empty import. Verified: 128 container tests across all seven lanes, 1183 unit tests, `:adapter:outbound:persistence-jpa:check`, `:app-bootstrap:check`, `verifyCleanArchitectureDependencies`, `verifyOneTypePerFile`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
# Experimental Support Matrix
|
|
|
|
Everything here is off unless its `backend.jpa.experimental.*` flag is explicitly true, and none of
|
|
it is part of the Stable composition.
|
|
|
|
| Feature | Flag | State |
|
|
|---|---|---|
|
|
| Shared-schema multi-tenancy (column) | `backend.jpa.experimental.multitenancy-column` | Experimental |
|
|
| PostgreSQL RLS multi-tenancy | `backend.jpa.experimental.multitenancy-rls` | Experimental |
|
|
| Schema-per-tenant | `backend.jpa.experimental.multitenancy-schema` | Experimental |
|
|
| Database-per-tenant | `backend.jpa.experimental.multitenancy-database` | Experimental |
|
|
| Consistency-aware read replica | `backend.jpa.experimental.read-replica` | Experimental |
|
|
| Jakarta Persistence 4.0 lane | `backend.jpa.experimental.jakarta-persistence-4` | Experimental |
|
|
| Hibernate ORM 8 lane | `backend.jpa.experimental.hibernate-8` | Experimental |
|
|
| PostgreSQL 19 lane | `backend.jpa.experimental.postgresql-19` | Experimental |
|
|
|
|
Presence on the classpath is not consent. `ExperimentalFeatureGate` fails startup when a module is
|
|
present and its flag is not set, because an experimental module can arrive transitively and a
|
|
tenant-isolation feature that switched itself on would be the worst possible default.
|
|
|
|
## Known constraints
|
|
|
|
- Tenant context is fail-closed. An unbound tenant in a shared-schema deployment means a query with
|
|
no tenant predicate, which returns every tenant's rows.
|
|
- A Hibernate filter is not the security boundary. It does not apply to native SQL, bulk DML,
|
|
`getReference`, or the second-level cache.
|
|
- RLS requires all three of: `ENABLE ROW LEVEL SECURITY`, `FORCE ROW LEVEL SECURITY` (the owner is
|
|
otherwise exempt from its own policies), and a runtime role without `BYPASSRLS`.
|
|
- Tenant bindings are transaction-local. A session-local setting survives the connection's return to
|
|
the pool.
|
|
- `readOnly=true` never routes to a replica on its own. Read-after-write uses a consistency token or
|
|
the primary.
|
|
- Unavailable replica lag evidence means the primary. Absence of evidence is not evidence of
|
|
freshness.
|
|
- Per-tenant pools are bounded globally. Fifty tenants with a modest pool each is five hundred
|
|
connections against a server that permits a hundred.
|
|
- Tenant ids never become metric tags. Tenant cardinality is unbounded by definition.
|
|
|
|
## Lanes never change Stable
|
|
|
|
A compatibility lane publishes nothing and changes no Stable contract. If Hibernate 8 generates
|
|
different SQL for the fetch-pagination gate, that is a finding about Hibernate 8 — the 7.x gate keeps
|
|
asserting what 7.x must do, because that is what deployments run.
|