From b1cda0307b2e95c7bfe2e56237e58bc4c180adcb Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:56:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(jpa):=20JPA=20=EC=9A=B4=EC=98=81=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EB=A5=BC=20=ED=95=9C=EA=B5=AD=EC=96=B4?= =?UTF-8?q?=EB=A1=9C=20=EC=98=AE=EA=B8=B0=EA=B3=A0=20=EC=BD=94=EB=93=9C?= =?UTF-8?q?=EC=99=80=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `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 없음). --- docs/jpa/batch-write-guide.md | 67 ++-- docs/jpa/entity-mapping-guide.md | 161 ++++------ docs/jpa/experimental-promotion-checklist.md | 64 ++-- docs/jpa/experimental-support-matrix.md | 60 ++-- docs/jpa/migration-guide.md | 295 ++++++++---------- docs/jpa/observability.md | 79 +++-- docs/jpa/postgresql-extensions.md | 57 ++-- docs/jpa/query-fetch-guide.md | 94 +++--- docs/jpa/repository-adaptation.md | 222 ++++++------- docs/jpa/runbooks.md | 113 +++---- docs/jpa/security.md | 69 ++-- docs/jpa/support-matrix.md | 176 +++++------ docs/jpa/transaction-guide.md | 77 ++--- scripts/check-docs-exceptions.txt | 14 - .../platform/PoolLaneClaimTest.java | 11 +- .../testkit/JpaDocumentationContractTest.java | 14 +- 16 files changed, 700 insertions(+), 873 deletions(-) diff --git a/docs/jpa/batch-write-guide.md b/docs/jpa/batch-write-guide.md index 2cf65e28..eed38d1d 100644 --- a/docs/jpa/batch-write-guide.md +++ b/docs/jpa/batch-write-guide.md @@ -1,22 +1,19 @@ -# JPA batch write configuration +# JPA batch 쓰기 설정 -`HibernateJpaBatchExecutor` is an advanced opt-in. The template does not enable Hibernate batch -write settings globally because statistics and statement reordering add runtime cost even in -applications that never perform bulk writes. +`HibernateJpaBatchExecutor`는 고급 opt-in이다. 템플릿은 Hibernate batch 쓰기 설정을 전역으로 켜지 않는다. 통계와 문장 +재정렬은 bulk 쓰기를 한 번도 하지 않는 애플리케이션에도 런타임 비용을 더하기 때문이다. -## What the executor owns +## executor가 가지는 것 -A `JpaBatchProfile` owns the JDBC batch size for one batch run. Before the first item is written, -the executor applies `profile.jdbcBatchSize()` to the current Hibernate `Session`. The previous -Session value is restored in `finally`, including failed runs. +`JpaBatchProfile`이 batch 실행 한 번의 JDBC batch 크기를 가진다. executor는 첫 항목을 쓰기 전에 +`profile.jdbcBatchSize()`를 지금 Hibernate `Session`에 적용한다. 앞 Session 값은 실패한 실행을 포함해 `finally`에서 +되돌린다. -The executor does **not** open a transaction. The application service must enter a -`TransactionPort.inWrite(...)` boundary first. +executor는 트랜잭션을 열지 **않는다**. 애플리케이션 서비스가 먼저 `TransactionPort.inWrite(...)` 경계에 들어가야 한다. -## What the application must configure +## 애플리케이션이 설정할 것 -If a profile requests insert or update ordering, the matching Hibernate setting must already be -enabled on the SessionFactory: +profile이 insert나 update 정렬을 요구하면, 맞는 Hibernate 설정이 SessionFactory에 이미 켜져 있어야 한다. ```yaml spring: @@ -28,37 +25,31 @@ spring: generate_statistics: true ``` -`hibernate.generate_statistics=true` is required because `BatchExecutionResult` reports measured -flush and prepared-statement deltas. A disabled statistics registry would turn those values into -convincing zeros. +`BatchExecutionResult`가 잰 flush와 prepared statement의 차이를 보고하므로 `hibernate.generate_statistics=true`가 필요하다. +통계 registry가 꺼져 있으면 그 값이 그럴듯한 0이 된다. -The `HibernateStatisticsCollector` must also receive an instrumented `JdbcBatchCounter`. -`HibernateStatisticsCollector.of(sessionFactory)` is intentionally insufficient for this executor: -Hibernate statistics do not expose actual JDBC batch executions. +`HibernateStatisticsCollector`는 계측된 `JdbcBatchCounter`도 받아야 한다. 이 executor에는 +`HibernateStatisticsCollector.of(sessionFactory)`가 일부러 모자라다. Hibernate 통계는 실제 JDBC batch 실행을 드러내지 않는다. -`hibernate.default_batch_fetch_size` is unrelated to this write executor. It affects association -fetching and belongs to query/fetch tuning instead. +`hibernate.default_batch_fetch_size`는 이 쓰기 executor와 상관없다. 연관 fetch에 영향을 주고, 쿼리·fetch 조정에 속한다. -## Entity identifier constraint +## 엔티티 식별자 제약 -When `JpaBatchProfile.batchingRequired()` is true, an entity using -`GenerationType.IDENTITY` is rejected by `HibernateBatchConfigurationGuard`. Hibernate must issue -each INSERT immediately to obtain the generated identifier, so JDBC insert batching cannot satisfy -that profile. +`JpaBatchProfile.batchingRequired()`가 참이면 `GenerationType.IDENTITY`를 쓰는 엔티티는 `HibernateBatchConfigurationGuard`가 +거부한다. Hibernate는 생성된 식별자를 얻으려고 INSERT마다 바로 실행해야 하므로, JDBC insert batching으로는 그 profile을 +채울 수 없다. -Prefer a sequence-based identifier when a workload requires insert batching. Keep the sequence -allocation size aligned with the database migration. +insert batching이 필요한 작업에는 sequence 기반 식별자를 쓴다. sequence의 allocation size는 DB 마이그레이션과 맞춰 둔다. -## Failure behavior +## 실패 동작 -Configuration is checked before the persister receives the first item: +설정은 persister가 첫 항목을 받기 전에 확인한다. -- missing `hibernate.order_inserts=true` when the profile requests insert ordering: fail; -- missing `hibernate.order_updates=true` when the profile requests update ordering: fail; -- disabled Hibernate statistics: fail; -- missing JDBC batch instrumentation: fail; -- no caller-owned transaction: fail. +- profile이 insert 정렬을 요구하는데 `hibernate.order_inserts=true`가 없다: 실패. +- profile이 update 정렬을 요구하는데 `hibernate.order_updates=true`가 없다: 실패. +- Hibernate 통계가 꺼져 있다: 실패. +- JDBC batch 계측이 없다: 실패. +- 호출자가 가진 트랜잭션이 없다: 실패. -These failures are deliberate. A batch API that silently degrades to one statement per row produces -correct data but false performance evidence, which is harder to detect than a startup or invocation -failure. +이 실패는 일부러다. 행마다 문장 하나로 조용히 떨어지는 batch API는 데이터는 맞지만 성능 증거는 거짓이고, 그것은 기동이나 +호출 실패보다 알아채기 어렵다. diff --git a/docs/jpa/entity-mapping-guide.md b/docs/jpa/entity-mapping-guide.md index aae8772c..c8c57686 100644 --- a/docs/jpa/entity-mapping-guide.md +++ b/docs/jpa/entity-mapping-guide.md @@ -1,117 +1,92 @@ -# Entity Mapping Guide +# 엔티티 매핑 가이드 -Design §10-§13. The rules here exist because each one has a failure mode that is invisible in review -and expensive in production. +설계서 §10-§13. 여기 있는 규칙마다, 리뷰에서는 보이지 않고 운영에서는 비싼 실패 꼴이 있다. -## The domain owns the model +## 모델은 도메인이 가진다 -The platform defines no business entity. Table names, column semantics, keys, unique and check -requirements, associations, cascade rules, lock policy, and soft-delete policy all belong to the -domain module. There is no `GenericRepository` and no platform base repository, because a -single generic API forces every aggregate through the same operations — and one aggregate's later -requirement then changes behaviour for all of them. +플랫폼은 업무 엔티티를 정의하지 않는다. 테이블 이름, 열의 뜻, 키, unique·check 요구, 연관, cascade 규칙, lock 정책, +soft-delete 정책은 모두 도메인 모듈의 것이다. `GenericRepository`도 플랫폼 base repository도 없다. generic API +하나는 모든 aggregate를 같은 연산으로 몰아넣고, 그러면 한 aggregate의 나중 요구가 모두의 동작을 바꾼다. -## Entities must be proxyable +## 엔티티는 proxy가 될 수 있어야 한다 -- Not `final`. Hibernate creates a lazy proxy by generating a subclass; a final entity cannot be - subclassed, so *every* association to it loads eagerly whatever the mapping says. Nothing errors. -- A non-private no-arg constructor. The provider instantiates entities reflectively before - populating fields. +- `final`이 아니다. Hibernate는 subclass를 만들어 lazy proxy를 만든다. final 엔티티는 subclass를 만들 수 없으므로 그것으로의 + 연관은 매핑이 뭐라고 하든 *모두* eager로 읽힌다. 아무 오류도 나지 않는다. +- private이 아닌 인자 없는 생성자. provider는 칸을 채우기 전에 reflection으로 엔티티를 만든다. -`EntityMappingCondition` in the testkit enforces both. +testkit의 `EntityMappingCondition`이 둘을 강제한다. -## Identifiers +## 식별자 -Default to a sequence with an `allocationSize` that matches the migration's `INCREMENT BY`. When -they disagree, the provider hands out identifiers the sequence has not reserved and the collision -surfaces later as a primary-key violation under load. +기본은 sequence이고, `allocationSize`는 마이그레이션의 `INCREMENT BY`와 맞춘다. 둘이 다르면 provider가 sequence가 예약하지 +않은 식별자를 내주고, 충돌은 나중에 부하에서 primary key 위반으로 드러난다. -`GenerationType.IDENTITY` is supported and limited: the key is assigned on insert, so the provider -must execute each insert immediately to learn it, which disables JDBC insert batching entirely. -`HibernateBatchConfigurationGuard` fails a batch profile that targets an IDENTITY entity rather than -letting the import silently run an order of magnitude slower. +`GenerationType.IDENTITY`는 지원하지만 제한이 있다. 키가 insert 때 정해지므로 provider는 키를 알려고 insert마다 바로 +실행해야 하고, 그러면 JDBC insert batching이 아예 꺼진다. `HibernateBatchConfigurationGuard`는 IDENTITY 엔티티를 대상으로 +하는 batch profile을, import가 조용히 열 배 느리게 돌게 두는 대신 실패시킨다. -UUIDv7 (`UuidV7Generator`) is the application-side option. It is preferred over UUIDv4 for a primary -key because v4 is uniformly random: every insert lands on a random leaf of the B-tree, so the index -never stays in cache and write amplification grows with the table. +UUIDv7(`UuidV7Generator`)은 애플리케이션 쪽 선택지다. primary key로는 UUIDv4보다 낫다. v4는 고르게 무작위라서 insert마다 +B-tree의 무작위 leaf에 떨어지고, 인덱스가 캐시에 머물지 못하며, 쓰기 증폭이 테이블과 함께 커진다. -## Values +## 값 -- Enums are `EnumType.STRING` or an explicit converter. **Never** `ORDINAL` — it stores the - constant's position, so inserting a new constant anywhere but the end silently reinterprets every - existing row. -- Money is `BigDecimal` with explicit precision and scale. `double` cannot represent `0.1`, so sums - drift and reconciliation disagrees with the ledger. -- `Duration` goes through a converter that stores milliseconds. The ISO-8601 text form sorts and - compares wrongly in SQL. -- `Instant` and `OffsetDateTime` map differently; a column typed for one cannot faithfully store the - other. +- enum은 `EnumType.STRING`이나 명시적 converter다. `ORDINAL`은 **절대** 쓰지 않는다. 상수의 위치를 저장하므로, 끝이 아닌 + 곳에 새 상수를 넣으면 기존 행이 모두 조용히 다른 뜻이 된다. +- 금액은 정밀도와 scale을 명시한 `BigDecimal`이다. `double`은 `0.1`을 나타내지 못해서 합계가 어긋나고 맞추기가 장부와 + 다른 말을 한다. +- `Duration`은 밀리초를 저장하는 converter를 거친다. ISO-8601 문자열 꼴은 SQL에서 정렬과 비교가 틀린다. +- `Instant`와 `OffsetDateTime`은 다르게 매핑된다. 한쪽에 맞춘 열은 다른 쪽을 그대로 저장하지 못한다. -## Associations +## 연관 (Associations) -Map each association from **one side only**. A JPA association between two entities is one foreign -key column. A bidirectional pair (`@ManyToOne` on the child plus `@OneToMany(mappedBy = ...)` on -the parent) stores that one column in two Java fields, and JPA writes only the owning one. The pair -stays consistent only while every caller remembers to update both fields, and nothing fails when -someone forgets. +연관은 **한쪽에서만** 매핑한다. 두 엔티티 사이의 JPA 연관은 foreign key 열 하나다. 양방향 짝(자식의 `@ManyToOne`과 부모의 +`@OneToMany(mappedBy = ...)`)은 그 열 하나를 Java 칸 둘에 저장하고, JPA는 소유하는 쪽만 쓴다. 짝은 모든 호출자가 두 칸을 +함께 고치는 것을 기억할 때만 맞고, 누가 잊어도 아무것도 실패하지 않는다. -What to use, in order of preference: +쓸 것, 고르는 순서대로: -1. **An ID reference between aggregates.** Hold the other aggregate's identifier as a plain column - (`UUID ownerId`). This is what every production entity in the template does today. Loading the - other aggregate is an explicit repository call, so a cross-aggregate load is visible in the code. -2. **A unidirectional `@ManyToOne` inside one aggregate**, always `fetch = FetchType.LAZY`. JPA's - default for a to-one association is `EAGER`, so every query that loads a child also queries for - its parent — the most common accidental N+1 in a JPA application. -3. **A collection is a query, not a field.** "The children of X" is a repository method - (`findByParentId`, or a fetch-join or projection query that pages in SQL). The query states its - own fetch plan and page, where a mapped collection hides both. -4. **Values the aggregate owns** — a list of tags, a set of codes — are `@ElementCollection` - (`LAZY`), not entities. +1. **aggregate 사이에는 ID 참조.** 다른 aggregate의 식별자를 평범한 열로 든다(`UUID ownerId`). 지금 템플릿의 모든 운영 엔티티가 + 이렇게 한다. 다른 aggregate를 읽는 것은 명시적인 repository 호출이라, aggregate를 넘는 읽기가 코드에 보인다. +2. **한 aggregate 안에서는 단방향 `@ManyToOne`**, 늘 `fetch = FetchType.LAZY`. JPA의 to-one 기본값은 `EAGER`라서, 자식을 + 읽는 모든 쿼리가 부모도 조회한다. JPA 애플리케이션에서 가장 흔한 실수 N+1이다. +3. **collection은 칸이 아니라 쿼리다.** 「X의 자식들」은 repository 메서드다(`findByParentId`, 또는 SQL에서 페이지를 나누는 + fetch join이나 projection 쿼리). 쿼리는 자기 fetch 계획과 페이지를 말하고, 매핑한 collection은 둘 다 숨긴다. +4. **aggregate가 가진 값**(태그 목록, 코드 집합)은 엔티티가 아니라 `@ElementCollection`(`LAZY`)이다. -A unidirectional `@OneToMany` with its own `@JoinColumn` is the exception, not the default. Use it -only for child entities the root genuinely owns and changes only through itself (the testkit's -`LifecycleParent` and `PagedParent` are this shape). It still costs an `UPDATE` per child when the -join column is nullable, and the collection still loads as a unit. The child then has no -association back to the root — not even a read-only `@ManyToOne` on the same join column -(`insertable = false, updatable = false`): that is the bidirectional pair again, without the -`mappedBy` that names it. If the child needs the root, it holds the root's ID. +자기 `@JoinColumn`이 있는 단방향 `@OneToMany`는 기본이 아니라 예외다. root가 정말 가지고 root를 통해서만 바꾸는 자식 +엔티티에만 쓴다(testkit의 `LifecycleParent`와 `PagedParent`가 이 모양이다). join 열이 nullable이면 자식마다 `UPDATE` 한 +번이 들고, collection은 여전히 한 덩어리로 읽힌다. 그러면 자식에는 root로 돌아가는 연관이 없다. 같은 join 열에 읽기 전용 +`@ManyToOne`(`insertable = false, updatable = false`)도 두지 않는다. 그것은 이름을 붙이는 `mappedBy`만 없을 뿐 다시 양방향 +짝이다. 자식이 root가 필요하면 root의 ID를 든다. -`CascadeType.ALL` with `orphanRemoval` is correct only for a child the aggregate genuinely owns. -Between independent aggregates it deletes rows another part of the system still owns — another -reason those are ID references. +`orphanRemoval`과 함께 쓰는 `CascadeType.ALL`은 aggregate가 정말 가진 자식에만 맞다. 독립된 aggregate 사이에서는 시스템의 +다른 부분이 아직 가진 행을 지운다. 그것들이 ID 참조인 또 하나의 이유다. -`JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` (testkit) fails the build on every -bidirectional pair, on `@Entity`, `@MappedSuperclass` and `@Embeddable` types: an association that -declares `mappedBy` (only that inverse half is reported), and two entities whose associations point -at each other without `mappedBy` (both halves are reported — the `@JoinColumn` form above, review -RR-03-04). The message says how the pair keeps the link: one join column mapped from both ends, or -the link stored twice — a `@OneToMany` without `@JoinColumn` in a join table beside the child's own -`@ManyToOne` column (what a forgotten `mappedBy` produces), or two `@ManyToMany` each owning a join -table (re-review round 3, RR3-02-05). That last check also refuses two entities that each hold their own foreign key to the -other (`Order.@OneToOne latestInvoice` with `Invoice.@ManyToOne order`). It is not one link mapped -twice, and the message says so; it is refused on purpose, because the two tables then reference each -other: neither row can be inserted or deleted first, one key has to be nullable and written by a -second `UPDATE`, and the entity graph is a cycle. Keep the association on one side and give the other -an ID or a query (re-review round 2, RR-02-15). A class that links to itself is a pair only when a -second member points back the other way (`@ManyToOne parent` with `@OneToMany children`); two -`@ManyToOne` links of a class to itself (a manager and a mentor) pass, because both keys point into -the one table and there are no two tables to order. 이 규칙은 `JpaProductionArchitectureTest`(app-bootstrap -`architectureTest`)가 운영 그래프 전체에 건다. -The failure message names the fields and these alternatives. +`JpaArchitectureRules.associationsAreMappedFromOneSideOnly()`(testkit)는 `@Entity`, `@MappedSuperclass`, `@Embeddable` 타입의 +모든 양방향 짝에서 빌드를 실패시킨다. `mappedBy`를 선언한 연관(그 반대쪽 반만 보고한다), 그리고 `mappedBy` 없이 서로를 +가리키는 두 엔티티(두 반을 다 보고한다. 위의 `@JoinColumn` 꼴, review RR-03-04)다. 메시지는 짝이 링크를 어떻게 가지는지 +말한다. 양 끝에서 매핑한 join 열 하나이거나, 링크를 두 번 저장한 것이다. 두 번 저장한 것은 자식 자신의 `@ManyToOne` 열 옆 +join 테이블의, `@JoinColumn` 없는 `@OneToMany`(`mappedBy`를 잊으면 생긴다)이거나, 저마다 join 테이블을 가진 `@ManyToMany` +둘이다(재확인 리뷰 round 3, RR3-02-05). 그 마지막 검사는 서로에게 저마다 foreign key를 든 두 엔티티도 거부한다 +(`Order.@OneToOne latestInvoice`와 `Invoice.@ManyToOne order`). 링크 하나를 두 번 매핑한 것은 아니고, 메시지도 그렇게 +말한다. 일부러 거부한다. 그러면 두 테이블이 서로를 참조해서, 어느 행도 먼저 넣거나 지울 수 없고, 키 하나는 nullable이어야 +하고 두 번째 `UPDATE`로 써야 하며, 엔티티 그래프가 cycle이 된다. 연관은 한쪽에 두고 다른 쪽에는 ID나 쿼리를 준다(재확인 +리뷰 round 2, RR-02-15). 자기 자신에 링크하는 클래스는, 두 번째 멤버가 반대로 가리킬 때만 짝이다(`@ManyToOne parent`와 +`@OneToMany children`). 자기 자신으로의 `@ManyToOne` 링크 둘(manager와 mentor)은 통과한다. 두 키가 모두 한 테이블을 가리켜서 +순서를 정할 두 테이블이 없기 때문이다. 이 규칙은 `JpaProductionArchitectureTest`(app-bootstrap `architectureTest`)가 운영 +그래프 전체에 건다. 실패 메시지가 칸 이름과 이 대안들을 알려 준다. -Chosen and rejected: +고른 것과 버린 것: -| Option | Decision | Why | +| 선택지 | 결정 | 이유 | | --- | --- | --- | -| One side only (ID reference, unidirectional `@ManyToOne`, collection by query), enforced by ArchUnit | Chosen | The link lives in one field, so there is nothing to keep in step. The rule turns a developer-memory convention into a build failure | -| Bidirectional with `mappedBy` and an `addChild`/`removeChild` helper that sets both sides | Rejected | The helper is the only thing keeping the two fields in step, and it must be remembered by every caller, every serializer (cycles in `toString`/JSON) and every cascade decision. A missed update leaves a row unlinked or a graph that disagrees with the database, with no error | -| Ban `@OneToMany` entirely | Rejected for now | It also bans a root-owned child collection, which has no second field to forget. Revisit if a real need for child entities that are read or changed on their own appears — that need is a sign they are a separate aggregate | -| Document only | Rejected | A convention the build does not check is invisible where the mapping is written, and the next copy of the template inherits whatever the examples show | +| 한쪽만(ID 참조, 단방향 `@ManyToOne`, 쿼리로 읽는 collection), ArchUnit으로 강제 | 고름 | 링크가 칸 하나에 있어서 맞춰 둘 것이 없다. 규칙이 개발자의 기억에 맡긴 관례를 빌드 실패로 바꾼다 | +| `mappedBy`와 양쪽을 다 설정하는 `addChild`/`removeChild` helper를 둔 양방향 | 버림 | 두 칸을 맞춰 두는 것은 helper뿐이고, 모든 호출자, 모든 serializer(`toString`·JSON의 cycle), 모든 cascade 결정이 그것을 기억해야 한다. 고치기를 하나 놓치면 링크 없는 행이나 DB와 다른 그래프가 남고, 오류는 없다 | +| `@OneToMany`를 아예 금지 | 지금은 버림 | root가 가진 자식 collection도 막는데, 그것에는 잊을 두 번째 칸이 없다. 자식 엔티티를 따로 읽거나 바꿀 실제 필요가 생기면 다시 본다. 그 필요는 그것이 별도 aggregate라는 신호다 | +| 문서만 | 버림 | 빌드가 확인하지 않는 관례는 매핑을 쓰는 자리에서 보이지 않고, 템플릿의 다음 사본은 예시가 보여 주는 것을 그대로 물려받는다 | -## Entities never leave the transaction +## 엔티티는 트랜잭션 밖으로 나가지 않는다 -A controller must not return an entity, or a collection or `Optional` of one. Response serialisation -happens after the transaction closes, so a lazy association touched by the serialiser either throws -or — with OSIV on, which this platform forbids — issues a query from the view layer, one per element. -`EntityExposureCondition` checks generic type arguments, not just the erased return type. +controller는 엔티티를, 또는 엔티티의 collection이나 `Optional`을 돌려주지 않는다. 응답 직렬화는 트랜잭션이 닫힌 뒤에 일어나므로, +serializer가 건드린 lazy 연관은 예외를 던지거나, OSIV가 켜져 있으면(이 플랫폼은 금지한다) view 계층에서 원소마다 쿼리를 낸다. +`EntityExposureCondition`은 지워진 반환 타입만이 아니라 generic 타입 인자까지 확인한다. diff --git a/docs/jpa/experimental-promotion-checklist.md b/docs/jpa/experimental-promotion-checklist.md index c6906018..7ab055c5 100644 --- a/docs/jpa/experimental-promotion-checklist.md +++ b/docs/jpa/experimental-promotion-checklist.md @@ -1,45 +1,43 @@ -# Experimental Promotion Checklist +# Experimental 승격 점검 목록 -A reviewer evaluates this checklist. Every technical item, then the ADR. (The -`ExperimentalPromotionGate` class that encoded it in main code was removed on 2026-09-25; nothing -called it.) +리뷰어가 이 목록을 판정한다. 기술 항목을 모두 본 뒤 ADR을 본다. (이것을 main 코드로 담았던 `ExperimentalPromotionGate` +클래스는 부르는 곳이 없어 2026-09-25에 지웠다.) -## Technical evidence +## 기술 증거 -- [ ] **Compatibility** — the Stable contract suite passes on the experimental target, twice, on two - supported patch releases. One passing run is a coincidence. -- [ ] **Security** — for tenancy features, cross-tenant read *and* write are both proven impossible, - including through native SQL, bulk DML, `getReference`, and the second-level cache. A filter - that covers only entity queries covers none of those. -- [ ] **Failure** — connection reuse does not leak tenant context; a failover does not silently route - a read-after-write to a stale replica; the commit-ambiguity scenarios still behave. -- [ ] **Migration** — per-tenant migration is resumable after a partial failure, and rate-limited. - With one schema per tenant, a run is N independent migrations and "it failed" is not an answer. -- [ ] **Performance** — pool capacity, replica lag under load, and per-tenant memory are measured, - not estimated. Database-per-tenant fails as a sum, not as an individual pool. +- [ ] **호환성** — Stable 계약 suite가 experimental 대상에서, 지원하는 patch 릴리스 둘에서, 두 번 통과한다. 한 번의 통과는 + 우연이다. +- [ ] **보안** — tenancy 기능이면 다른 테넌트의 읽기 *와* 쓰기가 둘 다 불가능함을 증명한다. native SQL, bulk DML, + `getReference`, second-level cache를 통한 것도 포함한다. 엔티티 쿼리만 덮는 필터는 그중 어느 것도 덮지 않는다. +- [ ] **장애** — 연결 재사용이 테넌트 context를 흘리지 않는다. failover가 쓰기 뒤 읽기를 조용히 낡은 replica로 보내지 않는다. + 커밋 모호함 시나리오가 여전히 맞게 동작한다. +- [ ] **마이그레이션** — 테넌트별 마이그레이션은 부분 실패 뒤 이어서 할 수 있고, 속도가 제한된다. 테넌트마다 schema가 하나면 + 실행 한 번은 독립 마이그레이션 N개이고, 「실패했다」는 답이 아니다. +- [ ] **성능** — 풀 용량, 부하에서의 replica 지연, 테넌트별 메모리를 어림하지 않고 잰다. 테넌트마다 DB를 두는 방식은 풀 + 하나가 아니라 합으로 실패한다. -## Decision +## 결정 -- [ ] **Reviewed ADR** — recording what is being promised, the operational burden it carries, and - what would cause it to be withdrawn. +- [ ] **검토한 ADR** — 무엇을 약속하는지, 그것이 지우는 운영 부담, 무엇이 생기면 거두는지를 기록한다. -The ADR is not a formality. The technical suites establish that something works; the ADR records -that the platform should promise it, which is a different question with a different cost. +ADR은 형식이 아니다. 기술 suite는 무언가가 동작함을 세우고, ADR은 플랫폼이 그것을 약속해야 함을 기록한다. 다른 질문이고 +비용도 다르다. -## What does not count as evidence +## 증거로 치지 않는 것 -- The version being generally available. -- The feature working in one environment. -- A passing suite that skipped because Docker was unavailable. -- A green lane whose assertions were relaxed to make it pass. +- 그 버전이 GA라는 사실. +- 그 기능이 한 환경에서 동작한다는 사실. +- Docker가 없어서 건너뛰고 통과한 suite. +- 통과시키려고 단언을 느슨하게 한 초록 lane. -## Outcomes +## 결과 -| Decision | Meaning | +결과 이름은 지운 `ExperimentalPromotionGate`가 쓰던 것이고, 지금은 리뷰어가 판정을 적는 말이다. + +| 결정 | 뜻 | |---|---| -| `BLOCKED_TECHNICAL` | at least one suite has not passed | -| `BLOCKED_MISSING_ADR` | evidence is complete; no reviewed decision exists | -| `ELIGIBLE_FOR_STABLE_REVIEW` | both; Stable review may begin | +| `BLOCKED_TECHNICAL` | 통과하지 않은 suite가 하나 이상 있다 | +| `BLOCKED_MISSING_ADR` | 증거는 다 있고, 검토한 결정이 없다 | +| `ELIGIBLE_FOR_STABLE_REVIEW` | 둘 다 있다. Stable 리뷰를 시작해도 된다 | -The two blocked states are distinct because they need different work: one needs evidence, the other -needs a decision. +막힌 상태 둘을 나누는 이유는 필요한 일이 달라서다. 하나는 증거가, 다른 하나는 결정이 필요하다. diff --git a/docs/jpa/experimental-support-matrix.md b/docs/jpa/experimental-support-matrix.md index 99e4e862..15bee87f 100644 --- a/docs/jpa/experimental-support-matrix.md +++ b/docs/jpa/experimental-support-matrix.md @@ -1,43 +1,35 @@ -# Experimental Support Matrix +# Experimental 지원 매트릭스 -Experimental code is library code in `dev.caskeleton.adapter.outbound.persistence.experimental`. -Nothing composes it and no setting turns it on: a deployment that wants one of these creates the -entry point in its own adapter code, and that call is the opt-in. None of it is part of the Stable -composition, and `JpaModuleBoundaryTest` keeps Stable packages from depending on it. +Experimental 코드는 `dev.caskeleton.adapter.outbound.persistence.experimental`의 라이브러리 코드다. 그것을 조립하는 것도, 켜는 +설정도 없다. 이 중 하나를 원하는 배포는 자기 어댑터 코드에서 진입점을 만들고, 그 호출이 opt-in이다. 어느 것도 Stable 조립에 +들어가지 않고, `JpaModuleBoundaryTest`가 Stable 패키지가 그것에 의존하지 못하게 막는다. -| Feature | Entry point | Evidence (PostgreSQL lane unless noted) | State | +| 기능 | 진입점 | 증거(따로 적지 않으면 PostgreSQL lane) | 상태 | |---|---|---|---| -| Shared-schema multi-tenancy (column) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental | +| 공유 schema multi-tenancy(열) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental | | PostgreSQL RLS multi-tenancy | `rls.RlsTenantSessionBinder`, `rls.RlsPolicyVerifier` | `RlsIsolationFailureTest` | Experimental | -| Schema-per-tenant | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental | -| Database-per-tenant pool budget | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental | -| Consistency-aware read replica | `replica.ConsistencyAwareDataSourceRouter` (you implement `ReplicaLagMonitor`) | `ReadAfterWriteRoutingContractTest` | Experimental | -| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | none — probes in `.github/workflows/jpa-next.yml` record `NOT_EXECUTABLE` | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest` (unit-lane version canaries) | Not executable | +| 테넌트마다 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) | 실행 불가 | -The `backend.jpa.experimental.*` flags and `ExperimentalFeatureGate` that used to front these were -removed on 2026-09-25: no code read the flags from configuration, so setting one did nothing, and -the gate only checked a map the caller built itself. +> 이력: 이것들 앞에 있던 `backend.jpa.experimental.*` 스위치와 `ExperimentalFeatureGate`는 2026-09-25에 지웠다. 어떤 코드도 +> 설정에서 스위치를 읽지 않아서 켜도 아무 일이 없었고, gate는 호출자가 스스로 만든 map만 확인했다. -## 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. +- 테넌트 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는 메트릭 태그가 되지 않는다. 테넌트 수는 정의상 상한이 없다. -## Lanes never change Stable +## lane은 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. +호환성 lane은 아무것도 게시하지 않고 어떤 Stable 계약도 바꾸지 않는다. Hibernate 8이 fetch-pagination gate에 다른 SQL을 +만들면 그것은 Hibernate 8에 대한 발견이다. 7.x gate는 7.x가 해야 할 것을 계속 단언한다. 배포가 돌리는 것이 그것이기 때문이다. diff --git a/docs/jpa/migration-guide.md b/docs/jpa/migration-guide.md index 0a6b3e61..3d00664d 100644 --- a/docs/jpa/migration-guide.md +++ b/docs/jpa/migration-guide.md @@ -1,198 +1,165 @@ -# Migration Guide +# 마이그레이션 가이드 -Design §31-§32. Flyway owns the schema; Hibernate only validates. +설계서 §31-§32. 스키마는 Flyway가 가지고, Hibernate는 검증만 한다. -## Who may change the schema +이 문서의 절 셋은 코드와 다른 문서가 영어 제목으로 가리킨다. 그래서 그 절 제목에는 영어 이름을 괄호로 함께 둔다: +「누가 스키마를 바꾸나 (Who may change the schema)」, 「잠금 대기에 상한을 둔다 (Bound the lock wait)」, +「동시 인덱스 빌드 (Concurrent index builds)」. -| Environment | Mode | +## 누가 스키마를 바꾸나 (Who may change the schema) + +| 환경 | 방식 | |---|---| -| local, test, dev | migrate at startup with the migration credential | -| staging, prod | deployment-owned migration; the application validates only | +| local, test, dev | 마이그레이션 자격 증명으로 기동할 때 migrate한다 | +| staging, prod | 배포가 가진 마이그레이션. 애플리케이션은 검증만 한다 | -Migrating from inside the application in production means every instance of a rolling deploy races -to apply the same script, and the loser's failure is indistinguishable from a real one. +운영에서 애플리케이션 안에서 migrate하면 rolling deploy의 모든 인스턴스가 같은 스크립트를 적용하려고 경주하고, 진 쪽의 +실패는 진짜 실패와 구별되지 않는다. -Whoever runs the migration holds Flyway's PostgreSQL migration lock for the session, not in a -transaction: `flyway.postgresql.transactional.lock=false`. Flyway's default (`true`) keeps a -transaction open until the whole run ends, and a concurrent index build waits for every transaction -older than itself, Flyway's own included — the deploy stops with no error and no time limit -("Concurrent index builds" below). The template sets it for every Flyway it runs: the module -defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock: -false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every -stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest` -refuses production code that builds a Flyway any other way: calling `Flyway.configure()`, or -constructing a configuration itself (`new FluentConfiguration()`, `new ClassicConfiguration()`, a -subclass of either, or `FluentConfiguration::new`). `new Flyway(...)` over the policy's configuration -is allowed. The deployment-owned migration of -staging and prod is outside this repository: give its tool the same value -(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file). +마이그레이션을 돌리는 쪽은 Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션이 아니라 세션에 둔다: +`flyway.postgresql.transactional.lock=false`. Flyway의 기본값(`true`)은 실행 전체가 끝날 때까지 트랜잭션을 열어 두고, +동시 인덱스 빌드는 Flyway 자신의 것을 포함해 자기보다 오래된 모든 트랜잭션을 기다린다. 그러면 배포가 오류도 시간 상한도 +없이 멈춘다(아래 「동시 인덱스 빌드」). 템플릿은 자기가 돌리는 모든 Flyway에 이 값을 둔다. Spring Boot가 기동할 때 만드는 +Flyway에는 module defaults(`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock: +false`)가, 스스로 만드는 stream에는 `FlywaySchemaPolicy.configure()`가 그렇게 한다. 서비스 자신의 stream도 거기서 +시작하고, `JpaProductionArchitectureTest`는 다른 방법으로 Flyway를 만드는 운영 코드를 거부한다. `Flyway.configure()`를 +부르거나, 설정을 직접 만드는 것(`new FluentConfiguration()`, `new ClassicConfiguration()`, 그 둘의 subclass, +`FluentConfiguration::new`)이다. 정책의 설정 위에 `new Flyway(...)`를 하는 것은 허용한다. staging과 prod의 배포 쪽 +마이그레이션은 이 저장소 밖에 있다. 그 도구에도 같은 값을 준다(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, 또는 그 도구 +설정 파일의 위 키). -A session lock assumes the connection Flyway takes stays its own for the whole run, which the -template's direct Hikari connection gives. Behind a pooler in transaction mode (PgBouncer -`pool_mode = transaction`) the unlock can reach another server connection and release nothing, and -the next migration waits for a lock that a pooled connection still holds. Run migrations over a -direct connection or a session-mode pool. +세션 잠금은 Flyway가 잡은 연결이 실행 내내 Flyway의 것으로 남는다고 가정한다. 템플릿의 직접 Hikari 연결이 그것을 준다. +트랜잭션 모드 pooler(PgBouncer `pool_mode = transaction`) 뒤에서는 unlock이 다른 서버 연결로 가서 아무것도 풀지 못하고, +다음 마이그레이션은 풀의 연결이 아직 쥔 잠금을 기다린다. 마이그레이션은 직접 연결이나 세션 모드 풀로 돌린다. -`ddl-auto` is `validate` or `none`. Never `update`: it never drops or narrows anything, so it -produces a schema that is neither the old one nor the one the migrations describe — silently, on -whichever instance started first. +`ddl-auto`는 `validate`나 `none`이다. `update`는 절대 쓰지 않는다. 그것은 아무것도 지우거나 좁히지 않으므로, 옛 스키마도 +아니고 마이그레이션이 설명하는 스키마도 아닌 스키마를 만든다. 조용히, 먼저 뜬 인스턴스에서. -## Validation fails closed and never repairs +## 검증은 닫힌 채 실패하고, repair하지 않는다 -At startup Flyway's own validation (and Hibernate `ddl-auto=validate`) refuses a checksum mismatch, -a missing migration, or a schema Hibernate disagrees with. Nothing in the application calls -`repair`. In tests, the testkit's `FlywayValidationGate` turns a failed `ValidateResult` into -`SchemaMismatchException`; the migration contract tests use it. +기동할 때 Flyway 자신의 검증(과 Hibernate `ddl-auto=validate`)이 checksum 불일치, 빠진 마이그레이션, Hibernate가 동의하지 +않는 스키마를 거부한다. 애플리케이션의 어떤 것도 `repair`를 부르지 않는다. 테스트에서는 testkit의 `FlywayValidationGate`가 +실패한 `ValidateResult`를 `SchemaMismatchException`으로 바꾸고, 마이그레이션 계약 테스트가 그것을 쓴다. -Repair rewrites the schema history table to match whatever scripts are on disk. That resolves the -symptom by deleting the evidence: a checksum mismatch means the deployed script differs from the -applied one, and the interesting question is which change is missing from this database. Repair -makes that question unaskable. It exists only as an explicit admin operation with an operator, a -reason, and an approval (design §8.4). +repair는 schema history 테이블을 디스크에 있는 스크립트에 맞춰 다시 쓴다. 그것은 증거를 지워서 증상을 없앤다. checksum +불일치는 배포한 스크립트가 적용된 것과 다르다는 뜻이고, 물어야 할 것은 이 DB에 어느 변경이 빠졌느냐다. repair는 그 질문을 +물을 수 없게 만든다. repair는 운영자, 이유, 승인이 있는 명시적 관리 작업으로만 있다(설계서 §8.4). -The one change to the history an operator makes is narrower than repair: after a concurrent index -migration fails, the failed row of that one version is deleted so that the version can run again -("Concurrent index builds" below). Every applied row, and its checksum, stays as it was. +운영자가 이력에 하는 변경은 repair보다 좁은 것 하나다. 동시 인덱스 마이그레이션이 실패한 뒤, 그 버전을 다시 돌릴 수 있게 +그 한 버전의 실패 행을 지운다(아래 「동시 인덱스 빌드」). 적용된 행과 그 checksum은 모두 그대로다. -Only Flyway's structured error codes reach the exception. Its messages embed the script path and -part of the failing statement. +예외에는 Flyway의 구조화된 오류 코드만 닿는다. Flyway의 메시지는 스크립트 경로와 실패한 문장 일부를 담는다. -## Bound the lock wait +## 잠금 대기에 상한을 둔다 (Bound the lock wait) -A migration that locks a table already in use starts with `SET LOCAL lock_timeout = '5s';`, before -the first statement that takes the lock. `ALTER TABLE` takes the strongest lock there is, which -conflicts even with a plain read; a non-concurrent `CREATE INDEX` takes one that stops every write; -`UPDATE` and `DELETE` wait on the rows other transactions hold. Unbounded, the migration waits for -the oldest open transaction that touched the table — an operator's forgotten `BEGIN` in psql has no -deadline — and every read and write that arrives meanwhile queues behind the migration, holding a -pool connection while it waits. With the bound, the migration fails after five seconds, Flyway -rolls it back whole, the database stays on the version before it and the new release does not -start: a failed deploy instead of an outage. Deploy again when the transaction has ended. +이미 쓰는 테이블을 잠그는 마이그레이션은, 잠금을 잡는 첫 문장 전에 `SET LOCAL lock_timeout = '5s';`로 시작한다. +`ALTER TABLE`은 가장 강한 잠금을 잡아 평범한 읽기와도 부딪친다. 동시가 아닌 `CREATE INDEX`는 모든 쓰기를 멈추는 잠금을 +잡는다. `UPDATE`와 `DELETE`는 다른 트랜잭션이 쥔 행을 기다린다. 상한이 없으면 마이그레이션은 그 테이블을 건드린 가장 오래된 +열린 트랜잭션을 기다린다. psql에서 운영자가 잊은 `BEGIN`에는 마감이 없다. 그사이 도착하는 모든 읽기와 쓰기가 마이그레이션 +뒤에 줄을 서고, 기다리는 동안 풀 연결을 쥔다. 상한이 있으면 마이그레이션은 5초 뒤 실패하고, Flyway가 통째로 롤백하고, DB는 +그 앞 버전에 남고, 새 릴리스는 뜨지 않는다. 장애 대신 실패한 배포다. 그 트랜잭션이 끝난 뒤 다시 배포한다. -`LOCAL`, because a plain `SET` outlives the migration on the pooled connection Flyway borrowed and -changes every statement that later runs on it. The value is not zero: `lock_timeout = 0` (or -`DEFAULT`, or a later `RESET`) is no bound at all. A migration with `executeInTransaction=false` -cannot use it — `SET LOCAL` outside a transaction only warns — so a statement that locks a table -goes into a migration that runs in one. A statement on a table the same migration created a moment -earlier waits for nothing and needs no bound; `CREATE TABLE IF NOT EXISTS` does not count, because -the table may already be there. +`LOCAL`인 이유: 평범한 `SET`은 Flyway가 빌린 풀 연결에서 마이그레이션보다 오래 남아, 나중에 그 연결에서 도는 모든 문장을 +바꾼다. 값은 0이 아니다. `lock_timeout = 0`(또는 `DEFAULT`, 뒤의 `RESET`)은 상한이 아니다. `executeInTransaction=false`인 +마이그레이션은 그것을 쓸 수 없다. 트랜잭션 밖의 `SET LOCAL`은 경고만 하기 때문이다. 그래서 테이블을 잠그는 문장은 +트랜잭션 안에서 도는 마이그레이션에 넣는다. 같은 마이그레이션이 방금 만든 테이블에 대한 문장은 기다릴 것이 없어 상한이 +필요 없다. `CREATE TABLE IF NOT EXISTS`는 해당하지 않는다. 테이블이 이미 있을 수 있기 때문이다. -Flyway also takes a migration out of its transaction on its own, without a `.sql.conf`: on -PostgreSQL 12 and later, any statement that starts with `VACUUM`, `CREATE [UNIQUE] INDEX -CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE` or -`DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM` or `DISCARD ALL` (Flyway 11, -`PostgreSQLParser`; words inside parentheses are skipped, so `VACUUM (FULL)` and `REINDEX (VERBOSE) -SCHEMA` count). One such statement puts the whole script outside a transaction. Next to any other -statement — a `SET LOCAL lock_timeout` included — Flyway refuses the migration at deploy under its -default `mixed=false`; a service that sets `mixed=true` gets it run, with the bound silently gone. -Put such a statement in a migration of its own. `REINDEX TABLE|INDEX CONCURRENTLY` is not on -Flyway's list: Flyway runs it in the transaction, PostgreSQL refuses it there, and it needs -`executeInTransaction=false` (below). A locking statement that cannot run in a transaction at all — -`VACUUM FULL`, a non-concurrent `REINDEX SCHEMA|DATABASE|SYSTEM` — can never be bounded this way and -does not belong in a migration: run it by hand as an operations step, outside a deploy, in a psql -session that sets `SET lock_timeout = '5s';` first (the session ends with the step, so the plain -`SET` is the bound there). A `.sql.conf` with `executeInTransaction=true` does not change that: it -keeps the statement and its `SET LOCAL` in the transaction only for PostgreSQL to refuse it at -deploy, and the inspector below refuses it as well. +Flyway는 `.sql.conf` 없이도 스스로 마이그레이션을 트랜잭션 밖으로 뺀다. PostgreSQL 12 이상에서 `VACUUM`, `CREATE [UNIQUE] +INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE`나 +`DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM`, `DISCARD ALL`로 시작하는 문장이 있으면 그렇다(Flyway 11, +`PostgreSQLParser`. 괄호 안의 낱말은 건너뛰므로 `VACUUM (FULL)`과 `REINDEX (VERBOSE) SCHEMA`도 센다). 그런 문장 하나가 +스크립트 전체를 트랜잭션 밖에 둔다. 다른 문장(`SET LOCAL lock_timeout` 포함) 옆에 두면 Flyway는 기본값 `mixed=false`에서 +배포 때 그 마이그레이션을 거부한다. `mixed=true`로 둔 서비스는 그것을 돌리지만 상한이 조용히 사라진다. 그런 문장은 따로 +마이그레이션 하나에 넣는다. `REINDEX TABLE|INDEX CONCURRENTLY`는 Flyway의 목록에 없다. Flyway는 그것을 트랜잭션 안에서 +돌리고 PostgreSQL이 거기서 거부하므로 `executeInTransaction=false`가 필요하다(아래). 트랜잭션 안에서 아예 돌 수 없는 잠그는 +문장(`VACUUM FULL`, 동시가 아닌 `REINDEX SCHEMA|DATABASE|SYSTEM`)은 이 방법으로 상한을 둘 수 없고 마이그레이션에 넣지 않는다. +배포 밖에서 운영 단계로 손으로 돌린다. 먼저 `SET lock_timeout = '5s';`를 거는 psql 세션에서 한다(세션이 그 단계와 함께 +끝나므로 거기서는 평범한 `SET`이 상한이다). `executeInTransaction=true`인 `.sql.conf`도 이것을 바꾸지 못한다. 그 문장과 +`SET LOCAL`을 트랜잭션 안에 둘 뿐이고, 배포 때 PostgreSQL이 거부하며, 아래의 inspector도 거부한다. -Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script — -and the `.sql.conf` beside it, as Flyway reads it (a properties file, `false` in any case), and -otherwise the statements Flyway takes out of the transaction on its own — and names the statements -from its list that lock an existing table with no bound in force: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, `DROP TABLE`; `CREATE INDEX`, -`DROP INDEX`, `REINDEX` and `REFRESH MATERIALIZED VIEW` without `CONCURRENTLY`, `CLUSTER`, `VACUUM -FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a -foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER` -on their table; `UPDATE` and `DELETE`. It reads text, so a statement outside the list is not -checked. `MigrationLockWaitTest`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스 -스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 Flyway와 같은 방식으로 마이그레이션을 찾고, 소수 -버전(`V22_1__`)도 포함한다(`VersionedMigrationFiles`, testkit). The migrations released before the rule wait unbounded and -stay that way (they are applied, and applied files are never edited); the test lists them and -refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest` -(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration -gives up within the bound while another transaction holds the table, and leaves the version below -it; it also compares the inspector's copy of Flyway's list with Flyway itself for the statements it -lists (each is named by the inspector exactly when Flyway refuses it next to a `SET LOCAL`), and -shows a `VACUUM FULL` run under `mixed=true` waiting out a reader despite its `SET LOCAL`. A -statement a Flyway upgrade adds to the list is outside that comparison; `LockWaitMigrationInspectorTest` -pins Flyway's own patterns (`PostgreSQLParser`), so such an upgrade fails the pull request's `ci` -until the copy follows. The gRPC ledger's tree lives in the -optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigrationLockWaitIT` -runs every ledger migration after V001, read from the tree, against a held ledger instead, so its -next migration is checked on real PostgreSQL. It finds and orders that tree with the testkit's own -`VersionedMigrationFiles`, which the ledger's `build.gradle` copies into its integration-test sources -at build time (`sharedMigrationFileSources`), so both builds read one definition. A concurrent index -build in that tree runs outside a transaction and is no case for a held ledger: it goes in the -test's `RUN_OUTSIDE_A_TRANSACTION` with its reason, and the same test holds each file listed there to -`ConcurrentIndexMigrationInspector`, copied the same way ("Concurrent index builds"). Every ledger -lane applies the tree one file at a time, as Flyway does, so such a file is not refused inside the -implicit transaction of one string holding many. The rule came -from V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2, -RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02, -RR6-03-03; round 7, RR7-03-01). +기억에 맡기지 않고 강제한다. `LockWaitMigrationInspector`(persistence-jpa testkit)가 스크립트를 읽는다. 옆의 `.sql.conf`도 +Flyway처럼 읽고(properties 파일, 대소문자 상관없이 `false`), 그 밖에는 Flyway가 스스로 트랜잭션 밖으로 빼는 문장을 본다. +그리고 상한 없이 이미 있는 테이블을 잠그는, 자기 목록의 문장을 이름 댄다: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, +`DROP TABLE`; `CONCURRENTLY` 없는 `CREATE INDEX`, `DROP INDEX`, `REINDEX`, `REFRESH MATERIALIZED VIEW`, `CLUSTER`, +`VACUUM FULL`; 참조하는 테이블에 대한 `REFERENCES`(새 테이블에서도 `ALTER TABLE`에서도. foreign key는 추가되는 동안 부모 +테이블의 쓰기를 막는다); 그 테이블의 `CREATE TRIGGER`와 `DROP TRIGGER`; `UPDATE`와 `DELETE`. 텍스트를 읽으므로 목록 밖의 +문장은 확인하지 않는다. `MigrationLockWaitTest`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스 +스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 Flyway와 같은 방식으로 마이그레이션을 찾고, 소수 버전 +(`V22_1__`)도 포함한다(`VersionedMigrationFiles`, testkit). 규칙 전에 나간 마이그레이션은 상한 없이 기다리고 그대로 둔다 +(이미 적용됐고, 적용된 파일은 고치지 않는다). 테스트가 그것을 나열하고 새것은 거부한다. -## Concurrent index builds +`PostgreSqlMigrationLockWaitIntegrationTest`(`postgresqlMigrationLockWaitIntegrationTest`)가 실제 PostgreSQL에서 보인다. +다른 트랜잭션이 테이블을 쥔 동안 상한 있는 마이그레이션은 상한 안에 포기하고 그 아래 버전을 남긴다. 또 inspector가 가진 +Flyway 목록 사본을 그것이 나열한 문장에 대해 Flyway 자신과 비교하고(inspector는 Flyway가 `SET LOCAL` 옆에서 거부하는 바로 +그때 그 문장을 이름 댄다), `mixed=true`에서 돈 `VACUUM FULL`이 `SET LOCAL`에도 불구하고 읽는 쪽을 기다리는 것도 보인다. +Flyway 업그레이드가 목록에 더한 문장은 그 비교 밖이다. `LockWaitMigrationInspectorTest`가 Flyway 자신의 패턴 +(`PostgreSQLParser`)을 고정하므로, 그런 업그레이드는 사본이 따라올 때까지 pull request의 `ci`를 실패시킨다. -`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` cannot run -inside a transaction block. Flyway runs a script outside a transaction on its own when it holds -`CREATE`/`DROP INDEX CONCURRENTLY` or `REINDEX SCHEMA|DATABASE`, with or without `CONCURRENTLY` -(above). It runs `REINDEX INDEX|TABLE … CONCURRENTLY` — `REINDEX (CONCURRENTLY) TABLE` included — in -the transaction, where PostgreSQL refuses it. `PostgreSqlMigrationLockWaitIntegrationTest` shows the -five forms on real PostgreSQL. Write the companion configuration for every concurrent statement -anyway, so the file says what it needs and no reader has to know Flyway's list: +gRPC ledger의 트리는 optional 빌드에 있어서 testkit에 의존할 수 없다. 그래서 그 `GrpcOperationLedgerMigrationLockWaitIT`가 +트리에서 읽은 V001 뒤의 모든 ledger 마이그레이션을 대신 쥔 ledger에 대고 돌리므로, 다음 마이그레이션도 실제 PostgreSQL에서 +확인된다. 그 트리를 찾고 순서를 매기는 것은 testkit 자신의 `VersionedMigrationFiles`다. ledger의 `build.gradle`이 빌드 때 +그것을 통합 테스트 소스로 복사하므로(`sharedMigrationFileSources`) 두 빌드가 한 정의를 읽는다. 그 트리의 동시 인덱스 빌드는 +트랜잭션 밖에서 돌므로 쥔 ledger로 시험할 경우가 아니다. 그런 파일은 이유와 함께 테스트의 `RUN_OUTSIDE_A_TRANSACTION`에 +넣고, 같은 테스트가 거기 나열한 파일마다 같은 방식으로 복사한 `ConcurrentIndexMigrationInspector`를 건다(「동시 인덱스 +빌드」). 모든 ledger lane은 Flyway처럼 트리를 파일 하나씩 적용하므로, 그런 파일이 여러 문장을 담은 문자열 하나의 암묵적 +트랜잭션 안에서 거부되지 않는다. + +이 규칙은 같은 커밋에서 V21에는 상한이 있고 V22에는 없었던 데서 나왔다(재확인 리뷰 2026-11-03 round 2, RR-02-09; round 3, +RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02, RR6-03-03; round 7, RR7-03-01). + +## 동시 인덱스 빌드 (Concurrent index builds) + +`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`는 트랜잭션 블록 안에서 돌 수 없다. Flyway는 +스크립트가 `CREATE`/`DROP INDEX CONCURRENTLY`나 `REINDEX SCHEMA|DATABASE`(`CONCURRENTLY`가 있든 없든)를 담으면 스스로 +트랜잭션 밖에서 돌린다(위). `REINDEX INDEX|TABLE … CONCURRENTLY`(`REINDEX (CONCURRENTLY) TABLE` 포함)는 트랜잭션 안에서 +돌리고, PostgreSQL이 거기서 거부한다. `PostgreSqlMigrationLockWaitIntegrationTest`가 다섯 꼴을 실제 PostgreSQL에서 보인다. +그래도 모든 동시 문장에 짝 설정을 쓴다. 파일이 자기에게 필요한 것을 말하고, 읽는 사람이 Flyway의 목록을 알 필요가 없다. ```conf # V42__order_index.sql.conf executeInTransaction=false ``` -Outside a transaction, `CREATE INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` still wait until -every transaction older than them has ended. Under Flyway's default lock that includes the -transaction Flyway itself keeps open, and Flyway waits for the build in turn: the deploy never ends, -and the table's other DDL and autovacuum queue behind the build meanwhile. The template's Flyway -holds its lock for the session instead ("Who may change the schema"), so the build waits only for -other transactions; a deployment tool left on Flyway's default stops on the first such migration. -`DROP INDEX CONCURRENTLY` does not wait that way: it waits only for the transactions that hold a -lock on its table. `PostgreSqlConcurrentIndexMigrationIntegrationTest` -(`postgresqlConcurrentIndexMigrationIntegrationTest`) applies both builds as a second deploy, with -the Flyway Spring Boot builds from the module defaults and with `FlywaySchemaPolicy.configure()`, -on real PostgreSQL. The other transactions still count: a long one an operator or a report keeps -open holds the build, and the drop too once it has touched the table, and a file run outside a -transaction cannot bound that wait with `SET LOCAL`. Look for old transactions -(`pg_stat_activity.xact_start`) before deploying one. +트랜잭션 밖에서도 `CREATE INDEX CONCURRENTLY`와 `REINDEX … CONCURRENTLY`는 자기보다 오래된 모든 트랜잭션이 끝날 때까지 +기다린다. Flyway 기본 잠금에서는 Flyway 자신이 열어 둔 트랜잭션도 거기 들고, Flyway는 다시 빌드를 기다린다. 배포가 끝나지 +않고, 그동안 그 테이블의 다른 DDL과 autovacuum이 빌드 뒤에 줄을 선다. 템플릿의 Flyway는 대신 세션에 잠금을 둔다(「누가 +스키마를 바꾸나」). 그래서 빌드는 다른 트랜잭션만 기다린다. Flyway 기본값에 둔 배포 도구는 그런 첫 마이그레이션에서 멈춘다. +`DROP INDEX CONCURRENTLY`는 그렇게 기다리지 않는다. 그 테이블에 잠금을 쥔 트랜잭션만 기다린다. +`PostgreSqlConcurrentIndexMigrationIntegrationTest`(`postgresqlConcurrentIndexMigrationIntegrationTest`)가 두 빌드를 두 번째 +배포로, module defaults로 Spring Boot가 만드는 Flyway와 `FlywaySchemaPolicy.configure()`로, 실제 PostgreSQL에 적용한다. +다른 트랜잭션은 여전히 센다. 운영자나 리포트가 열어 둔 긴 트랜잭션은 빌드를 붙잡고, 테이블을 건드린 뒤라면 삭제도 붙잡는다. +트랜잭션 밖에서 도는 파일은 그 대기에 `SET LOCAL`로 상한을 둘 수 없다. 그런 마이그레이션을 배포하기 전에 오래된 트랜잭션 +(`pg_stat_activity.xact_start`)을 찾는다. -The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test -(nothing checks it at startup), and additionally requires the migration to contain nothing else. -Next to another statement, a concurrent one makes Flyway refuse the file before any of it runs when -nothing configures it; with `executeInTransaction=false` Flyway commits each statement on its own, -and a failed build leaves the statements before it applied — state to reconstruct by hand. +testkit의 `ConcurrentIndexMigrationInspector`가 마이그레이션 테스트에서 스크립트를 이 관점으로 확인하고(기동 때 확인하는 +것은 없다), 그 마이그레이션에 다른 것이 없기를 더 요구한다. 다른 문장 옆에 두면, 아무것도 설정하지 않았을 때 동시 문장은 +Flyway가 파일을 하나도 돌리기 전에 거부하게 만든다. `executeInTransaction=false`면 Flyway는 문장마다 따로 커밋하고, 실패한 +빌드는 그 앞 문장을 적용된 채 남긴다. 손으로 다시 맞춰야 하는 상태다. -Alone, a failed statement leaves an invalid index and a history row with `success = false` for its -version, and Flyway refuses every later deploy ("Detected failed migration to version …") until that -row is gone: dropping the index is not enough. The recovery is -[migration-failed.md](../runbooks/migration-failed.md) "Recover a failed concurrent index migration": -confirm no build is running, remove the cause, drop the invalid index a failed build or rebuild -left, delete that version's failed row and nothing else, deploy again. A failed `DROP INDEX -CONCURRENTLY` leaves invalid the index it was dropping; the runbook leaves that one for the deploy -again to drop, since dropped by hand it makes the same statement fail. It is not `flyway repair`, -which would also rewrite the remaining rows' checksums. `PostgreSqlConcurrentIndexMigrationIntegrationTest` -(`postgresqlConcurrentIndexMigrationIntegrationTest`) runs the runbook's SQL, read from the runbook, -after a unique build that failed on a duplicate and after a rebuild and a drop cancelled while they -waited for an open transaction, and shows both mixed files above. +혼자 있는 문장이 실패하면 무효 인덱스와 그 버전의 `success = false` 이력 행을 남기고, 그 행이 사라질 때까지 Flyway는 뒤의 +모든 배포를 거부한다("Detected failed migration to version …"). 인덱스를 지우는 것만으로는 안 된다. 복구는 +[migration-failed.md](../runbooks/migration-failed.md) 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent +index migration)」다. 도는 빌드가 없는지 확인하고, 원인을 없애고, 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지우고, 그 +버전의 실패 행만 지우고, 다시 배포한다. 실패한 `DROP INDEX CONCURRENTLY`는 지우던 인덱스를 무효로 남긴다. runbook은 그것을 +다시 배포가 지우도록 남긴다. 손으로 지우면 같은 문장이 실패하기 때문이다. 이것은 `flyway repair`가 아니다. repair는 남은 행의 +checksum도 다시 쓴다. `PostgreSqlConcurrentIndexMigrationIntegrationTest`(`postgresqlConcurrentIndexMigrationIntegrationTest`)가 +runbook에서 읽은 runbook의 SQL을, 중복으로 실패한 unique 빌드 뒤와, 열린 트랜잭션을 기다리다 취소된 재빌드와 삭제 뒤에 돌리고, +위의 섞인 파일 둘도 보인다. -An invalid index is not merely useless — the planner ignores it while every write still maintains -it. [runbooks.md](runbooks.md) has the query that finds them. Nothing drops them automatically: an -invalid index can also mean a build is still running, and the two are indistinguishable from the -catalog alone. +무효 인덱스는 쓸모없기만 한 게 아니다. planner는 그것을 무시하는데 모든 쓰기는 여전히 그것을 유지한다. 찾는 쿼리는 +[runbooks.md](runbooks.md)에 있다. 아무것도 그것을 자동으로 지우지 않는다. 무효 인덱스는 아직 도는 빌드를 뜻할 수도 있고, +카탈로그만으로는 둘을 구별할 수 없다. -## Upgrade scenarios +## 업그레이드 시나리오 -Three, each catching something the others do not: +셋이고, 저마다 다른 것이 못 잡는 것을 잡는다. -| Scenario | Catches | +| 시나리오 | 잡는 것 | |---|---| -| `empty` | an early migration edited to match a later one, no longer applying to a fresh database | -| `previous-release` | the actual deployment path; the only one exercising this release's migrations | -| `oldest-supported` | a migration that silently assumes state only recent databases have | +| `empty` | 뒤 마이그레이션에 맞추려고 고친 앞 마이그레이션이 새 DB에 더는 적용되지 않음 | +| `previous-release` | 실제 배포 경로. 이 릴리스의 마이그레이션을 돌리는 유일한 시나리오 | +| `oldest-supported` | 최근 DB에만 있는 상태를 몰래 가정하는 마이그레이션 | -Each asserts a data invariant, not just the schema version. A migration that renames a column and -loses its contents leaves the version correct and the data gone. +시나리오마다 스키마 버전만이 아니라 데이터 불변식을 단언한다. 열 이름을 바꾸면서 내용을 잃은 마이그레이션은 버전은 맞고 +데이터는 사라진 채로 남는다. diff --git a/docs/jpa/observability.md b/docs/jpa/observability.md index ad05f819..24d74828 100644 --- a/docs/jpa/observability.md +++ b/docs/jpa/observability.md @@ -1,58 +1,49 @@ -# Observability +# 관측 -Design §37. What is measured, and what must never appear in a measurement. +설계서 §37. 무엇을 재고, 측정에 무엇이 절대 나타나면 안 되나. -## What is emitted by default +## 기본으로 내는 것 -Nothing JPA-specific. No composition constructs a `MeterRegistry`-backed observation for the -platform, and `SpringTransaction` records no transaction metric. The `jpa.transaction.*` meters -this page used to list (`duration`, `rollback`, `timeout`, `completion.unknown`) were produced by -`JpaTransactionObservation`, which nothing constructed; it was removed on 2026-09-25 -(`docs/capability-status.md`). Transaction outcomes are visible through the shared persistence error -codes and the application's own metrics, not through a JPA meter. +JPA 고유의 것은 없다. 어떤 조립도 플랫폼에 `MeterRegistry` 기반 observation을 만들지 않고, `SpringTransaction`은 트랜잭션 +메트릭을 기록하지 않는다. 트랜잭션 결과는 JPA meter가 아니라 공유 영속성 오류 코드와 애플리케이션 자신의 메트릭으로 보인다. -## Query metrics — only when the caller asks +> 이력: 이 문서가 전에 적던 `jpa.transaction.*` meter(`duration`, `rollback`, `timeout`, `completion.unknown`)는 +> `JpaTransactionObservation`이 만들었는데, 그것을 만드는 곳이 없어서 2026-09-25에 지웠다(`docs/capability-status.md`). -`jpa.query.duration` and `jpa.query.rows` are recorded by `MicrometerQueryObservation`, and only -when a service passes it to a library executor that accepts a `QueryObservation` -(`JpaStreamExecutor`, `HibernateBulkDmlExecutor`). The default is `NoopQueryObservation`. Rows are -measured as well as duration because a query that issues one statement and hydrates twenty thousand -rows is fast per statement and catastrophic per request — a duration metric alone reports it as -merely slow. +## 쿼리 메트릭 — 호출자가 요청할 때만 -## Bounded tags, always +`jpa.query.duration`과 `jpa.query.rows`는 `MicrometerQueryObservation`이 기록한다. 서비스가 `QueryObservation`을 받는 라이브러리 +executor(`JpaStreamExecutor`, `HibernateBulkDmlExecutor`)에 그것을 넘길 때만이다. 기본값은 `NoopQueryObservation`이다. 걸린 +시간뿐 아니라 행도 재는 이유가 있다. 문장 하나를 내고 행 2만 개를 채우는 쿼리는 문장으로는 빠르고 요청으로는 재앙이다. 걸린 +시간 메트릭만으로는 그저 느리다고 보고된다. -Every meter `MicrometerQueryObservation` records carries exactly five tags: persistence unit, -operation, query, outcome, failure category (`JpaMetricTags`). All five are registered identifiers, -validated by `LowCardinality` at construction rather than at the registry — so an unbounded value -fails where it was introduced instead of surviving until a dashboard stops loading. +## 태그는 늘 상한이 있다 -Never a tag: entity id, tenant id, SQL parameter, exception message, JDBC URL. Each is unbounded, so -each creates a time series per row or per failure; several are also the data the platform keeps out -of logs, which a metrics backend would store just as durably and export just as widely. +`MicrometerQueryObservation`이 기록하는 meter는 모두 태그를 정확히 다섯 가진다. persistence unit, operation, query, outcome, +failure category(`JpaMetricTags`)다. 다섯 다 등록된 식별자이고, registry가 아니라 만들 때 `LowCardinality`가 검증한다. 그래서 +상한 없는 값은 대시보드가 안 열릴 때까지 살아남지 않고, 들어온 자리에서 실패한다. -## Query names in SQL +절대 태그가 아닌 것: entity id, tenant id, SQL 파라미터, 예외 메시지, JDBC URL. 하나하나가 상한이 없어서 행마다나 실패마다 +시계열을 만든다. 몇은 플랫폼이 로그에서도 빼는 데이터이고, 메트릭 backend는 그것을 로그만큼 오래 저장하고 넓게 내보낸다. -`JpaRepositoryFragmentSupport` sets the registered query name as the `org.hibernate.comment` hint; -Hibernate writes it into the SQL only when `hibernate.use_sql_comments=true`. The alternative is -`NamedStatementInspector`, which prefixes a statement with the query name bound by -`JpaStreamExecutor`, `JpaKeysetQuerySupport` or `JpaRepositoryFragmentSupport.observing(..)`. -Neither is on by default: a deployment enables the inspector with -`spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector`. -The comment then travels into `pg_stat_activity`, `auto_explain`, and the slow-query log. Without it, -"which endpoint issues this query" is answered by grepping the codebase for fragments of SQL. +## SQL 안의 쿼리 이름 -## Diagnostics +`JpaRepositoryFragmentSupport`는 등록한 쿼리 이름을 `org.hibernate.comment` hint로 둔다. Hibernate는 +`hibernate.use_sql_comments=true`일 때만 그것을 SQL에 쓴다. 다른 길은 `NamedStatementInspector`다. `JpaStreamExecutor`, +`JpaKeysetQuerySupport`, `JpaRepositoryFragmentSupport.observing(..)`이 묶은 쿼리 이름을 문장 앞에 붙인다. 둘 다 기본으로 꺼져 +있다. 배포는 +`spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector`로 +inspector를 켠다. 그러면 주석이 `pg_stat_activity`, `auto_explain`, slow query 로그로 간다. 그것이 없으면 「어느 엔드포인트가 이 +쿼리를 내나」는 코드에서 SQL 조각을 grep해서 답한다. -`SqlDiagnosticRedactor.redact(sql)` removes string literals, numbers, and anything email-shaped. It is -a utility for code that is about to log SQL; nothing in the platform logs SQL through it. Redaction -is blunt on purpose: preserving "harmless" values would require knowing which columns hold personal -data. +## 진단 -## The actuator endpoint +`SqlDiagnosticRedactor.redact(sql)`은 문자열 literal, 숫자, 이메일 모양의 모든 것을 지운다. SQL을 곧 로그에 쓸 코드를 위한 +도구다. 플랫폼 안의 어떤 것도 그것을 거쳐 SQL을 로그에 쓰지 않는다. 지우기는 일부러 거칠다. 「해롭지 않은」 값을 남기려면 +어느 열이 개인정보를 담는지 알아야 한다. -`jpaplatform` reports database major version, provider version, schema version, OSIV state, runtime -role verification, and capability levels. It reports no JDBC URL, no username, no SQL, and no entity -catalog — an actuator endpoint is reachable by anyone who reaches the management port, and each of -those would be a free reconnaissance answer. It is read-only: an endpoint that could trigger a -migration or a repair would be an admin capability exposed over HTTP. +## actuator 엔드포인트 + +`jpaplatform`은 DB major 버전, provider 버전, 스키마 버전, OSIV 상태, 런타임 역할 검증, capability 수준을 보고한다. JDBC URL, +사용자 이름, SQL, 엔티티 목록은 보고하지 않는다. actuator 엔드포인트는 management 포트에 닿는 누구나 닿을 수 있고, 그 하나하나가 +공짜 정찰 답이 된다. 읽기 전용이다. 마이그레이션이나 repair를 일으킬 수 있는 엔드포인트는 HTTP로 드러난 관리 capability가 된다. diff --git a/docs/jpa/postgresql-extensions.md b/docs/jpa/postgresql-extensions.md index 2124e0e8..e13d0b67 100644 --- a/docs/jpa/postgresql-extensions.md +++ b/docs/jpa/postgresql-extensions.md @@ -1,50 +1,43 @@ -# PostgreSQL Extensions +# PostgreSQL 확장 기능 -Design §8.3, §21, §30. What the platform uses beyond portable JPA, and what each is guarded by. +설계서 §8.3, §21, §30. 플랫폼이 이식 가능한 JPA 너머에서 무엇을 쓰고, 각각을 무엇이 지키나. -Everything here is core PostgreSQL. No server extension is required. +여기 있는 것은 모두 PostgreSQL core다. 서버 extension은 필요 없다. -## Locking +## 잠금 -`SELECT ... FOR UPDATE` with a finite bound, always. `PostgreSqlLockOptions` refuses an unbounded -lock request because it waits as long as the holder holds it, turning one slow transaction into a -pile-up of blocked connections. +`SELECT ... FOR UPDATE`에는 늘 유한한 상한을 둔다. `PostgreSqlLockOptions`는 상한 없는 잠금 요청을 거부한다. 쥔 쪽이 쥐는 만큼 +기다리므로, 느린 트랜잭션 하나가 막힌 연결 더미가 된다. -`NOWAIT` and a wait timeout are separate requests, not two spellings of one — modelling them as a -single field with a magic zero is how "no wait" becomes "wait forever". +`NOWAIT`와 대기 시간 상한은 같은 것의 두 표기가 아니라 다른 요청이다. 둘을 마법의 0을 가진 칸 하나로 모델링하면 「기다리지 +않음」이 「영원히 기다림」이 된다. -`55P03` (lock not available) and `40P01` (deadlock) drive opposite recovery and are never collapsed: -the first leaves the transaction alive and the caller in control; the second has already been rolled -back by the server. +`55P03`(잠금을 얻을 수 없음)과 `40P01`(교착)은 반대 복구로 이어지므로 합치지 않는다. 앞의 것은 트랜잭션을 살려 두고 호출자에게 +통제를 남긴다. 뒤의 것은 서버가 이미 롤백했다. ## JSONB -`JsonDocument` carries a schema name and version alongside the payload. A JSONB column is schemaless -at the database level, so without an envelope the only record of what a stored document means is the -code that wrote it — and a document written two releases ago is indistinguishable from a current one. +`JsonDocument`는 payload와 함께 schema 이름과 버전을 싣는다. JSONB 열은 DB 수준에서 schema가 없으므로, envelope가 없으면 저장된 +문서가 무엇을 뜻하는지 기록한 것은 그것을 쓴 코드뿐이다. 두 릴리스 전에 쓴 문서와 지금 문서를 구별할 수 없다. -The payload never carries a Java class name. Type metadata in a JSONB column is a deserialization -gadget: whoever can write a row chooses the class the reader instantiates. +payload에는 Java 클래스 이름을 절대 싣지 않는다. JSONB 열의 타입 메타데이터는 deserialization gadget이다. 행을 쓸 수 있는 누구나 +읽는 쪽이 만들 클래스를 고른다. -Query paths are registered. A JSON path is part of the SQL text and cannot be bound, so forwarding a -request field into one is concatenating untrusted input into a statement. Values are always bound. +쿼리 경로는 등록한다. JSON 경로는 SQL 문장의 일부라 묶을 수 없으므로, 요청 칸을 그것에 넘기면 믿을 수 없는 입력을 문장에 이어 +붙이는 것이다. 값은 늘 묶는다. -## Arrays and ranges +## 배열과 범위 -Arrays are built with `Connection.createArrayOf`, never by formatting a literal — hand-formatting is -where quoting bugs live, and a tag containing a comma changes the array's shape rather than its -content. +배열은 literal을 꾸미지 않고 `Connection.createArrayOf`로 만든다. 손으로 꾸미면 quoting 버그가 생기고, 쉼표가 든 태그는 배열의 +내용이 아니라 모양을 바꾼다. -`PgRange` models both endpoints as independently optional and independently inclusive, because that -is what a PostgreSQL range is. Whether `[09:00, 10:00)` and `[10:00, 11:00)` overlap depends on the -bracket, not the values, and a pair of `timestamptz` columns cannot express it. +`PgRange`는 두 끝을 저마다 선택적으로, 저마다 포함 여부를 따로 모델링한다. PostgreSQL range가 그렇기 때문이다. +`[09:00, 10:00)`과 `[10:00, 11:00)`이 겹치는지는 값이 아니라 괄호가 정하고, `timestamptz` 열 한 쌍으로는 그것을 나타낼 수 없다. ## COPY (J4 admin) -`COPY` bypasses the Persistence Context, entity callbacks, version checks, and Envers entirely. That -is why it is fast and why it is an admin capability with a registered statement, a bounded stream, a -row and byte cap, a finite server-side `statement_timeout`, and a named operator. +`COPY`는 Persistence Context, 엔티티 callback, 버전 확인, Envers를 모두 건너뛴다. 그래서 빠르고, 그래서 관리 capability다. 등록한 +문장, 상한 있는 stream, 행·바이트 상한, 유한한 서버 쪽 `statement_timeout`, 이름 있는 운영자가 필요하다. -The registry accepts only `COPY ... FROM STDIN`. `COPY ... FROM '/path'` reads a file on the -*database server* as the server's OS user; it is superuser-only for exactly that reason and does not -belong behind an application API. +registry는 `COPY ... FROM STDIN`만 받는다. `COPY ... FROM '/path'`는 *DB 서버*의 파일을 서버 OS 사용자로 읽는다. 바로 그 +이유로 superuser 전용이고, 애플리케이션 API 뒤에 둘 것이 아니다. diff --git a/docs/jpa/query-fetch-guide.md b/docs/jpa/query-fetch-guide.md index 75b023ad..a3e5dbd2 100644 --- a/docs/jpa/query-fetch-guide.md +++ b/docs/jpa/query-fetch-guide.md @@ -1,75 +1,63 @@ -# Query and Fetch Guide +# 쿼리와 fetch 가이드 -Design §23-§28. How queries are chosen, bounded, and proven. +설계서 §23-§28. 쿼리를 어떻게 고르고, 제한하고, 증명하나. -## Named queries +## 이름 있는 쿼리 -Every registered query carries a `QueryName`. It is the tag `MicrometerQueryObservation` records -under and the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the -only thing that connects a statement on the server back to the use case that issued it. Neither is on -by default; [observability.md](observability.md) says how a deployment turns each on. The format rejects raw -SQL for a reason: a metric tag built from a query string is unbounded by construction, and one built -from a parameterised value leaks row data into telemetry. +등록한 쿼리는 모두 `QueryName`을 가진다. 그것은 `MicrometerQueryObservation`이 기록하는 태그이고, `pg_stat_activity`와 +slow query 로그에 나타나는 SQL 주석이다. 서버의 문장을 그것을 낸 use case와 잇는 것은 그것뿐이다. 둘 다 기본으로 꺼져 +있다. 배포가 각각을 켜는 법은 [observability.md](observability.md)에 있다. 형식이 원본 SQL을 거부하는 데는 이유가 있다. 쿼리 +문자열로 만든 메트릭 태그는 처음부터 상한이 없고, 파라미터 값으로 만든 것은 행 데이터를 원격 측정으로 흘린다. -## Fetch plans, not eager mappings +## eager 매핑이 아니라 fetch 계획 -N+1 is solved per use case with a registered entity graph, not by making an association `EAGER` in -the mapping. The eager fix repairs the one query that needed it and imposes the extra join on every -other query against that entity, including the ones that only wanted the id. +N+1은 매핑에서 연관을 `EAGER`로 만들어서가 아니라 use case마다 등록한 entity graph로 푼다. eager 고침은 그것이 필요했던 쿼리 +하나를 고치고, 그 엔티티에 대한 다른 모든 쿼리에 추가 join을 지운다. id만 원했던 쿼리까지. -`fetchgraph` and `loadgraph` are different: a fetch graph is exhaustive (attributes outside it are -lazy whatever the mapping says), a load graph is additive. Choosing the wrong one produces either -missing data or the amplification the graph was meant to avoid. +`fetchgraph`와 `loadgraph`는 다르다. fetch graph는 빠짐없는 목록이고(그 밖의 속성은 매핑이 뭐라고 하든 lazy다), load graph는 +더하는 것이다. 잘못 고르면 데이터가 빠지거나, graph가 피하려던 증폭이 생긴다. -## Measuring, not guessing +## 짐작하지 말고 잰다 -`QueryMeasurement` records statements, hydrated entities, rows, fetches, and elapsed time. Statement -count alone cannot distinguish the two failures that matter: +`QueryMeasurement`는 문장, 채운 엔티티, 행, fetch, 걸린 시간을 기록한다. 문장 수만으로는 중요한 두 실패를 가릴 수 없다. -- **N+1** — many statements, few rows. -- **Cartesian fetch** — one statement, an enormous number of rows. +- **N+1** — 문장은 많고 행은 적다. +- **Cartesian fetch** — 문장은 하나이고 행은 엄청나게 많다. -A suite asserting only on statement count passes the second one every time. +문장 수만 단언하는 suite는 두 번째를 늘 통과시킨다. -## Pagination +## 페이지 나누기 -Offset pagination makes the database walk and discard `n` rows before returning any. Keyset -pagination replaces it: +offset 페이지 나누기는 DB가 무엇이든 돌려주기 전에 `n`행을 지나가며 버리게 한다. keyset 페이지 나누기가 그것을 대신한다. -- The predicate is lexicographic. For an ordering of `(createdAt, id)`, "after `(t, x)`" is - `createdAt < t OR (createdAt = t AND id < x)` — **not** `createdAt <= t AND id < x`, which reads - plausibly and silently drops rows from the middle of the result set. -- The ordering must end in a unique column. Without one, a page boundary inside a run of equal - values duplicates and skips rows. -- `size + 1` rows are fetched and `size` returned. That extra row answers `hasNext` without a count - query, which would be a second full scan whose answer is stale on arrival. +- 조건은 사전순이다. `(createdAt, id)` 정렬에서 「`(t, x)` 다음」은 `createdAt < t OR (createdAt = t AND id < x)`다. + `createdAt <= t AND id < x`가 **아니다.** 그것은 그럴듯해 보이지만 결과 중간의 행을 조용히 빠뜨린다. +- 정렬은 unique 열로 끝나야 한다. 그렇지 않으면 같은 값이 이어지는 구간 안의 페이지 경계가 행을 중복하고 건너뛴다. +- `size + 1`행을 읽고 `size`를 돌려준다. 그 한 행이 count 쿼리 없이 `hasNext`에 답한다. count 쿼리는 두 번째 전체 scan이고, + 답이 도착할 때 이미 낡았다. -Cursors are signed. An unsigned cursor is client-controlled ordering state: rewriting it lets a -caller seek to arbitrary keys. +cursor에는 서명한다. 서명 없는 cursor는 클라이언트가 다루는 정렬 상태다. 그것을 고치면 호출자가 아무 키로나 건너뛸 수 있다. -## Sorting +## 정렬 -Client sort parameters are mapped through `SafeSortRegistry`, never passed through. A sort field -reaches the query as part of the ORDER BY clause rather than as a bound value, so forwarding the -client's string means the client writes part of the statement. `JpaSort.unsafe` has no call site in -this platform. +클라이언트의 정렬 파라미터는 그대로 넘기지 않고 `SafeSortRegistry`로 매핑한다. 정렬 칸은 묶은 값이 아니라 ORDER BY 절의 +일부로 쿼리에 닿으므로, 클라이언트의 문자열을 넘기면 클라이언트가 문장의 일부를 쓰게 된다. `JpaSort.unsafe`는 이 플랫폼에서 +부르는 곳이 없다. -The registry's tie-breaker is always appended, because a sort that does not end in a unique column -has no total order and paging over a non-total order duplicates and skips rows. +registry의 tie-breaker는 늘 덧붙인다. unique 열로 끝나지 않는 정렬은 전체 순서가 없고, 전체 순서가 아닌 것으로 페이지를 +나누면 행이 중복되고 건너뛰어진다. -## Streaming +## streaming -A JPA `Stream` is a live cursor holding a `ResultSet`, a statement, and a connection. `JpaStreamExecutor` -consumes it inside a try-with-resources and never returns it, because a stream returned past the -transaction boundary is a connection leak that presents as unrelated timeouts elsewhere. A read-only -transaction is required: streaming inside a write transaction pins a write connection for the whole -traversal. +JPA `Stream`은 `ResultSet`, 문장, 연결을 쥔 살아 있는 cursor다. `JpaStreamExecutor`는 그것을 try-with-resources 안에서 다 쓰고 +절대 돌려주지 않는다. 트랜잭션 경계 밖으로 돌려준 stream은 연결 누수이고, 다른 곳의 상관없어 보이는 시간 초과로 나타난다. +읽기 전용 트랜잭션이 필요하다. 쓰기 트랜잭션 안의 streaming은 순회 내내 쓰기 연결을 붙잡는다. -## Batching +## batching -Configuring `hibernate.jdbc.batch_size` proves nothing. `BatchExecutionResult.jdbcBatches` comes from -counting real `executeBatch()` calls at the JDBC layer, because an IDENTITY generator, an interleaved -select, or a mid-loop flush disables batching while the configuration still says it is on. +`hibernate.jdbc.batch_size`를 설정한 것은 아무것도 증명하지 않는다. `BatchExecutionResult.jdbcBatches`는 JDBC 층에서 실제 +`executeBatch()` 호출을 세서 나온다. IDENTITY generator, 끼어든 select, 반복 중간의 flush는 설정이 켜져 있다고 말하는 동안 +batching을 꺼 버리기 때문이다. -Flush and clear are separate boundaries. Flushing alone sends the statements and keeps every entity -in the Persistence Context — the classic bulk-import out-of-memory. +flush와 clear는 다른 경계다. flush만 하면 문장은 보내지만 모든 엔티티를 Persistence Context에 남긴다. 대량 import의 전형적인 +메모리 부족이다. diff --git a/docs/jpa/repository-adaptation.md b/docs/jpa/repository-adaptation.md index c0b3a490..2bb8bcf2 100644 --- a/docs/jpa/repository-adaptation.md +++ b/docs/jpa/repository-adaptation.md @@ -1,165 +1,147 @@ -# JPA Relational Persistence Platform — Repository Adaptation Contract +# JPA 관계형 영속성 플랫폼 — 저장소 대응 계약 -**Design source:** `docs/design/2026-08-11-jpa-persistence-platform-design.md` -**Stable plan source:** `docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md` -**Experimental plan source:** `docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md` +**설계 출처:** `docs/design/2026-08-11-jpa-persistence-platform-design.md` +**Stable 계획 출처:** `docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md` +**Experimental 계획 출처:** `docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md` -The design package states its own adaptation rule (§3.2): the assumed package paths and Gradle -structure are explicit implementation *assumptions* made because the real Backend Skeleton -repository was not supplied. Before implementing, paths are adjusted to the repository's existing -conventions and root package while the public contracts and policy semantics are preserved. +설계 패키지는 자기 대응 규칙을 스스로 밝힌다(§3.2). 가정한 패키지 경로와 Gradle 구조는 실제 Backend Skeleton 저장소를 +받지 못해서 둔 명시적 구현 *가정*이다. 구현 전에 공개 계약과 정책 의미는 지키면서 경로를 저장소의 기존 관례와 root 패키지에 +맞춘다. -This file is the single record of *how* that mapping was performed. Only paths, build DSL, and -composition-root ownership changed. Public contracts, policy order, retry semantics, and error -semantics are implemented as specified. +이 파일은 그 대응을 *어떻게* 했는지 적는 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트 소유뿐이다. 공개 계약, 정책 +순서, 재시도 의미, 오류 의미는 명세대로 구현했다. -## 1. Why the module layout differs +## 1. 모듈 배치가 다른 이유 -The plan assumes a greenfield library with 18 Stable Gradle projects under `modules/jpa/` plus 7 -Experimental projects under `modules/jpa-experimental/`. This repository is a Clean Architecture -template whose **fail-closed registry** (`src/config/architecture/modules.json`, enforced by -`src/settings.gradle` and `verifyCleanArchitectureDependencies`) declares **exactly 19 leaf -identities**, and `src/settings.gradle` throws when the registry does not contain exactly 19 -modules. Creating 25 more Gradle projects would violate HARD-STOP #5 in `AGENTS.md`. +계획은 `modules/jpa/` 아래 Stable Gradle 프로젝트 18개와 `modules/jpa-experimental/` 아래 Experimental 프로젝트 7개를 둔 +새 라이브러리를 가정한다. 이 저장소는 **fail-closed registry**(`src/config/architecture/modules.json`)를 가진 Clean +Architecture 템플릿이다. `src/settings.gradle`은 registry를 읽고 검증한 뒤 등록된 프로젝트만 들이고, +`verifyCleanArchitectureDependencies`가 그 밖의 edge를 막는다. leaf 목록은 registry가 정한다. 계획의 Gradle 프로젝트를 +새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다. -Therefore the plan's library modules become **package boundaries inside the registered leaf** -`:adapter:outbound:persistence-jpa`, with two exceptions driven by this repository's own rules. -This is the same adaptation already applied to the HTTP client platform -(`docs/httpclient/repository-adaptation.md`). +그래서 계획의 라이브러리 모듈은 등록 leaf `:adapter:outbound:persistence-jpa` **안의 패키지 경계**가 된다. 예외는 이 저장소 +자신의 규칙에서 나온 둘이다. HTTP 클라이언트 플랫폼에 이미 한 것과 같은 대응이다(`docs/httpclient/repository-adaptation.md`). -| Plan module | Repository home | Reason | +| 계획 모듈 | 저장소 위치 | 이유 | |---|---|---| -| `jpa-spring-boot-starter` | `:adapter:outbound:persistence-jpa` (`…persistence.autoconfigure`, `…persistence.startup`) | Relational persistence is a capability module selected by one build line (`AGENTS.md` capability rules): the leaf registers its own auto-configuration, startup validation, actuator view and shipped settings, and the default composition does not carry it. Use-case assembly over its ports (the outbox relay) stays in `app-bootstrap`. | -| `jpa-testkit`, `jpa-testkit-postgresql`, `jpa-testkit-migration`, `jpa-testkit-queryplan` | `:adapter:outbound:persistence-jpa` `src/testkit/java/**/testkit` | The plan forbids production modules depending on the testkit. A source set whose dependencies are declared only on test configurations gives the same guarantee without a new Gradle project, and more than one lane consumes it. | +| `jpa-spring-boot-starter` | `:adapter:outbound:persistence-jpa` (`…persistence.autoconfigure`, `…persistence.startup`) | 관계형 영속성은 빌드 한 줄로 고르는 capability 모듈이다(`AGENTS.md` capability 규칙). leaf가 자기 auto-configuration, 기동 검증, actuator view, 내보내는 설정을 등록하고, 기본 조립은 그것을 싣지 않는다. 그 port 위의 use case 조립(outbox relay)은 `composition:outbox-relay`에 있다. | +| `jpa-testkit`, `jpa-testkit-postgresql`, `jpa-testkit-migration`, `jpa-testkit-queryplan` | `:adapter:outbound:persistence-jpa` `src/testFixtures/java/**/testkit` | 계획은 운영 모듈이 testkit에 의존하는 것을 막는다. 의존을 test 설정에만 선언한 source set이 새 Gradle 프로젝트 없이 같은 보장을 주고, 여러 lane이 그것을 쓴다. | -The package boundary is enforced by `JpaModuleBoundaryTest`. It holds a closed catalog of the -production root's direct child packages, compares that catalog against the tree for exact equality, -checks every observed top-level edge against the declared ones, and rejects cycles. +패키지 경계는 `JpaModuleBoundaryTest`가 강제한다. 운영 root의 바로 아래 자식 패키지를 닫힌 목록으로 들고, 그 목록을 +트리와 정확히 같은지 비교하고, 관찰한 최상위 edge를 모두 선언한 것과 대조하고, cycle을 거부한다. -This used to be a stronger claim than the test. The catalog listed thirteen packages while the tree -held twenty-two, so nine — `audit`, `config`, `failure`, `fileserver`, `h2`, `idempotency`, `lock`, -`notification`, `outbox` — were governed by nothing, and a `transaction → postgresql` / -`postgresql → transaction` cycle passed. Both are closed now, and the catalog's exact-equality check -is what keeps a new package from being green by omission. +> 이력: 전에는 문서의 주장이 테스트보다 강했다. 목록은 패키지 13개였는데 트리에는 22개가 있어서, 아홉 개(`audit`, +> `config`, `failure`, `fileserver`, `h2`, `idempotency`, `lock`, `notification`, `outbox`)를 아무것도 다스리지 않았고 +> `transaction → postgresql` / `postgresql → transaction` cycle이 통과했다. 둘 다 닫았다. 새 패키지가 빠져서 초록이 되지 +> 않게 막는 것은 목록의 정확히-같음 검사다. -**Known gap.** The catalog governs top-level packages. Sub-package edges inside one top-level -package are not checked, and the target tree in the review's JPA-023 (a `capability/*` layout) is -not implemented — the notification configuration facade is the first step toward it. +**알려진 빈틈.** 목록은 최상위 패키지를 다스린다. 한 최상위 패키지 안의 하위 패키지 edge는 확인하지 않는다. 리뷰 +JPA-023의 목표 트리(`capability/*` 배치)는 구현하지 않았다. 알림 설정 facade가 그쪽으로 가는 첫걸음이다. -## 2. Package mapping +## 2. 패키지 대응 -Root package: `io.backend.skeleton.jpa` → `dev.caskeleton.adapter.outbound.persistence`. +root 패키지: `io.backend.skeleton.jpa` → `dev.caskeleton.adapter.outbound.persistence`. -| Plan module | Plan package | Repository package | +| 계획 모듈 | 계획 패키지 | 저장소 패키지 | |---|---|---| -| `jpa-core-api` | `…jpa.api` (+ `.capability`, `.error`, `.query`, `.transaction`) | `dev.caskeleton.adapter.outbound.persistence.api` (+ same subpackages) | +| `jpa-core-api` | `…jpa.api` (+ `.capability`, `.error`, `.query`, `.transaction`) | `dev.caskeleton.adapter.outbound.persistence.api` (+ 같은 하위 패키지) | | `jpa-transaction` | `…jpa.transaction` | `…persistence.transaction` | | `jpa-spring-data` | `…jpa.springdata` | `…persistence.springdata` | | `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` | -| `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ same subpackages) | -| `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ same subpackages except `.write`, removed 2026-09-25) | +| `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ 같은 하위 패키지) | +| `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ `.write`를 뺀 같은 하위 패키지. `.write`는 2026-09-25에 지움) | | `jpa-postgresql-copy` | `…jpa.postgresql.copy` | `…persistence.postgresql.copy` | | `jpa-migration-flyway` | `…jpa.migration` | `…persistence.migration` | -| `jpa-auditing` | `…jpa.auditing` | none — removed; `…persistence.audit.AuditableEntity` is the one audit mechanism | +| `jpa-auditing` | `…jpa.auditing` | 없음 — 지웠다. `…persistence.audit.AuditableEntity`가 유일한 감사 방식이다 | | `jpa-envers` | `…jpa.envers` | `…persistence.envers` | | `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` | | `jpa-observability` | `…jpa.observation` | `…persistence.observation` | | `jpa-security` | `…jpa.security` | `…persistence.security` | | `jpa-spring-boot-starter` | `…jpa.autoconfigure` | `…persistence.autoconfigure`, `…persistence.startup` | -| `jpa-testkit*` | `…jpa.testkit` (+ `.id`, `.mapping`, `.lifecycle`, `.query`, `.fetch`, `.postgresql`, `.migration`, `.queryplan`, `.failure`, `.pool`, `.release`) | `…persistence.testkit` (+ same subpackages), `testkit` source set | -| `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ same subpackages except `.next`, removed 2026-09-25) | +| `jpa-testkit*` | `…jpa.testkit` (+ `.id`, `.mapping`, `.lifecycle`, `.query`, `.fetch`, `.postgresql`, `.migration`, `.queryplan`, `.failure`, `.pool`, `.release`) | `…persistence.testkit` (+ 같은 하위 패키지), `testFixtures` source set | +| `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ `.next`를 뺀 같은 하위 패키지. `.next`는 2026-09-25에 지움) | -The existing `…persistence.transaction` and `…persistence.postgresql` packages already hold this -leaf's `TransactionPort` implementation and PostgreSQL vendor composition. The platform types are -**additive**: no existing type was renamed, moved, or replaced, and no plan type collides with an -existing name. +이미 있던 `…persistence.transaction`과 `…persistence.postgresql` 패키지는 이 leaf의 `TransactionPort` 구현과 PostgreSQL +vendor 조립을 이미 가지고 있다. 플랫폼 타입은 **더하기만** 했다. 이름을 바꾸거나 옮기거나 대신한 기존 타입은 없고, 기존 +이름과 부딪치는 계획 타입도 없다. -## 3. Test-suite mapping +## 3. 테스트 suite 대응 -The plan declares seven JVM test suites (`test`, `integrationTest`, `contractTest`, -`migrationTest`, `failureTest`, `performanceTest`, `compatibilityTest`). This leaf already owns a -Docker-backed `postgresqlIntegrationTest` source set and its readiness Gradle tasks are registered -as strict lanes in this leaf's `build.gradle`; `JpaReadinessRegistryTest` holds the readiness cards -to those lanes (it replaced the build-tools `verifyJpaReadinessRegistry`). +계획은 JVM 테스트 suite 일곱을 선언한다(`test`, `integrationTest`, `contractTest`, `migrationTest`, `failureTest`, +`performanceTest`, `compatibilityTest`). 이 leaf는 이미 Docker를 쓰는 `postgresqlIntegrationTest` source set을 가지고, +그 readiness Gradle 태스크는 이 leaf의 `build.gradle`에 strict lane으로 등록돼 있다. `JpaReadinessRegistryTest`가 readiness +card를 그 lane과 대조한다(build-tools의 `verifyJpaReadinessRegistry`를 대신했다). -| Plan suite | Repository lane | +| 계획 suite | 저장소 lane | |---|---| -| `test` | `src/test` — hermetic unit lane, `./gradlew :adapter:outbound:persistence-jpa:test` | -| `contractTest`, `integrationTest`, `migrationTest`, `failureTest`, `compatibilityTest` | `src/postgresqlIntegrationTest` — real PostgreSQL containers; selected by the `jpaPlatform*` Gradle tasks | -| `performanceTest` | `src/jpaPlatformPerformanceTest` — pool and `REQUIRES_NEW` connection behaviour, run by `jpaPlatformPoolContractTest`; never part of `check`. The source set keeps the plan's name; the lane asserts behaviour rather than measuring, and no numeric performance bound is claimed anywhere from it. | +| `test` | `src/test` — 밀폐된 unit lane, `./gradlew :adapter:outbound:persistence-jpa:test` | +| `contractTest`, `integrationTest`, `migrationTest`, `failureTest`, `compatibilityTest` | `src/postgresqlIntegrationTest` — 실제 PostgreSQL 컨테이너. `jpaPlatform*` Gradle 태스크가 고른다 | +| `performanceTest` | `src/jpaPlatformPerformanceTest` — 풀과 `REQUIRES_NEW` 연결 동작. `jpaPlatformPoolContractTest`가 돌리고, `check`에는 절대 들어가지 않는다. source set은 계획의 이름을 그대로 쓴다. 이 lane은 측정하지 않고 동작을 단언하며, 그로부터 어떤 성능 수치도 주장하지 않는다. | -Docker-dependent lanes fail closed rather than skipping, matching the existing -`PostgreSqlReadinessSupport.assertDockerAvailable()` convention in this leaf. +Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 leaf의 기존 관례 `PostgreSqlReadinessSupport.assertDockerAvailable()`과 +같다. -## 4. Other deliberate substitutions +## 4. 그 밖에 일부러 바꾼 것 -| Plan assumption | Repository reality | Adaptation | +| 계획의 가정 | 저장소의 실제 | 대응 | |---|---|---| -| Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, root `src/build.gradle` conventions (spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, one-type-per-file), `LockMode.STRICT` dependency locking | Source sets and dependencies declared in `src/adapter/outbound/persistence-jpa/build.gradle`; `gradle.lockfile` regenerated with `resolveAndLockAll --write-locks`. | -| Spring Boot 4.1 dependency management, Spring Data JPA 4.1 | Repository baseline is Spring Boot 4.0.8 | Versions are inherited from the repository BOM and never pinned per module, exactly as the plan requires ("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). | -| Hibernate ORM 7.4 is the Stable provider | Boot 4.0.0 resolves `org.hibernate.orm:hibernate-core:7.1.8.Final` | The *declared* Stable provider baseline of the design stays 7.4 in `HibernateProviderPolicy`; the runtime provider version is read from Hibernate itself and reported. The collection-fetch-pagination gate runs against whatever provider the BOM resolves, and `HibernateProviderPolicy.driftsFromDeclaredBaseline()` makes the difference visible instead of hiding it behind a green check. | -| PostgreSQL 16·17·18 Stable matrix | This leaf's existing evidence image is `postgres:16-alpine` | `PostgreSqlVersion` declares exactly PG 16, 17, 18. The default lane runs the repository's existing 16 image; 17 and 18 are selected by `-Pjpa.matrix.versions=16,17,18`, and an unknown or empty selection is an error rather than a skip. | -| `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. | +| Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, `src/build-logic`의 convention plugin(Java로 씀: spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, 파일 하나에 타입 하나), `LockMode.STRICT` 의존성 잠금 | source set과 의존성은 `src/adapter/outbound/persistence-jpa/build.gradle`에 선언했다. `gradle.lockfile`은 `resolveAndLockAll --write-locks`로 다시 만들었다. | +| Spring Boot 4.1 의존성 관리, Spring Data JPA 4.1 | 저장소 기준선은 `src/gradle/libs.versions.toml`의 Spring Boot 버전이다 | 버전은 저장소 BOM에서 물려받고 모듈마다 고정하지 않는다. 계획이 요구하는 그대로다("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). | +| Hibernate ORM 7.4가 Stable provider | 저장소 BOM이 `org.hibernate.orm:hibernate-core:7.1.8.Final`을 푼다(release registry의 `stable-tested-baseline`) | 설계의 *선언* Stable provider 기준선은 `HibernateProviderPolicy`에서 7.4로 남는다. 런타임 provider 버전은 Hibernate 자신에게서 읽어 보고한다. collection-fetch-pagination gate는 BOM이 푸는 provider에서 돌고, `HibernateProviderPolicy.driftsFromDeclaredBaseline()`이 차이를 초록 검사 뒤에 숨기지 않고 드러낸다. | +| PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `src/config/testing/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. | +| `settings.gradle.kts` 모듈 등록 | fail-closed registry | registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다. | | `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. | -| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. | -| release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `persistence-jpa/release/release-registry.json`, run per PostgreSQL major by the `jpa-release-gate` job in `.github/workflows/release.yml` | The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix. | | -| Per-task `git add` + `git commit` | `AGENTS.md`: commit policy is `human-only`; agents do not stage, commit, amend, or push | Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here. | -| Querydsl as an optional module dependency | Querydsl is not part of this repository's dependency set | `querydsl` is implemented against the plan's contracts with the Querydsl types kept behind `compileOnly`, so the Stable runtime classpath never carries Querydsl and a deployment opting in adds the artifact itself. | -| Hibernate Envers as a module dependency | Envers is not part of this repository's dependency set | Same treatment as Querydsl: `compileOnly` + explicit opt-in, matching the plan's "Envers is opt-in and never enabled by a global base class". | -| `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt` | There is no `build-logic` project and no Kotlin source set; module boundaries are enforced by the registry itself | `verifyCleanArchitectureDependencies` plus `:app-bootstrap:architectureTest` assert the same property against `src/config/architecture/modules.json`, which is the authority the plan's test would have had to duplicate. | -| `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | The security lane is one suite in this leaf rather than a per-module `integrationTest` | `PostgreSqlSecurityContractTest` (tag `jpa-security`) exercises `PostgreSqlRuntimeRoleVerifier.verify` and `.requireSafe` against a real restricted role on a real server. | -| `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest` requires every `@ConfigurationProperties` type to end in `Settings` or `Policy` | Renamed to `JpaSafetySettings` and `JpaDataSourceSettings`. The bound property prefixes and every field are unchanged; only the class names move to this repository's convention. | +| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. | +| 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.github/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | | +| task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. | +| Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. | +| Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. | +| `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt` | `src/build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `src/config/architecture/modules.json`을 정본으로 강제한다. | +| `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | 보안 lane은 모듈마다의 `integrationTest`가 아니라 이 leaf의 suite 하나다 | `PostgreSqlSecurityContractTest`(tag `jpa-security`)가 실제 서버의 실제 제한 역할에 대고 `PostgreSqlRuntimeRoleVerifier.verify`와 `.requireSafe`를 돌린다. | +| `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest`는 모든 `@ConfigurationProperties` 타입 이름이 `Settings`나 `Policy`로 끝나기를 요구한다 | `JpaSafetySettings`로 이름을 바꿨다. 묶는 속성 prefix와 모든 칸은 그대로이고 클래스 이름만 이 저장소 관례로 옮겼다. `JpaDataSourceProperties`에 해당하는 설정 클래스는 지금 없다. datasource 검사는 `JpaDataSourceProfileValidator`가 한다. | -### Types relocated to keep the dependency direction legal +### 의존 방향을 지키려고 옮긴 타입 -The plan's module map forbids `jpa-core-api` from depending on any other platform module. Three -value-only types the design places in a downstream module are consumed by a core contract, so they -live in the core here instead. Each is a pure value with no framework dependency, so the relocation -costs nothing and the alternative — a core contract importing an adapter package — would break the -boundary the module map exists to hold. +계획의 모듈 지도는 `jpa-core-api`가 다른 플랫폼 모듈에 의존하는 것을 막는다. 설계가 하위 모듈에 둔 값 타입 셋을 core 계약이 +쓰므로, 여기서는 core에 둔다. 셋 다 framework 의존이 없는 순수 값이라 옮기는 비용이 없다. 대안인, core 계약이 어댑터 패키지를 +import하는 것은 모듈 지도가 지키려는 경계를 깬다. -| Type | Plan module | Repository package | Consumed by | +| 타입 | 계획 모듈 | 저장소 패키지 | 쓰는 곳 | |---|---|---|---| -| `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException` (design §17.3 types the field) | -| `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails` (design §22.4) | -| `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | the PostgreSQL translators | +| `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException`(설계서 §17.3이 칸의 타입을 정한다) | +| `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails`(설계서 §22.4) | +| `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | PostgreSQL translator들 | -The ArchUnit rule pack (`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`) -is placed in the `testkit` source set rather than in `…persistence.security` production code. ArchUnit -is a test library; putting the rule pack in `main` would drag it onto every deployment's runtime -classpath to serve code that only ever runs in a test. +ArchUnit 규칙 묶음(`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`)은 `…persistence.security` 운영 +코드가 아니라 `testFixtures` source set에 둔다. ArchUnit은 테스트 라이브러리다. 규칙 묶음을 `main`에 두면 테스트에서만 도는 +코드를 위해 모든 배포의 런타임 classpath에 그것을 끌고 간다. +### 실제 서버에서 계약이 찾은 것 -### Findings the contracts produced against a real server +설계의 규칙 둘이 조금 틀리게 적혀 있었고, 그것을 보여 준 것은 컨테이너 lane이다. 설계서 본문은 여전히 옛 내용이라 여기에 +기록한다. -Two of the design's rules turned out to be stated slightly wrong, and the container lanes are what -showed it. Both are recorded here because the design text still reads the old way. +- **§17.2 커밋 모호함은 SQLSTATE class `08`만이 아니다.** 커밋이 진행 중인 backend에 `pg_terminate_backend`를 하면 연결 + class 상태가 아니라 `57P01`(`admin_shutdown`)을 보고하고, 그것이 도착할 때 커밋 기록은 이미 WAL에 있을 수 있다. 이것을 + 담았던 classifier(`CommitFailureClassifier`)는 2026-09-25에 두 번째 트랜잭션 엔진과 함께 지웠다. + `PostgreSqlConcurrencyFailureContractTest`가 여전히 주입 지점을 고정한다. +- **schema-per-tenant 상태는 실행 결과로 짐작하지 말고 다시 읽어야 한다.** `MigrateResult`의 대상 버전은 이미 최신이던 + tenant에서 비어 있어서, 그것을 기록하면 부분 rollout 중 마이그레이션한 tenant를 안 한 것으로 보고했다. + `SchemaTenantMigrationOrchestrator`가 이제 tenant의 schema history에서 적용된 버전을 읽는다. -- **§17.2 commit ambiguity is not only SQLSTATE class `08`.** `pg_terminate_backend` on a backend - with a commit in flight reports `57P01` (`admin_shutdown`), not a connection-class state — and the - commit record may already be in the WAL when it arrives. The classifier that encoded this - (`CommitFailureClassifier`) was removed with the second transaction engine on 2026-09-25; - `PostgreSqlConcurrencyFailureContractTest` still pins the injection points. -- **Schema-per-tenant status must be read back, not inferred from the run.** `MigrateResult`'s - target version is empty for a tenant that was already current, so recording it reported migrated - tenants as unmigrated during a partial rollout. `SchemaTenantMigrationOrchestrator` now reads the - applied version from the tenant's schema history. +## 5. 설계에서 바뀌지 않은 것 -## 5. What is unchanged from the design - -- Domain owns Entity, Embeddable, Repository, Query, index requirements, lock/soft-delete/audit - policy. No `GenericRepository` and no Spring Data CRUD re-implementation exists. -- Application Service owns the transaction boundary; OSIV is false in every runtime profile. -- `TransactionCompletionUnknownException` always reports `completionUnknown=true`, - `retryable=false`, and is never automatically retried — reconciliation handles it. -- Retry re-executes the whole use case in a new transaction and a new Persistence Context. -- SQLSTATE classification is structural (`40001`, `40003`, `40P01`, `23505`, `23503`, `23514`, - `55P03`) and never parses localized message text. -- Flyway is the source of truth for production schema change; Hibernate only validates; - `ddl-auto` never mutates a deployed schema. -- `CREATE INDEX CONCURRENTLY` requires an explicit non-transactional migration marker. -- Metric labels and ordinary logs never carry SQL parameters, entity IDs, tenant IDs, or PII. -- Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica) are library code - a deployment constructs itself and never enter the Stable composition. JPA 4, Hibernate 8 and - PostgreSQL 19 are `NOT_EXECUTABLE` probes, not features. The `backend.jpa.experimental.*` flags - were removed on 2026-09-25: nothing read them. +- 도메인이 Entity, Embeddable, Repository, Query, 인덱스 요구, lock·soft-delete·감사 정책을 가진다. `GenericRepository`도, + Spring Data CRUD를 다시 구현한 것도 없다. +- Application Service가 트랜잭션 경계를 가진다. OSIV는 모든 런타임 profile에서 false다. +- `TransactionCompletionUnknownException`은 늘 `completionUnknown=true`, `retryable=false`를 보고하고, 자동으로 다시 시도하지 + 않는다. 맞추기가 처리한다. +- 재시도는 use case 전체를 새 트랜잭션과 새 Persistence Context에서 다시 돌린다. +- SQLSTATE 분류는 구조적이다(`40001`, `40003`, `40P01`, `23505`, `23503`, `23514`, `55P03`). 지역화된 메시지 문장을 파싱하지 + 않는다. +- 운영 스키마 변경의 정본은 Flyway다. Hibernate는 검증만 하고, `ddl-auto`는 배포된 스키마를 바꾸지 않는다. +- `CREATE INDEX CONCURRENTLY`에는 명시적인 비트랜잭션 마이그레이션 표시가 필요하다. +- 메트릭 label과 보통 로그에는 SQL 파라미터, entity ID, tenant ID, PII를 싣지 않는다. +- Experimental 기능(multi-tenancy, RLS, schema·database tenancy, read replica)은 배포가 직접 만드는 라이브러리 코드이고 Stable + 조립에 들어가지 않는다. JPA 4, Hibernate 8, PostgreSQL 19는 기능이 아니라 `NOT_EXECUTABLE` probe다. + `backend.jpa.experimental.*` 스위치는 아무것도 읽지 않아서 2026-09-25에 지웠다. diff --git a/docs/jpa/runbooks.md b/docs/jpa/runbooks.md index 6e954dc7..1f95e3fd 100644 --- a/docs/jpa/runbooks.md +++ b/docs/jpa/runbooks.md @@ -1,65 +1,56 @@ -# JPA Platform Runbooks +# JPA 플랫폼 runbook -Operator procedures for the failures this platform is designed to surface rather than hide. +이 플랫폼이 숨기지 않고 드러내도록 설계한 실패에 대한 운영자 절차다. -## A transaction reported completion unknown +## 트랜잭션이 완료를 모른다고 보고했다 -**Signal:** a write use case failed with a commit-phase error (connection lost, `57P01`, class -`08`) from `TransactionPort`. +**신호:** 쓰기 use case가 `TransactionPort`에서 커밋 단계 오류(연결 끊김, `57P01`, class `08`)로 실패했다. -**What it means:** the commit may or may not have happened. It is not a rollback. +**뜻:** 커밋이 됐을 수도 안 됐을 수도 있다. 롤백이 아니다. -**Do not** re-run the use case. That is what the platform refused to do automatically, for the same -reason. +use case를 다시 돌리지 **않는다**. 플랫폼이 같은 이유로 자동으로 하기를 거부한 일이다. -**Procedure:** +**절차:** -1. Take the idempotency key or operation id of the failed request. -2. Check the idempotency record for that key. -3. Check the business row the use case would have written. -4. Check the outbox for a corresponding event. -5. If all three agree the write happened, stop — the request succeeded. -6. If all three agree it did not, the use case may be re-run. -7. If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; - guessing is not. +1. 실패한 요청의 멱등 키나 operation id를 꺼낸다. +2. 그 키의 멱등성 기록을 확인한다. +3. use case가 썼을 업무 행을 확인한다. +4. outbox에 그에 맞는 이벤트가 있는지 확인한다. +5. 셋이 모두 쓰기가 일어났다고 하면 멈춘다. 요청은 성공했다. +6. 셋이 모두 일어나지 않았다고 하면 use case를 다시 돌려도 된다. +7. 서로 다르거나 결론이 나지 않으면 넘긴다. 결론 없음은 정당한 결과다. 짐작은 아니다. -## Deadlock or serialization rate rising +## 교착이나 직렬화 실패 비율이 오른다 -**Signal:** `DB_DEADLOCK` / serialization failures rising in the persistence error codes. +**신호:** 영속성 오류 코드에서 `DB_DEADLOCK`·직렬화 실패가 오른다. -`SpringTransaction` does not retry, so each one reaches the caller. +`SpringTransaction`은 다시 시도하지 않으므로 하나하나가 호출자에게 닿는다. -1. Group the failures by operation. A single operation dominating means a hot row or an - inconsistent lock order. -2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a - code fix, not a tuning one. -3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required. +1. 실패를 operation별로 묶는다. operation 하나가 압도하면 hot row나 어긋난 잠금 순서다. +2. 교착이면 두 operation이 같은 행을 반대 순서로 잡는지 확인한다. 그것은 조정이 아니라 코드를 고칠 일이다. +3. `SERIALIZABLE`에서의 직렬화 실패면 그 격리 수준이 정말 필요한지 확인한다. -## Pool exhaustion +## 풀 고갈 -**Signal:** connection acquisition timeouts; `PoolMeasurement.pending` non-zero. +**신호:** 연결 획득 시간 초과. `PoolMeasurement.pending`이 0이 아니다. -1. Check `REQUIRES_NEW` usage. It takes a second connection while pinning the first, so the pool - must satisfy `(threads x (1 + depth)) + 1`. -2. Check for streaming outside a bounded scope — a `Stream` returned past the transaction holds its - connection until the pool notices. -3. Check for external calls inside a DB transaction. The design forbids them precisely because an - HTTP timeout then holds a connection for its whole duration. +1. `REQUIRES_NEW` 사용을 확인한다. 첫 연결을 쥔 채 두 번째 연결을 잡으므로, 풀은 `(threads x (1 + depth)) + 1`을 채워야 한다. +2. 상한 있는 범위 밖의 streaming을 확인한다. 트랜잭션 밖으로 돌려준 `Stream`은 풀이 알아챌 때까지 연결을 쥔다. +3. DB 트랜잭션 안의 외부 호출을 확인한다. 설계가 그것을 금지하는 이유가 바로 그것이다. 그러면 HTTP 시간 초과가 그 시간 + 내내 연결을 쥔다. -## Flyway validation failed at startup +## 기동할 때 Flyway 검증이 실패했다 -The deployment is running against a schema it was not built for. It failed closed, which is correct. +배포가 맞지 않는 스키마에서 돌고 있다. 닫힌 채 실패했고, 그것이 맞다. -1. Read the reported error codes (the messages are deliberately not propagated). -2. `CHECKSUM_MISMATCH` — an applied migration was edited afterwards. Find which change is missing - from this database. **Do not run `repair`**: it rewrites history to match the scripts, which - resolves the symptom by deleting the evidence. -3. `MISSING_SCRIPT` — a migration applied here is not in this build. Usually a rollback to an older - artifact. +1. 보고된 오류 코드를 읽는다(메시지는 일부러 전달하지 않는다). +2. `CHECKSUM_MISMATCH` — 적용된 마이그레이션을 나중에 고쳤다. 이 DB에 어느 변경이 빠졌는지 찾는다. **`repair`를 돌리지 + 않는다.** repair는 이력을 스크립트에 맞춰 다시 써서, 증거를 지워 증상을 없앤다. +3. `MISSING_SCRIPT` — 여기 적용된 마이그레이션이 이 빌드에 없다. 보통 옛 산출물로 되돌린 것이다. -## An invalid index exists +## 무효 인덱스가 있다 (An invalid index exists) -**Signal:** this query returns rows. +**신호:** 이 쿼리가 행을 돌려준다. ```sql select n.nspname || '.' || i.relname as invalid_index @@ -69,28 +60,24 @@ join pg_namespace n on n.oid = i.relnamespace where not x.indisvalid; ``` -A concurrent build, rebuild or drop failed. The index is ignored by the planner and maintained by -every write. +동시 빌드, 재빌드, 삭제가 실패했다. planner는 그 인덱스를 무시하고, 모든 쓰기는 그것을 유지한다. -1. Confirm no build is currently running. An in-progress build looks identical in the catalog. -2. If a migration was building, rebuilding or dropping it, Flyway recorded that version as failed - (`success = false`) and refuses every later deploy until that row is gone: dropping the index - does not clear it. Follow [migration-failed.md](../runbooks/migration-failed.md) "Recover a - failed concurrent index migration" instead of the next step. It removes the cause, drops the - index a failed build or rebuild left, and deletes that one row. It leaves the index a failed - `DROP INDEX CONCURRENTLY` left, for the deploy again to drop: dropped by hand, that statement - finds no index and fails again. -3. Otherwise run `DROP INDEX CONCURRENTLY IF EXISTS ;` outside a migration, and - re-apply the index migration. +1. 지금 도는 빌드가 없는지 확인한다. 진행 중인 빌드도 카탈로그에서는 똑같이 보인다. +2. 마이그레이션이 그것을 빌드, 재빌드, 삭제하던 중이었으면, Flyway는 그 버전을 실패(`success = false`)로 기록했고 그 행이 + 사라질 때까지 뒤의 모든 배포를 거부한다. 인덱스를 지워도 풀리지 않는다. 다음 단계 대신 + [migration-failed.md](../runbooks/migration-failed.md) 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed + concurrent index migration)」를 따른다. 그 절차는 원인을 없애고, 실패한 빌드나 재빌드가 남긴 인덱스를 지우고, 그 한 행을 + 지운다. 실패한 `DROP INDEX CONCURRENTLY`가 남긴 인덱스는 다시 배포가 지우도록 남긴다. 손으로 지우면 그 문장이 인덱스를 + 찾지 못해 다시 실패한다. +3. 그렇지 않으면 마이그레이션 밖에서 `DROP INDEX CONCURRENTLY IF EXISTS ;`를 돌리고, 인덱스 마이그레이션을 + 다시 적용한다. -The platform does not drop these automatically: on a rolling deploy every instance would race to -drop an index another instance was about to finish building. +플랫폼은 이것을 자동으로 지우지 않는다. rolling deploy에서는 모든 인스턴스가, 다른 인스턴스가 곧 빌드를 끝낼 인덱스를 +지우려고 경주한다. -## The runtime role failed verification +## 런타임 역할이 검증에 실패했다 -Startup refused because the runtime credential holds `CREATE`, or `search_path` contains an -unapproved schema. +런타임 자격 증명이 `CREATE`를 가지거나 `search_path`에 승인하지 않은 schema가 있어서 기동이 거부됐다. -This is not a false positive to be worked around. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 -갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 -지킬 수 없다. +돌아갈 오탐이 아니다. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 +자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 지킬 수 없다. diff --git a/docs/jpa/security.md b/docs/jpa/security.md index dbf5fa92..818990eb 100644 --- a/docs/jpa/security.md +++ b/docs/jpa/security.md @@ -1,18 +1,18 @@ -# Security +# 보안 -Design §36. Credential separation, privilege verification, and what never leaves the process. +설계서 §36. 자격 증명 분리, 권한 검증, 프로세스 밖으로 절대 나가지 않는 것. -## Three credentials +## 자격 증명 셋 -| Role | May | +| 역할 | 할 수 있는 것 | |---|---| -| `app_migration` | own the schema, apply migrations (DDL) | -| `app_runtime` | select, insert, update, delete (DML only) | -| `app_admin` | J4 operations — COPY, backfill, maintenance | +| `app_migration` | schema 소유, 마이그레이션 적용(DDL) | +| `app_runtime` | select, insert, update, delete(DML만) | +| `app_admin` | J4 작업 — COPY, backfill, 정비 | -The separation is what makes "Flyway owns schema change" enforceable rather than aspirational. If -the application's own credential cannot execute DDL, then no code path, no library, and no injected -statement can alter the schema at runtime, regardless of what the application intended. +이 분리가 「schema 변경은 Flyway가 가진다」를 바람이 아니라 강제할 수 있는 규칙으로 만든다. 애플리케이션 자신의 자격 증명이 +DDL을 실행할 수 없으면, 애플리케이션이 무엇을 의도했든 어떤 코드 경로도, 라이브러리도, 주입된 문장도 실행 중에 schema를 바꿀 +수 없다. ### 역할과 권한 — 운영 DB가 갖춰야 할 것 @@ -50,9 +50,9 @@ statement can alter the schema at runtime, regardless of what the application in 확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다. -## Startup verification +## 기동 검증 -`PostgreSqlRuntimeRoleVerifier` asks the *server* what the connection can do: +`PostgreSqlRuntimeRoleVerifier`가 연결이 무엇을 할 수 있는지 *서버*에 묻는다. ```sql select current_user, @@ -61,38 +61,35 @@ select current_user, has_database_privilege(current_user, current_database(), 'CREATE') ``` -Configuration cannot answer this. Effective privileges come from direct grants, inherited role -memberships, `PUBLIC` grants, and schema ownership, and no reading of a deployment manifest -reconstructs that combination reliably. +설정으로는 이것에 답할 수 없다. 실제 권한은 직접 grant, 물려받은 역할 membership, `PUBLIC` grant, schema 소유에서 오고, 배포 +manifest를 읽어서는 그 조합을 믿을 만하게 되살릴 수 없다. -Startup fails when the runtime role is not on the allowlist, or holds `CREATE` on the schema or the -database. +런타임 역할이 허용 목록에 없거나, schema나 데이터베이스에 `CREATE`를 가지면 기동이 실패한다. ## search_path -`SearchPathPolicy` is an allowlist. `search_path` decides which schema an unqualified name resolves -to, so a writable untrusted schema on it — classically `public`, where `CREATE` was granted broadly -before PostgreSQL 15 — lets a planted table, function, or operator shadow the real one, and the -application executes it without noticing. `$user` is exempt: only the connected role owns it. +`SearchPathPolicy`는 허용 목록이다. `search_path`는 이름만 쓴 객체가 어느 schema로 풀리는지 정한다. 그래서 그 위에 쓸 수 있는 +믿지 못할 schema가 있으면(전형적으로 `public`. PostgreSQL 15 전에는 `CREATE`가 넓게 주어졌다) 심어 둔 테이블, 함수, 연산자가 +진짜 것을 가리고, 애플리케이션은 알아채지 못한 채 그것을 실행한다. `$user`는 예외다. 연결한 역할만 그것을 소유한다. -Refusing the runtime role `CREATE` closes the same route from the other side. +런타임 역할에게 `CREATE`를 주지 않는 것이 같은 길을 반대쪽에서 막는다. -## What never leaves the process +## 프로세스 밖으로 절대 나가지 않는 것 -- SQL parameter values, entity ids, tenant ids, and PII: not in exception messages, not in metric - tags, not in logs. `JpaFailureContext` composes messages from bounded values only. -- Constraint names reach the application as registered `ConstraintCode`s; an unregistered physical - name maps to a bounded unknown code rather than being passed through. -- Cursors are HMAC-signed. An unsigned cursor is client-controlled ordering state. -- The actuator report carries no JDBC URL, username, or SQL. +- SQL 파라미터 값, entity id, tenant id, PII. 예외 메시지에도, 메트릭 태그에도, 로그에도 없다. `JpaFailureContext`는 상한 있는 + 값으로만 메시지를 만든다. +- 제약 이름은 등록된 `ConstraintCode`로 애플리케이션에 닿는다. 등록되지 않은 물리 이름은 그대로 넘기지 않고 상한 있는 unknown + 코드로 매핑한다. +- cursor는 HMAC으로 서명한다. 서명 없는 cursor는 클라이언트가 다루는 정렬 상태다. +- actuator 보고에는 JDBC URL, 사용자 이름, SQL이 없다. -## Injection surfaces, and how each is closed +## 주입 표면과 각각을 막는 법 -| Surface | Why it cannot be a parameter | Closed by | +| 표면 | 파라미터가 될 수 없는 이유 | 막는 것 | |---|---|---| -| sort field | part of ORDER BY | `SafeSortRegistry` allowlist | -| JSON path | part of the statement | registered `JsonPathName` | -| schema name | an identifier | registered `SchemaTenantRegistry` | -| COPY table | an identifier | registered `RegisteredCopyStatement` | +| 정렬 칸 | ORDER BY의 일부 | `SafeSortRegistry` 허용 목록 | +| JSON 경로 | 문장의 일부 | 등록한 `JsonPathName` | +| schema 이름 | 식별자 | 등록한 `SchemaTenantRegistry` | +| COPY 테이블 | 식별자 | 등록한 `RegisteredCopyStatement` | -Values are always bound. Identifiers are always registered. +값은 늘 묶는다. 식별자는 늘 등록한다. diff --git a/docs/jpa/support-matrix.md b/docs/jpa/support-matrix.md index 258fa1fa..50a1965d 100644 --- a/docs/jpa/support-matrix.md +++ b/docs/jpa/support-matrix.md @@ -1,89 +1,79 @@ -# JPA Persistence Platform — Support Matrix +# JPA 영속성 플랫폼 — 지원 매트릭스 -**This document is a rendering. The machine-readable source is -[`src/adapter/outbound/persistence-jpa/release/release-registry.json`](../../src/adapter/outbound/persistence-jpa/release/release-registry.json).** +**이 문서는 렌더링이다. 기계가 읽는 정본은 +[`src/adapter/outbound/persistence-jpa/release/release-registry.json`](../../src/adapter/outbound/persistence-jpa/release/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. +registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 +registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다. -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. +- `JpaReleaseRenderingTest`가 DB 표, gate 표, `release.yml`의 JPA matrix와 승격 목록을 registry와 비교한다. +- `jpaReleaseQualification` 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 + 그래프를 만들 때 실패한다. +- `jpa-nightly.yml`의 matrix도 같은 비교를 받는다. Experimental major는 `.github/workflows`의 어떤 lane이 그것을 대상으로 + 기록해야 하고, Stable lane은 그것을 돌리면 안 된다. -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. +> 이력: 전에는 `JpaReleaseManifest`가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 `PostgreSQL NN`이 지원 +> 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 +> 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. +> 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. `jpa-nightly.yml`은 자기 +> matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental +> major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를 +> 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다. -## 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`](../../.github/workflows/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 | +| PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | +| PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | +| PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | +| PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 | +| H2 | Local convenience | PostgreSQL 동작의 증거가 **절대** 아니다 | -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. +major마다 **자기 릴리스 job**이 있다. `release.yml`의 `jpa-release-gate` job이 major마다 job 하나로 펼치고, 승격 job은 세 +major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래서 major 하나가 빠지면 그 증거가 아니라 릴리스가 빠진다. +`JpaPlatformContractSupport.start()`는 여러 버전 선택을 아예 거부한다. -**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. +> 이력: 한동안 그렇지 않았다. 릴리스 lane이 `-Pjpa.matrix.versions=16,17,18`을 `selectedVersions().get(0)`을 쓰는 +> `JpaPlatformContractSupport.start()`에 넘겼으므로, 통합 suite 전체가 PostgreSQL 16에만 돌았다. 이 표는 단언 셋짜리 +> smoke test를 근거로 17과 18을 전부 덮었다고 적었다. -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. +**provider 기준선.** gate는 Spring Boot BOM이 푸는 Hibernate 버전 **7.1.8.Final**에서 돈다. registry는 그것을 +`stable-tested-baseline`으로 기록한다. 7.4는 `compatibility-target`으로 기록하고, 전체 lane이 실제로 그 버전에서 돈 뒤에 +기준선이 된다. -`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. +> 이력: 이 문서는 전에 7.4를 Stable 기준선이라 불렀고 페이지네이션 gate 이름도 `hibernate-7.4-fetch-pagination`이었다. +> 그래서 그 gate를 돌릴 때마다 한 번도 돌려 보지 않은 provider 이름이 붙은 증거가 나왔다. -## Specification and provider +H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 +빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다. -| Component | Stable | Experimental | +`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.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 declared baseline | 8 (lane) | -| Spring Boot | repository BOM | — | +| Hibernate ORM | 7.4 선언 기준선 | 8 (lane) | +| Spring Boot | 저장소 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](repository-adaptation.md) §4. +Hibernate 줄에는 설명이 필요하다. 설계서는 7.4를 Stable provider로 선언하고, 이 저장소의 Spring Boot BOM은 7.1.x를 푼다. +`HibernateProviderPolicy`가 둘을 다 가진다. 선언 기준선은 상수로, 풀린 버전은 Hibernate 자신에게서 읽는다. +`driftsFromDeclaredBaseline()`이 상수를 상수와 비교하는 대신 그 차이를 드러낸다. +[repository-adaptation.md](repository-adaptation.md) §4를 본다. -## Capability support levels +## capability 지원 수준 -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"). +수준은 `jpaplatform` actuator 엔드포인트가 `JpaPlatformReport.platformCapabilities()`로 보고하는 값이다. 마지막 세 +줄(기술 감사, multi-tenancy, read replica)은 그 보고에 없고 이 문서가 정한다. Advanced와 Experimental 줄은 서비스가 직접 +부르는 라이브러리 코드다(`src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」). -| Capability | Level | +| capability | 수준 | |---|---| | Keyset pagination | Stable | | Flyway schema gate | Stable | @@ -95,44 +85,40 @@ itself (`src/adapter/outbound/persistence-jpa/README.md` "라이브러리 API"). | PostgreSQL array and range | Advanced | | Bulk DML | Advanced | | Hibernate `StatelessSession` | Advanced | -| PostgreSQL `COPY` | Admin (J4) | +| PostgreSQL `COPY` | Advanced (admin 자격 증명 필요) | | Hibernate second-level cache | Advanced | | Hibernate Envers | Advanced | -| Technical auditing — `audit/AuditableEntity` | Stable (canonical) | +| 기술 감사 — `audit/AuditableEntity` | Stable (canonical) | | Multi-tenancy (column, RLS, schema, database) | Experimental | -| Consistency-aware read replica | Experimental | +| 일관성을 아는 read replica | Experimental | -## Release gates +## 릴리스 gate -Each row is a way the platform could pass its tests and still be wrong in production. +줄마다, 플랫폼이 테스트를 통과하고도 운영에서 틀릴 수 있는 길 하나다. -| Gate | Kind | What it prevents | +| Gate | Kind | 막는 것 | |---|---|---| -| `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 | +| `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가 몰래 테이블 전체를 읽고 메모리에서 페이지를 나눔 | -### 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. +감사 방식은 `audit/AuditableEntity` 하나다. `created_*`/`updated_*`, 256자 actor이고, repository 어댑터가 명시적으로 +찍는다. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. 두 번째 방식인 Spring Data listener 기반 +(`auditing/AuditMetadata`)은 한 번도 조립되지 않아서 지웠다. `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`이 +그것이 엔티티에 돌아오지 못하게 막는다. -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. +이 방식은 bulk·native update에 닿지 않는다. 어댑터의 보통 save에서 찍으므로, DB로 바로 가는 문장은 감사 열을 앞 save의 +값으로 남긴다. 그래서 감사 대상 엔티티의 bulk update는 문장 안에서 감사 열을 설정해야 하고, +`JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit`가 운영 그래프에서 그것을 확인한다. -## 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. +- Reactive JPA. JPA는 blocking 명세다. 그 위의 reactive facade는 blocking 호출을 없애는 게 아니라 event loop로 옮긴다. +- 운영 스키마를 쓰는 Hibernate. `ddl-auto`는 배포된 스키마를 절대 바꾸지 않는다. +- 플랫폼이 가진 generic CRUD repository. 도메인이 자기 repository를 가진다(설계서 §10.1). +- 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다. diff --git a/docs/jpa/transaction-guide.md b/docs/jpa/transaction-guide.md index 491d7530..b4c45ef3 100644 --- a/docs/jpa/transaction-guide.md +++ b/docs/jpa/transaction-guide.md @@ -1,65 +1,56 @@ -# Transaction Guide +# 트랜잭션 가이드 -Design §15-§20. What owns a transaction, what may be retried, and what must never be. +설계서 §15-§20. 무엇이 트랜잭션을 가지고, 무엇을 다시 시도해도 되고, 무엇은 절대 안 되나. -## The application service owns the boundary +## 경계는 애플리케이션 서비스가 가진다 -Repository adapters do not open transactions. The use case does, through `TransactionPort`, -because the unit of work is a business decision and only the use case knows where it starts and -ends. `SpringTransaction` is the only implementation: one pre-built `TransactionTemplate` per -mode over Spring's `PlatformTransactionManager`, every mode running at `READ_COMMITTED` and -bounded in time. +repository 어댑터는 트랜잭션을 열지 않는다. use case가 `TransactionPort`로 연다. 작업 단위는 업무 결정이고, 그것이 어디서 +시작하고 끝나는지는 use case만 알기 때문이다. 구현은 `SpringTransaction` 하나다. Spring의 `PlatformTransactionManager` 위에 +mode마다 미리 만든 `TransactionTemplate` 하나를 두고, 모든 mode가 `READ_COMMITTED`로 돌며 시간 상한이 있다. -- **Isolation** is pinned on the pool, not per transaction: the module defaults set - `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED` and - `HikariPoolConstraintValidator` refuses any other level. A template that names the level makes - pgjdbc ask the server for it (`SHOW TRANSACTION ISOLATION LEVEL`) at every begin. -- **Time bound**: `app.persistence-jpa.transaction.write-timeout` (`inWrite`, `inRootWrite`) and - `read-timeout` (`inRead`), 30 s each by default; `inNew` is fixed at 30 s. Spring hands the - remaining time to each statement, so the server cancels a slow statement or lock wait - (`DB_QUERY_CANCELED`) and the connection returns to the pool. A unit of work that needs longer - is usually a batch job that should be split, not a reason to raise the bound. +- **격리 수준**은 트랜잭션마다가 아니라 풀에 고정한다. module defaults가 + `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 두고, `HikariPoolConstraintValidator`가 다른 + 수준을 거부한다. 수준을 이름 대는 template은 begin마다 pgjdbc가 서버에 그것을 묻게 한다(`SHOW TRANSACTION ISOLATION LEVEL`). +- **시간 상한**: `app.persistence-jpa.transaction.write-timeout`(`inWrite`, `inRootWrite`)과 `read-timeout`(`inRead`), 기본값은 + 각각 30 s다. `inNew`는 30 s로 고정이다. Spring이 남은 시간을 문장마다 넘기므로 서버가 느린 문장이나 잠금 대기를 취소하고 + (`DB_QUERY_CANCELED`) 연결은 풀로 돌아간다. 더 오래 걸려야 하는 작업 단위는 보통 상한을 올릴 이유가 아니라 나눠야 할 batch + 작업이다. -| Call | Propagation | When | +| 호출 | 전파 | 언제 | |---|---|---| -| `inWrite` | `REQUIRED`, read-write | command default | -| `inRootWrite` | `REQUIRED`, read-write, rejects an ambient transaction before running | orchestration that must prove a physical commit | -| `inRead` | `REQUIRED`, read-only | query default | -| `inNew` | `REQUIRES_NEW`, read-write | outbox / audit / compensation that must commit on its own | +| `inWrite` | `REQUIRED`, 읽기-쓰기 | command 기본 | +| `inRootWrite` | `REQUIRED`, 읽기-쓰기, 돌기 전에 바깥 트랜잭션을 거부 | 물리 커밋을 증명해야 하는 조율 | +| `inRead` | `REQUIRED`, 읽기 전용 | query 기본 | +| `inNew` | `REQUIRES_NEW`, 읽기-쓰기 | 혼자 커밋해야 하는 outbox / 감사 / 보상 | -Open Session In View is off in every runtime profile. It is on by default in Spring Boot, which is -why `JpaDangerousConfigurationGuard` fails startup rather than trusting configuration review. +Open Session In View는 모든 런타임 profile에서 꺼져 있다. Spring Boot에서는 기본으로 켜져 있어서, 설정 리뷰를 믿지 않고 +`JpaDangerousConfigurationGuard`가 기동을 실패시킨다. -`REQUIRES_NEW` acquires a second physical connection while pinning the first, so the pool must -satisfy: +`REQUIRES_NEW`는 첫 물리 연결을 쥔 채 두 번째를 잡으므로 풀은 다음을 채워야 한다. ```text maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1 ``` -## Nothing is retried by the port +## port는 아무것도 다시 시도하지 않는다 -`SpringTransaction` runs the action once. A failure rolls back and propagates, translated to -the shared persistence error codes where the SQLSTATE is known; a lost `@Version` race has no -SQLSTATE and is reported as `DB_OPTIMISTIC_CONFLICT` (409). A caller that decides to retry must -re-run the whole use case in a new transaction — never re-issue one statement — because an -optimistic conflict or a serialization failure means the state the attempt computed against is no -longer the committed state. +`SpringTransaction`은 action을 한 번 돌린다. 실패하면 롤백하고 넘기며, SQLSTATE를 알면 공유 영속성 오류 코드로 바꾼다. +잃은 `@Version` 경주는 SQLSTATE가 없고 `DB_OPTIMISTIC_CONFLICT`(409)로 보고한다. 다시 시도하기로 한 호출자는 문장 하나를 다시 +보내지 말고 use case 전체를 새 트랜잭션에서 다시 돌린다. 낙관적 충돌이나 직렬화 실패는 시도가 기준으로 계산한 상태가 더는 +커밋된 상태가 아니라는 뜻이기 때문이다. -A second engine with named policies, deadline budgets, transaction-local timeouts and automatic -full-transaction retry (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, -`PolicyTransactionPort`) existed next to this one and was removed on 2026-09-25. Its last commit is -recorded in `docs/capability-status.md`. +> 이력: 이름 있는 정책, 마감 예산, 트랜잭션 로컬 시간 상한, 자동 전체 트랜잭션 재시도를 가진 두 번째 엔진 +> (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, `PolicyTransactionPort`)이 이것 옆에 있다가 +> 2026-09-25에 지워졌다. 마지막 커밋은 `docs/capability-status.md`에 있다. -## Completion unknown +## 완료를 모름 -A connection can break while a commit is in flight; the server may have committed and only the -acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type -system enforces it: `JpaFailureContext` refuses to represent a retryable completion-unknown failure. -The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once +커밋이 진행 중일 때 연결이 끊길 수 있다. 서버는 커밋했고 확인 응답만 잃었을 수 있다. `TransactionCompletionUnknownException`은 +절대 다시 시도하지 않고, 타입 체계가 그것을 강제한다. `JpaFailureContext`는 다시 시도할 수 있는 완료 모름 실패를 표현하기를 +거부한다. port 자신은 아무것도 다시 시도하지 않으므로, 그런 커밋은 호출자에게 실패로 정확히 한 번 나타난다 (`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`). -Recovery is reconciliation, not retry: +복구는 재시도가 아니라 맞추기다. ```text check the idempotency record -> check the business row -> check the outbox diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 72572a68..802ea42b 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -54,18 +54,6 @@ language docs/httpclient/retry-and-ambiguity.md language docs/httpclient/security.md language docs/httpclient/streaming.md language docs/httpclient/support-matrix.md -language docs/jpa/batch-write-guide.md -language docs/jpa/entity-mapping-guide.md -language docs/jpa/experimental-promotion-checklist.md -language docs/jpa/experimental-support-matrix.md -language docs/jpa/migration-guide.md -language docs/jpa/observability.md -language docs/jpa/postgresql-extensions.md -language docs/jpa/query-fetch-guide.md -language docs/jpa/repository-adaptation.md -language docs/jpa/runbooks.md -language docs/jpa/support-matrix.md -language docs/jpa/transaction-guide.md language docs/mongodb/advanced/encryption.md language docs/mongodb/advanced/multi-tenancy.md language docs/mongodb/advanced/sharding.md @@ -144,8 +132,6 @@ reference src/README.md .github/scripts/verify-gate-matrix.sh number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 number docs/httpclient/repository-adaptation.md 19 leaf number docs/httpclient/repository-adaptation.md Spring Boot 4.0.8 -number docs/jpa/repository-adaptation.md 19 leaf -number docs/jpa/repository-adaptation.md Spring Boot 4.0.8 number docs/manual/01-generator.md 5 leaf number docs/mongodb/repository-adaptation.md 19 leaf number docs/mongodb/repository-adaptation.md Spring Boot 4.0.8 diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java index b7724e94..ef94f18c 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java @@ -46,7 +46,7 @@ class PoolLaneClaimTest { private static final String REMOVED_FLAG = "performance." + "assertions." + "enabled"; @Test - @DisplayName("no file describing the pool lane mentions the flag that was removed") + @DisplayName("풀 lane을 설명하는 파일은 지운 스위치를 말하지 않는다") void noFileMentionsTheRemovedFlag() { for (String description : LANE_DESCRIPTIONS) { assertThat(read(description)) @@ -56,7 +56,7 @@ class PoolLaneClaimTest { } @Test - @DisplayName("no file describing the pool lane claims a certification or a machine bound") + @DisplayName("풀 lane을 설명하는 파일은 인증이나 기계 상한을 주장하지 않는다") void noFileClaimsACertificationOrAMachineBound() { for (String description : LANE_DESCRIPTIONS) { String text = read(description).toLowerCase(Locale.ROOT); @@ -68,12 +68,15 @@ class PoolLaneClaimTest { .as("%s describes the pool lane as certifying something it does not measure", description) .doesNotContain("pool pressure certification") .doesNotContain("machine-dependent bounds") - .doesNotContain("machine bounds"); + .doesNotContain("machine bounds") + .doesNotContain("풀 압력 인증") + .doesNotContain("기계 상한") + .doesNotContain("기계에 따라 다른 상한"); } } @Test - @DisplayName("the nightly job runs the behaviour lane, under its behaviour name") + @DisplayName("nightly job은 동작 lane을 그 동작 이름으로 돌린다") void theNightlyJobRunsTheBehaviourLane() { String nightly = read(".github/workflows/jpa-nightly.yml"); diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaDocumentationContractTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaDocumentationContractTest.java index 95c1dada..56ed7158 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaDocumentationContractTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaDocumentationContractTest.java @@ -28,7 +28,7 @@ class JpaDocumentationContractTest { private final JpaReleaseManifest manifest = JpaReleaseManifest.loadFromRepository(); @Test - @DisplayName("the support matrix names the registry's provider baseline, not the target") + @DisplayName("지원 매트릭스는 목표가 아니라 registry의 provider 기준선을 이름 댄다") void theSupportMatrixNamesTheRegistrysProviderBaseline() { String matrix = read("docs/jpa/support-matrix.md"); @@ -42,7 +42,7 @@ class JpaDocumentationContractTest { } @Test - @DisplayName("every gate the registry declares is named in the support matrix") + @DisplayName("registry가 선언한 gate는 모두 지원 매트릭스에 이름이 있다") void everyRegistryGateIsNamedInTheSupportMatrix() { String matrix = read("docs/jpa/support-matrix.md"); @@ -52,7 +52,7 @@ class JpaDocumentationContractTest { } @Test - @DisplayName("the H2 passage separates measurement from guarantee") + @DisplayName("H2 단락은 측정과 보장을 가른다") void theH2PassageSeparatesMeasurementFromGuarantee() { String matrix = read("docs/jpa/support-matrix.md"); @@ -62,18 +62,18 @@ class JpaDocumentationContractTest { assertThat(flowed) .as("two documents disagreed about SKIP LOCKED because they answered different questions") - .contains("not a production guarantee") - .contains("PostgreSQL contract evidence"); + .contains("운영 보장이 아니") + .contains("PostgreSQL 계약 증거"); } @Test - @DisplayName("the boundary document states the gap it does not enforce") + @DisplayName("경계 문서는 강제하지 않는 빈틈을 밝힌다") void theBoundaryDocumentStatesItsGap() { String adaptation = read("docs/jpa/repository-adaptation.md"); assertThat(adaptation) .as("a document may call a boundary enforced only where a test actually enforces it") - .contains("Known gap"); + .contains("알려진 빈틈"); } private static String read(String repositoryRelativePath) {