문제 (재리뷰 round7 영속성 RR7-03-01~05) - 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가 "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의 이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에 다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다. docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서 멈춘다. - 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다. 가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다 커밋해 앞 문장이 남는다. - 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX … CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다. - LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면 SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은 "늘 거부"라고 쓴다. - ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고 안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개 (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도 모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be executed within a pipeline"으로 실패한다. 고른 방법 - 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에 "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드 확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의 실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고 flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고 postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어 실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기 Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다. - 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와 잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태). - 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와 상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은 PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이 맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라 그대로 둔다. - ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을 두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스 문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어 sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다 (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을 파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로 바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다. 위험·한계 - 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다. 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이 없다(업그레이드 안내 4.1에 적음). - runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라 성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이 지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다. - ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음). - Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라 UP-TO-DATE로 처리됐다. 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 기준73d39212+ 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시 메서드, + 임시 ledger V004): - persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중 2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log) - postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장 대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied, conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데 검사기는 통과 (red2-lockwait.log) - postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 — 옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version 2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김, runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음) (red2-concurrent.log) - ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기 IT "name it as an exception here", 다른 IT 둘 "cannot be executed within a pipeline" (red-ledger.log) GREEN — 이 커밋의 트리b49369e7: - :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0), :testQualityCheck rc=0 - postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0) - postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0) - -p optional-platforms :grpc:grpc-operation-ledger-jpa:check integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0) - :app-bootstrap:documentContractTest rc=0 (66건 실패 0) - 두 빌드의 verifyStrictLaneStages --dry-run rc=0 - ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고 메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면 rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent index statement"로 거부 - python3 scripts/check-work-docs.py --links docs: 깨진 링크 0 Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
adapter-persistence-rdbms — 설계 결정 참조
RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: dev.caskeleton.adapter.persistence.
허용/금지 의존, 테스트 명령, 그리고 계약 테이블(TransactionPort 모드표, SQLState → Error Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 CLAUDE.md 다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만 적는다.
capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env
템플릿 기본 조립에는 이 모듈이 없다. 관계형 저장소가 필요한 서비스는 app-bootstrap/build.gradle에
한 줄을 넣는다.
runtimeOnly project(':adapter:outbound:persistence-jpa')
그 줄을 지우면 아래 전부가 함께 사라진다. 다른 파일은 고치지 않는다.
제공하는 것 (모듈이 있으면 켜진다. APP_PERSISTENCE_JPA_ENABLED=false면 완전히 꺼진다: 이 모듈의
bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도 spring.autoconfigure.exclude에
추가되므로 DataSource·풀·EntityManagerFactory·Flyway가 만들어지지 않고 DB 없이 기동한다. 그래서 DB가
필요한 다른 capability(notification·fileserver 저장소, messaging JDBC outbox/inbox 등)와 함께 끌 수는 없다)
- 포트 구현:
TransactionPort(SpringTransaction),DistributedLockPort(단일 인스턴스는 in-process,APP_MULTI_INSTANCE_ENABLED=true면 JDBCINT_LOCK+MeteredDistributedLock데코레이터 =distributedLockProvider), outbox store(OutboxStorePort,APP_OUTBOX_ENABLED=true), PostgreSQL 멱등성 store(APP_IDEMPOTENCY_PROVIDER=postgresql), audit·operation·live-event store. - 엔티티/리포지토리 스캔, vendor 조립(PostgreSQL 기본, H2는 개발용), Flyway 위치.
- 기동 정책(
startup패키지,JpaStartupAutoConfiguration): Flyway 마이그레이션 전략 (migrationStartupRunner, 실패 시 exit 70), datasource env 확인(exit 78), 실제 DB 제품·버전 확인, OSIV·DDL·Hikari·TLS·H2 금지 가드(prod exit 71),/actuator/jpaplatform(actuator가 있을 때만). - 스위치의 환경 처리(
JpaActivationEnvironmentPostProcessor, 모듈의spring.factories): 켜져 있으면 readiness 그룹에db추가, 꺼져 있으면 Boot의jdbc·hibernate·data.jpa·flyway자동 설정 패키지를spring.autoconfigure.exclude에 추가(기존 값은 유지). - 기본 설정
config/module-defaults/persistence-jpa.yml(spring.datasource/flyway/jpa,app.persistence*,app.lock.*,app.outbox.*,app.realtime.replay.*,app.runtime.migration-on-startup). support 모듈의ModuleDefaultsEnvironmentPostProcessor가 가장 낮은 우선순위로 읽으므로 애플리케이션 설정과 환경변수가 언제나 이긴다.
outbox relay(스케줄러)는 이 모듈이 아니라 합성 루트의 OutboxConfig가 조립한다. use case를
만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는
OutboxStorePort와 messaging이 주는 OutboxMessagePublishPort가 모두 있을 때만 켜진다.
durable operation HTTP 엔드포인트(POST /operations·GET·DELETE /operations/{id})도 같은
이유로 composition:durable-operation의 DurableOperationAutoConfiguration이 조립한다. 이 모듈이 주는 operation store와 outbox
append 포트(APP_OUTBOX_ENABLED=true)가 모두 있을 때만 켜진다. submit·cancel에는
operation-submit 역할(operation:submit, operation:cancel)이 필요하다.
애플리케이션이 제공해야 하는 bean: Clock, DomainContextPropagator(app-bootstrap과
sample-portfolio가 제공).
필요한 env 키 (src/.env.example, 레지스트리 docs/registries/env-keys.yaml)
| 용도 | 키 |
|---|---|
| 연결(필수) | APP_DATASOURCE_URL, APP_DATASOURCE_USERNAME, APP_DATASOURCE_PASSWORD(prod 필수 secret), APP_DATASOURCE_DRIVER |
| 스위치·vendor | APP_PERSISTENCE_JPA_ENABLED(기본 true), APP_PERSISTENCE_VENDOR(postgresql|h2), APP_FLYWAY_ENABLED, APP_MIGRATION_ON_STARTUP |
| 풀 | APP_DATASOURCE_POOL_MAX_SIZE, APP_DATASOURCE_POOL_MIN_IDLE, APP_DATASOURCE_CONNECTION_TIMEOUT, APP_DATASOURCE_POOL_IDLE_TIMEOUT, APP_DATASOURCE_POOL_MAX_LIFETIME |
| JPA | APP_DATASOURCE_DDL_AUTO, APP_DATASOURCE_SHOW_SQL, APP_DATASOURCE_FORMAT_SQL, APP_DATASOURCE_OPEN_IN_VIEW, APP_JPA_HIBERNATE_* |
| 선택 기능 | APP_OUTBOX_ENABLED, APP_OUTBOX_RELAY_ENABLED, APP_MULTI_INSTANCE_ENABLED(합성 루트 소유, 락 provider 선택), APP_IDEMPOTENCY_PROVIDER=postgresql, APP_REALTIME_REPLAY_ENABLED, APP_REALTIME_REPLAY_RETENTION |
라이브러리 API — 서비스의 어댑터 leaf에서 implementation으로 받아 직접 호출
아래 타입은 어떤 설정도 bean으로 만들지 않는다. 쓰려면 서비스의 어댑터 leaf가
implementation project(':adapter:outbound:persistence-jpa')를 선언하고(registry
allowed_dependencies에 그 edge가 있어야 한다) 자기 코드에서 생성·호출한다. runtimeOnly로는
컴파일되지 않는다(AGENTS.md capability 규칙의 라이브러리형 예외). Querydsl·Envers는 이 leaf에서
compileOnly이므로 쓰는 서비스가 com.querydsl:querydsl-jpa:5.1.0:jakarta·org.hibernate.orm:hibernate-envers를
직접 추가한다. "PG"는 postgresqlIntegrationTest(실제 PostgreSQL) 테스트다.
| 패키지 | 진입점 | 동작을 증명하는 테스트 |
|---|---|---|
springdata |
JpaRepositoryFragmentSupport(커스텀 fragment 베이스) + RegisteredQuery |
JpaRepositoryFragmentSupportTest |
springdata |
SafeSortRegistry·SafeSortMapper(클라이언트 정렬 → 등록 컬럼) |
SafeSortMapperTest, KeysetOrderingContractTest |
springdata, api.query |
JpaKeysetQuerySupport·KeysetPredicateBuilder + KeysetPageRequest·KeysetSlice |
JpaKeysetQuerySupportTest, KeysetSliceAssemblerTest, KeysetOrderingContractTest |
springdata |
FetchPlanApplier + EntityGraphCatalog |
FetchPlanApplierTest |
springdata |
JpaStreamExecutor + ScrollPolicy |
JpaStreamExecutorTest, ScrollPolicyTest |
api.query |
SignedJsonCursorCodec(서비스가 CursorPayloadCodec 구현), QueryName |
SignedJsonCursorCodecTest, QueryNameTest |
hibernate.batch |
HibernateJpaBatchExecutor + JpaBatchProfile·HibernateStatisticsCollector·JdbcBatchCounter |
HibernateJpaBatchExecutorTest, HibernateBatchConfigurationGuardTest, HibernateStatisticsCollectorTest, PG HibernateJpaBatchExecutorIntegrationTest |
hibernate.bulk |
HibernateBulkDmlExecutor |
PG HibernateBulkDmlExecutorIntegrationTest |
hibernate.stateless |
HibernateStatelessSessionRunner |
PG HibernateStatelessSessionRunnerIntegrationTest |
hibernate |
NamedStatementInspector(spring.jpa.properties.hibernate.session_factory.statement_inspector로 켬) |
NamedStatementInspectorTest |
postgresql.error |
PostgreSqlExceptionTranslator.with(PostgreSqlConstraintCatalog) → api.error 예외 계층 |
PostgreSqlFailureClassifierTest, PostgreSqlConstraintCatalogTest, PG PostgreSqlSqlStateContractTest·ConstraintRaceContractTest |
postgresql.lock |
PostgreSqlLockExceptionTranslator.standard(), PostgreSqlLockOptions |
PostgreSqlLockOptionsTest, PG PostgreSqlPessimisticLockContractTest |
postgresql.json |
PostgreSqlJsonQuerySupport + JsonDocumentCodec·JsonDocument |
PG PostgreSqlJsonbContractTest |
postgresql.array, .range |
PostgreSqlArraySupport, PgRange·PgRangeCodec |
PgRangeTest, PG PostgreSqlArrayRangeContractTest |
postgresql.copy |
RegisteredPostgreSqlCopyLoader(admin DataSource + CopyAdminCapability) |
PG PostgreSqlCopyLoaderIntegrationTest |
envers |
HibernateEnversHistoryReader, EnversConfigurationGuard |
PG EnversHistoryContractTest |
querydsl |
PredicatePolicy, QueryPage(서비스가 만든 JPAQuery 앞에서 검사) |
PredicatePolicyTest |
cache |
HibernateCacheGuard, HibernateCachePolicy, CacheRegionCatalog |
HibernateCacheGuardTest |
observation |
MicrometerQueryObservation(위 executor에 QueryObservation으로 전달), SqlDiagnosticRedactor |
JpaObservabilityContractTest, JpaMetricTagsTest |
experimental |
tenant·RLS·schema·database·replica 진입점 — 목록은 docs/jpa/experimental-support-matrix.md |
ExperimentalFailClosedTest, PG platform/experimental/* |
metric은 기본으로 하나도 나오지 않는다. jpa.query.*는 서비스가 MicrometerQueryObservation을
넘길 때만 기록된다(docs/jpa/observability.md). 2026-09-25에 지운 항목(단일 구현 인터페이스,
아무도 읽지 않는 app.jpa-platform.addons-enabled·backend.jpa.experimental.*, main의
promotion gate, 생성하는 곳 없는 JpaTransactionObservation 등)은 docs/capability-status.md
"제거된 코드"에 있다.
transaction — SpringTransaction
왜 모드별 템플릿을 미리 만들어 두나
TransactionTemplate 은 문서상 thread-safe 지만 mutable 하다. 매 호출마다 propagation /
readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로
(WRITE / READ_ONLY / REQUIRES_NEW) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가
사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 READ_COMMITTED
로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract).
왜 inRootWrite가 별도 템플릿이나 NEVER propagation을 만들지 않나
inRootWrite의 실행 속성은 inWrite와 같은 WRITE + REQUIRED + READ_COMMITTED라 기존
write template을 재사용한다. 차이는 실행 전 precondition이다.
TransactionSynchronizationManager.isActualTransactionActive()가 true이면 action과
PlatformTransactionManager를 호출하기 전에
NestedRootTransactionRejectedException으로 fail-fast한다. REQUIRES_NEW로 suspend해서
"root처럼 보이게" 하지 않으므로 호출자 transaction과 독립 commit되는 silent 의미 변경이 없다.
TransactionTemplate.execute는 commit까지 성공한 다음 값을 반환한다. 따라서
inRootWrite의 결과는 post-commit에만 호출자에게 보이고, commit 실패는 값 대신 원래 transaction
예외로 전파된다. 이 보장은 action이 외부 객체를 직접 변경하는 것을 되돌리는 보상이 아니라,
경계의 반환값을 성공으로 노출하지 않는 계약이다.
audit — AuditableEntity / AuditContextPort / DomainContextAuditContext
캡처 메커니즘 — Manual explicit-set (D1 현재 스켈레톤 기본값)
AuditableEntity 의 네 필드(created_at / updated_at / created_by / updated_by)는 평범한
@Column 이다 — Spring Data 의 @CreatedDate/@LastModifiedDate/@CreatedBy/@LastModifiedBy
도, @EntityListeners(AuditingEntityListener.class) 도 붙이지 않는다. 퍼시스턴스 어댑터가
initializeAudit(INSERT) 와 carryCreation + applyModification(UPDATE)로 명시적으로 값을
세팅한다. 공유 Clock 빈(D4)과 AuditContextPort actor(D5)를 재사용한다.
- INSERT 는
created_*와updated_*를 같은now/actor로 찍는다. NOT NULL 인updated_*를 신규 row 에서 채우기 위함이며, JPA-auditing 의modifyOnCreate기본동작에 의존하지 않는다. - UPDATE 는 두 단계다:
carryCreation으로 (Vernon Option A 재구성된) 엔티티가 잃어버린created_*를 다시 채워 넣고,applyModification으로updated_*만 옮긴다. created_*는updatable = false라 INSERT 이후 모든 UPDATE 문에서 제외된다 — 생성 actor/시각이 덮어써질 수 없다.version/optimistic-lock 은 여기 두지 않는다. 이 베이스는 audit 전용으로 남기고, 낙관적 잠금 정책은 개별 영속성 모델이 소유한다.
Growth path (D1, deferred — 구현 복제본 없음)
audited 애그리거트 수가 늘어 수동 세팅이 누락 위험을 키우면 Spring Data JPA Auditing 으로 이전할
수 있다. 다만 현재 leaf에는 두 번째 audit 모델을 미리 보관하지 않는다. 전환할 때
AuditableEntity의 같은 created_*/updated_* 스키마와 256자 actor 계약을 유지한 채
@EntityListeners(AuditingEntityListener.class)와 composition-owned AuditorAware /
DateTimeProvider를 원자적으로 도입한다. bulk/native @Query UPDATE는 어느 방식에서도 listener를
우회하므로 audit column을 statement에서 명시적으로 갱신해야 한다.
actor seam 을 왜 별도 포트로 격리하나
AuditContextPort 는 퍼시스턴스가 "누가 행위하는가"에 대해 의존하는 단 하나의 seam 이다.
actor 의 값 의미론(user id vs email vs subject claim)은 application/web 쪽의 사용자 모델
책임이고 여기서는 의도적으로 다루지 않는다. 그래서 타입을 String 으로 못박고, 이
포트가 보장하는 건 오직 "non-null actor"(프레임워크의 blank-on-absent 가 아니라) 하나 —
principal 이 없으면 "system".
DomainContextAuditContext 는 actor id 를 runtime-context-propagation seam
(DomainContextPropagator)에서 읽는다. 그 브랜치가 canonical actor key 를 소유하지만 API 가
확정되기 전까지 이 어댑터가 ACTOR_KEY 뒤로 격리해, 키가 바뀌어도 정확히 한 클래스만 손대게
한다(D5 Open Risk). 빈/blank context 값은 null/blank actor 가 아니라 "system" 으로 떨어뜨려
scheduler / Flyway / anonymous 경로에서도 NOT NULL created_by/updated_by 를 항상 만족시킨다.
config — PersistenceJpaConfig
왜 명시적 @EntityScan / @EnableJpaRepositories 가 필요한가
Spring Boot 메인 클래스는 dev.caskeleton.bootstrap 에 있어서, @AutoConfigurationPackage 가
앵커로 삼는 기본 엔티티/리포지토리 스캔이 dev.caskeleton.adapter.persistence.* 를 놓친다.
@SpringBootApplication 의 scanBasePackages 는 컴포넌트 스캔만 넓힐 뿐 JPA 엔티티/리포지토리
스캔은 넓히지 않는다. 이 설정이 없으면 production 리포지토리(예: IdempotencyRecordJpaRepository)
가 생성되지 않아 소비자(예: IdempotencyReaper)가 부팅에서 와이어링 실패한다. 스캔을 엔티티를
소유한 모듈에 둬서 와이어링을 그 자리에 유지한다.
왜 이름이 JpaConfig 가 아닌가
sample 모듈에 이미 ...sample.portfolio.adapter.persistence.config.JpaConfig 가 있다. IDE 의
"Run main class" 가 테스트 스코프 sample 모듈을 클래스패스에 올리면, simple name JpaConfig 를
공유하는 두 @Configuration 이 기본 빈 이름 jpaConfig 에서 충돌한다
(ConflictingBeanDefinitionException). 다른 simple name 으로 이를 피한다.
failure — 퍼시스턴스 실패 변환 SPI
매트릭스(SQLState → DB_* 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence
failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다.
SPI-pluggable 설계 (vendor 추출)
PersistenceExceptionTranslator 는 exact-state → code 맵을 등록된 모든 SqlStateErrorMapping
빈을 생성 시점에 merge 해서 만든다. core 모듈(StandardSqlStateErrorMapping)은 모든 RDBMS 가
공통으로 반환하는 portable/vendor-neutral 5개 row(40001, 23502, 23503, 23505, 23514)만
기여한다. vendor 별 row(40P01, 25P03, 57014 등 PostgreSQL)는 adapter-persistence-postgresql
가 추가 SqlStateErrorMapping 빈으로 기여한다.
- 서로 다른 contributor가 같은 exact SQLState를 등록하면 code가 같더라도 startup construction을 실패시킨다. last-writer-wins merge는 mapping ownership drift를 숨기므로 허용하지 않는다.
08*connection-class prefix →DB_UNAVAILABLE규칙은 맵 엔트리가 아니라 translator 가 직접 처리한다. 따라서 core 매핑 맵에는08*가 없다.- 커밋 단계는 따로 분류한다(ADR-JPA-003).
SpringTransaction은 본문이 끝난 뒤 자기가 연 쓰기 트랜잭션을 커밋하다 난 실패를translateCommitFailure로 보낸다. 여기서08*·40003·벤더 종료 상태(commitOutcomeUnknownStates(), PostgreSQL 은57P01·57P02)·SQLState 없는 전송 단절은DB_UNAVAILABLE(재시도 가능)이 아니라DB_COMPLETION_UNKNOWN(재시도 불가)이 된다. 서버가 이미 커밋했을 수 있어 재시도가 쓰기를 중복시키기 때문이다.- 커밋 전(연결 획득, 본문 실행) 연결 실패는 그대로
DB_UNAVAILABLE이다. 풀 고갈·재시작까지 결과 불명으로 몰면 운영자가 그 신호를 무시하게 된다(ADR 의 "좁게" 원칙). - 커밋 단계 안에서 Hibernate flush 실패와 COMMIT 자체 실패는 구분하지 않는다. flush 중 연결 단절은 실제로는 롤백이지만 결과 불명으로 보고된다 — 중복 쓰기보다 불필요한 조정(reconciliation)이 싸다.
- 읽기 전용 트랜잭션과 바깥 트랜잭션에 참여한 호출은 커밋할 쓰기가 없으므로 이 분류를 타지 않는다.
- 커밋 전(연결 획득, 본문 실행) 연결 실패는 그대로
- Fallback: 기여된 어떤 row 에도 없는 SQLState — 또는 cause chain 에
SQLException자체가 없는 경우 — 는Optional.empty()를 반환한다. 호출부는 원본 예외를 web catch-all 까지 전파시켜 detail 누설 없는 genericINTERNAL엔벨로프로 답하게 한다. translator 는 unknown state 에 대해DB_*코드를 절대 지어내지 않는다. - 변환된 carrier 의 진단 메시지에 SQLState 를 넣는 건 server-log 전용이다(web 어댑터가 절대 surface 하지 않음) — triage 를 돕되 클라이언트로 새지 않는다.
idempotency — PostgreSQL provider
app.capabilities.idempotency.provider=postgresql 일 때만 켜진다
(autoconfigure/PostgreSqlIdempotencyStoreConfig). 이 leaf 는 IdempotencyStorePort 구현
(PostgreSqlIdempotencyStore) 하나만 내놓고, executor 는 app-bootstrap
IdempotencyProviderSelectionConfig 가 만든다. V1 JDBC store 와 jdbc provider 값은 없다.
- 스키마: 기본 테이블은 primary Flyway(
db/migration/postgresql/V1__idempotency_record.sql)가, owner-safe 컬럼은db/migration/jpa/idempotencystream 이 소유한다. 기동 시IdempotencySchemaStream이db/migration/jpa/core→db/migration/jpa/idempotency순서로 적용하고 capability registry 행을ACTIVE로 올린다. 알림 capability 의NotificationSchemaStream과 같은 방식이다.app.runtime.migration-on-startup=false면 건너뛰고, 운영자가 적용·활성화할 때까지 store 가 fail closed 한다. - PostgreSQL 전용: data source 가 PostgreSQL 이 아니면 기동을 거부한다.
bootRunH2는 provider 를disabled나redis로 둔다. - 응답 크기: 완료 응답은 8 KiB 이하만 행에 inline 저장하고, 넘으면 거부한다.
- 만료: claim 은
expires_at을 처리 lease 끝 + replay TTL 로 두고, renew 는 lease 를 늘린 만큼expires_at도 뒤로 민다. 완료·실패 때 다시 앞으로 옮긴다.IdempotencyReaper(IdempotencyRecordJpaRepository사용, 기본 10분 간격reaper-interval)가 상태와 상관없이 지난 행을 지운다. 그래서expires_at이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을 다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를 실제로 돌려 이 경우를 본다. reaper 는 provider 가postgresql일 때만 돈다. - lease 가 지난 실행: lease 가 지난
EXECUTING행은 넘겨받지 않고RecoveryRequired로 답하며, 행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를 재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않고, lease 가 지난CLAIMED는 주인도 시작할 수 없다 — 둘 다LEASE_EXPIRED(전에는NOT_OWNER, 재리뷰 RR5-01-02). inspect 는 남의 lease 지난 실행을ABANDONED로 보고한다. Redis store 도 같다(IdempotencyStoreContract, RR-01-11, 2026-11-04 소유자 결정 — 전에는 행을ABANDONED·EXPIRED_EXECUTION으로 바꿔 늦은 결과를 버렸다). - 한 트랜잭션 안의 모양: executor 를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양)
claim 행은 그 트랜잭션이 끝날 때까지 커밋되지 않는다. 그래서 위의 "lease 가 지난 실행"을 다른 요청이
보는 일이 없다: 같은 키 요청은
on conflict에서 기다렸다가 커밋이면 재생, 롤백이면 새 실행을 받는다. 롤백(작업 예외, 쓰기 트랜잭션 제한 30s)은 executor 가 남긴 실패 기록도 지운다. 이 store 가 막는 중복은 같은 트랜잭션 안의 DB 효과이고, 트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다 (PostgreSqlIdempotencyIntegrationTest, 재리뷰 RR5-01-05,docs/web/http-contract.md§2).
outbox — JpaOutboxStore 외
스키마는 Flyway(V3__outbox_event.sql)가 소유하고, V13__outbox_canonical_transport_compatibility.sql이
canonical metadata와 exact BYTEA envelope_bytes를 더했다. append 모델은 canonical 하나다(2026-09-28,
소유자 결정 7): JpaOutboxStore가 OutboxAppendPort(ValidatedIntegrationEvent)와
OutboxStorePort를 함께 구현하고, app.outbox.enabled=true일 때만 존재한다. row는 validated
event의 exact envelope bytes와 hash를 저장하고, claim은 그 bytes로 같은 event를 복원한다
(ClaimedOutboxEvent). event_type·aggregate_id·correlation_id는 claim gate와 metrics query를
위해 contract id·aggregate id·correlation id를 한 번 더 적는다.
V19__outbox_event_canonical_only.sql은 pre-canonical row가 더 없다는 것을 DB에 적는다: envelope 없는
미발행 row가 남아 있으면 migration이 실패하고(이전 릴리스로 relay를 비우거나 손으로 정리한 뒤
다시 적용한다), 이후로는 PUBLISHED가 아닌 row에 canonical metadata가 반드시 있다
(ck_outbox_event_canonical_unless_published). pre-canonical payload·idempotency_key 컬럼은
nullable로 남고 아무것도 쓰거나 읽지 않는다 — 이전 릴리스로 되돌릴 때를 위해 지우지 않았다.
트랜잭션 경계 계약
- append: 호출자의
TransactionPort.inWrite()경계 안에서 호출되어야 하며, 내부에서 새 트랜잭션을 열지 않는다.@Repository가 빈만 등록하고 TX 는 use case 가 소유한다. - Application write 경계에는 adapter-local
@Transactional을 추가하지 않는다: 여러 port를 하나의 원자 작업으로 묶는 경계는 use case의TransactionPort가 소유한다. 예외는 adapter 자체가 하나의 저장소 프로토콜을 구현하는 내부 원자 단위다. 예를 들어 durable operation의 claim은UPDATE ... RETURNING후 같은 claim을 읽어야 하고, live-event append는 position allocator와 event insert가 함께 commit돼야 한다. 이런 메서드의 로컬 transaction은 application transaction을 대체하는 것이 아니라 port 자체의 atomic semantics다.
claim 계약 — vendor SPI (OutboxClaimRepository)
row claim 은 vendor 별 락 전략이 필요해 OutboxClaimRepository SPI 로 추출했다. canonical
PostgreSQL 구현은 native query 의 FOR UPDATE SKIP LOCKED 를 쓰고, 다른 벤더는 등가물을
공급한다(예: SQL Server WITH (UPDLOCK, READPAST)). eligibility predicate(I3 — concurrent-relay
안전을 위한 SKIP LOCKED)와 per-aggregate FIFO gate(I4 — NOT EXISTS correlated subquery)를
전부 SQL 에서 강제한다. 한 배치에 aggregate 당 최대 한 row(head)만 나타난다. 어댑터는 추가
in-memory 필터링을 하지 않는다 — 리포지토리가 반환한 모든 row 를 IN_FLIGHT 로 전이시켜 호출자에
돌려준다. 전체 SQL gate 동작은 PG contract 테스트(Testcontainers)가 검증한다.
FIFO gate 의 "같은 aggregate"와 "앞선 row":
- canonical row 끼리는
(tenant_scope, aggregate_type, aggregate_id)가 같아야 같은 aggregate 이고, 순서는(aggregate_sequence, event_index)다. 그래서occurred_at이 같은 이벤트도 한 번에 하나씩 나가고, 다른 tenant·type 의 DEAD row 가 같은aggregate_id를 막지 않는다. 인덱스는V18의ix_outbox_event_unpublished_aggregate_order. - gate 가 비교하는 row 는 전부 canonical 이다: V19 가 envelope 없는 미발행 row 를 거부한다.
읽을 수 없는 row(envelope 없음, 부분 metadata, 저장된 hash 와 bytes 불일치 등)는 claim 에서 DEAD 로 옮기고 배치에서 뺀다. 예전에는 예외로 claim transaction 전체가 롤백되고 다음 claim 이 같은 row 를 다시 먼저 골라 relay 가 영구히 멈췄다. 추측해서 발행하지 않으므로 fail-closed 는 유지된다.
eligible row(I3/I4/I6):
PENDING—next_attempt_at <= now(insert 시 즉시 eligible)FAILED—next_attempt_at <= now(backoff 경과)IN_FLIGHT—next_attempt_at <= now(orphaned row)
claim lease와 fencing token (V17)
in-flight timeout이 지나면 다른 relay가 IN_FLIGHT row를 다시 claim한다. 예전 완료 처리는
event_id만으로 row를 읽어 status를 덮어썼고 claim·publish·완료가 서로 다른 transaction이라,
timeout을 넘겨 멈췄던 relay A가 relay B의 결과를 덮을 수 있었다 — B가 PUBLISHED로 만든 row를
A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISHED는 B의 실패를 가린다.
- claim:
claimBatch(owner, ...)가 row lock(FOR UPDATE SKIP LOCKED)을 쥔 상태에서lease_owner = owner,lease_token = lease_token + 1을 기록하고OutboxLease(event, owner, token)을 돌려준다. owner는 relay 인스턴스(PublishPendingOutboxEventsUseCase)마다 한 번 만든 UUID다. - 완료:
markPublished/markFailed/markDead(lease)는 한 문장의 조건부 UPDATE다 —WHERE event_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token = ?. owner는 비우고 token은 그대로 둔다(token은 증가만 한다). 1 row면APPLIED, 0 row면STALE.findById+ setter 경로와@Version은 쓰지 않는다. - 실패 원인 코드(
V22):markFailed·markDeferred·markDead는 같은 조건부 UPDATE에서last_failure_code를 쓴다(publisher가 붙인 코드, 없으면 결과·예외 타입 이름). append INSERT는 이 열을 쓰지 않는다. claim이 행을 DEAD로 옮길 때(ATTEMPT_COUNTERS_INCONSISTENT,UNREADABLE_ROW)는 claim의 row lock 아래 entity flush로 그 이유를 쓴다 — 앞선 발행 실패의 코드가 남아 원인을 잘못 가리키지 않게(재리뷰 2차 RR-02-12). 이 DEAD는 relay 결과를 거치지 않아outbox.publisher.published.total{outcome=DEAD}에 안 잡히므로 경보는outbox.pending.size{status=DEAD}로도 건다.longRetries(n, now)는 미룬 claim이 n번 이상인 FAILED 행 수와 가장 오래된 행의 나이를 센다(outbox.retry.long.*게이지). 상태PARKED는 DDL이 없다 — claim이 PENDING·FAILED·IN_FLIGHT만 고르고, FIFO 게이트는 PUBLISHED 아닌 모든 행을 막는 앞 행으로 본다. claim이 시도 횟수가 어긋난 행(deferred_attempt_count > attempt_count)을 만나면 DEAD로 옮기고 WARNerror.reason=ATTEMPT_COUNTERS_INCONSISTENT로 원인을 말한다(재리뷰 2026-11-03 RR-05-01·03). - 미룬 실패와 claim 해제(
V20):markDeferred(lease, next)는markFailed와 같은 전이에deferred_attempt_count + 1을 더한다(일시적 실패는 시도 예산 밖).releaseLease(lease, at)는 손대지 않은 claim을PENDING,next_attempt_at = at,attempt_count - 1로 되돌린다(종료 중인 relay가 쓴다). 둘 다 같은 lease 조건부 UPDATE다. - aggregate 순서 번호(
V21):JpaOutboxStore는OutboxAggregateSequencePort도 구현한다.outbox_aggregate_sequencecounter를UPDATE(row lock)로 올린다. 올린 값은 그 aggregate의 가장 큰 outbox 번호보다 작아지지 않는다(rolling 배포 중 옛 인스턴스가 쓴 벽시계 번호가 먼저 온다). counter가 없으면INSERT ... ON CONFLICT DO NOTHING으로 만든다. 시작값은 남은 outbox 최대 번호와 V21이 기록한 floor(outbox_aggregate_sequence_floor, V21 적용 시각의 epoch 마이크로초) 중 큰 값 + 1이다. 첫 쓰기 두 개가 겹치면 두 번째는 첫 번째 커밋을 기다렸다가 아무것도 넣지 않고 증가만 한다(리뷰 RR-03-01). V21은 남은 row가 있는 aggregate의 counter를 그 최대 번호로 미리 만들고,outbox_event의 순서 키 유일 인덱스도 만든다 — 기존 중복 row가 있으면 migration이 실패하므로 먼저 정리해야 한다 (docs/runbooks/outbox-dead-letter.md§8). - STALE은 예외가 아니다: row의 결과는 지금 lease를 가진 relay가 쓴다. use case는 결과를
OutboxRelayResult.Outcome.STALE로 남기고OutboxRelayFailureReportPort.reportStaleCompletion으로 알린 뒤 다음 이벤트로 넘어간다. FAILED/DEAD report는 보내지 않는다(아무것도 저장되지 않았다).outbox.publisher.published.total{outcome=STALE}이 0보다 크면 in-flight timeout이 relay 정지 시간보다 짧다는 뜻이고, broker는 그 이벤트를 두 번 받았을 수 있다. - row가 없을 때도 0 row라
STALE이다. 예전처럼 throw하지 않는 이유: fencing 뒤에는 0 row가 "다른 relay가 가져감"이라는 정상 결과이고, 그 row는 가져간 relay가 끝내거나 timeout 뒤 다시 claim되므로 FIFO 큐가 막히지 않는다.
OutboxEventEntity 의 결정
AuditableEntity미상속(D6 — infra 엔티티).IdempotencyRecordEntity처럼 outbox row 는 도메인 애그리거트가 아니라 인프라 record 다. 자체 temporal 필드(occurred_at,next_attempt_at)가 도메인 의미를 갖고, genericcreated_at/updated_ataudit 컬럼과 섞이면 안 된다.- mutating setter 노출은 의도. claim은 lock된 managed 엔티티 위에서 상태(status /
attempt_count / next_attempt_at / lease)를 전이시킨다. 완료는 setter가 아니라 lease 조건부
bulk UPDATE다. outbox 어댑터만
이 필드를 건드리고, 모든 mutation 이 use case 소유
TransactionPort.inWrite()경계 안에서 돌기에 안전하다. next_attempt_atdual-purpose(I6 — 추가 컬럼 없음):PENDING: insert 때occurred_at으로 세팅 → 최초 claim 체크(next_attempt_at <= now)가 즉시 만족.IN_FLIGHT:claim_time + in_flight_timeout→ orphaned row 가 visibility window 만료 후 재claim 가능.FAILED:now + backoff→ backoff window 경과 후에만 재시도.
status는PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD문자열이다.Persistable<String>(새 엔티티는isNew() == true). 식별자를 직접 넣고@Version이 없는 엔티티를 Spring Data 는 기존 row 로 보고 merge 한다. 그래서 같은event_id로 두 번 append 하면 이미 PUBLISHED 된 row 가 PENDING·attempt 0 으로 덮여 다시 발행됐다. 이제 append 는 항상 insert 이고, 중복은 primary key 위반(23505)으로 드러난다.
metric 쿼리 반환 형태
OutboxEventJpaRepository.countGroupedByStatus() 는 [status(String), count(Long)],
findOldestUnpublishedOccurredAtByEventType() 는 [eventType(String), oldestOccurredAt(Instant)]
2-요소 배열 리스트를 돌려준다(각각 outbox.pending.size, outbox.publisher.lag gauge 용).
두 쿼리 모두 PUBLISHED row 는 세지 않는다 — retention 기간 동안 테이블 대부분이 PUBLISHED 라,
매 poll 마다 테이블 전체를 세게 된다.
JpaOutboxStore.oldestUnpublishedAgeSecondsByEventType 가 HashMap 을 쓰는 건 키가
enum 이 아니라 String(event-type 이름)이기 때문이다 — countByStatus() 는 키가
OutboxEventStatus enum 이라 EnumMap 을 쓴다(두 반환 타입이 의도적으로 다름).
status 에는 CHECK 가 없어 이 버전이 모르는 상태(뒤 버전이 쓴 상태, 손으로 친 값)가 있을 수 있다.
countByStatus() 는 그 상태만 빼고 세고 처음 한 번 WARN 으로 이름과 행 수를 말한다. 예전에는 그 이름 하나로
집계 전체가 실패해 PENDING 게이지까지 꺼졌다(재리뷰 2차 RR-02-11).
OutboxReaper
PUBLISHED row 는 이미 전달된 terminal-success record 라 무한 보관할 필요가 없다. reaper 가
retention 보다 오래된 PUBLISHED row 를 주기적으로 비워 테이블 성장과 metric gauge 를 묶는다.
스케줄링은 컴포지션 루트의 @EnableScheduling 으로 켜진다. 삭제는 deletePublishedBatch 로
1,000 row 씩, 배치마다 별도 transaction 으로 돌리고 배치가 덜 차면 멈춘다 — relay 장애 뒤 쌓인
PUBLISHED backlog 를 한 transaction 으로 지우면 그 사이 모든 row lock 을 쥔 긴 transaction 이 된다.
고정 interval / clock-skew 미처리는 프로젝트 선택(부하 하
cadence 측정 필요). retention 한 값은 reaper-local 이라 @Value 로 받지만, canonical 6-property
문서는 app-bootstrap OutboxSettings / application.yml 에 있다.
JPA production capability candidate
src/config/jpa/readiness-cards.yaml이 capability와 독립 schema stream의
machine-readable SSOT다(개수는 registry가 소유한다). selected base card와 implemented-candidate reliability card를
구분하며, 실제 PostgreSQL 테스트 통과만으로 immutable 운영 evidence가 필요한 R2를 주장하지
않는다.
이미 쓰이는 테이블을 잠그는 migration은 그 잠금 앞에 SET LOCAL lock_timeout = '5s';를 둔다. 상한이 없으면
그 테이블을 건드린 열린 트랜잭션 하나 뒤에서 끝없이 기다리고, 그동안 뒤에 온 읽기·쓰기가 모두 migration 뒤에 줄을
선다(V22, 재리뷰 2차 RR-02-09). MigrationLockWaitTest가 이 leaf DB에 도는 모든 tree를 검사하고,
postgresqlMigrationLockWaitIntegrationTest lane이 실제 PostgreSQL에서 상한 안에 실패하는지 본다
(docs/jpa/migration-guide.md "Bound the lock wait").
Flyway의 PostgreSQL 마이그레이션 잠금은 트랜잭션이 아니라 세션에 둔다. Flyway 기본값은 실행 내내 트랜잭션을
열어 두고, CREATE INDEX CONCURRENTLY·REINDEX … CONCURRENTLY는 그 트랜잭션이 끝나기를 기다려 배포가
끝나지 않는다(재리뷰 round6 RR6-03-01). Spring Boot의 Flyway는 config/module-defaults/persistence-jpa.yml의
spring.flyway.postgresql.transactional-lock: false로, 템플릿이 직접 만드는 Flyway는
FlywaySchemaPolicy.configure()로 받는다. 운영 코드가 Flyway.configure()를 직접 부르면
JpaProductionArchitectureTest가 거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다
(docs/jpa/migration-guide.md "Who may change the schema", lane postgresqlConcurrentIndexMigrationIntegrationTest).
적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로
바꾼 파일은 이미 그것을 적용한 모든 DB의 기동을 막는다. 변경은 새 버전으로 추가하고,
src/test/resources/db/applied-migrations.sha256에 한 줄을 더한다
(AppliedMigrationImmutabilityTest가 검사). 2026-09-23~25 사이에 수정본 postgresql/V9·V13을
적용해 만든 개발 DB는 원복된 파일과 checksum이 다르므로 한 번 flyway repair가 필요하다. 그
사이 수정본이 바꾸려던 char(64)→varchar(64)는 V16이 한다.
독립 Flyway stream은 broad classpath:db/migration으로 함께 실행하지 않는다. 각 stream은
자기 location/history table을 사용하고 non-empty schema adoption 때 version 0 baseline을 명시한
뒤 V1부터 실행한다.
| Capability | Location | History table | 상태 |
|---|---|---|---|
| core/adoption | db/migration/jpa/core |
flyway_jpa_core_history |
selected candidate |
| idempotency | db/migration/jpa/idempotency |
flyway_jpa_idempotency_history |
implemented-candidate |
owner-safe idempotency
PostgreSqlIdempotencyStore는 row lock을 얻은 뒤 clock_timestamp()를 평가한다.
claim takeover와 start/renew/complete/fail/release는 scope/state/owner/attempt/claim operation/
state revision을 SQL predicate로 다시 검증한다. expired CLAIMED(와 FAILED_RETRYABLE)만 takeover하며
expired EXECUTING은 행을 바꾸지 않고 reconciliation(RecoveryRequired)을 요구한다(2026-11-04 소유자 결정 —
이 문단은 그 전의 ABANDONED로 닫던 동작을 적고 있었다). takeover는 같은 attempt의 재생보다 먼저 본다.
시작을 거절당했거나 재시도 가능 실패로 끝난 attempt가 같은 attempt로 다시 claim해도 넘겨받는다(라운드6
RR6-02-01). raw client key는 저장하지 않고 versioned HMAC scope digest만 쓴다.
Redis store·in-memory fake와 같은 계약(IdempotencyStoreContract)을 실 PostgreSQL에서 통과한다
(PostgreSqlIdempotencyStoreContractTest, jpaPlatformContractTest). 그 계약에 맞춰 두 가지를
정했다(review 2026-11-01 01-05). 이전 revision의 핸들은 owner 튜플이 다르므로 NOT_OWNER다.
OPERATION_CONFLICT는 둘이다. 하나는 owner token이 같은데 호출이 claim과 다른 operation id를 댄 경우로, 다섯
전이(start·renew·complete·fail·release) 모두 거절하고 행을 바꾸지 않는다. 같은 token·다른 operation의 inspect도
상태와 상관없이(완료된 행도) OPERATION_CONFLICT다(2026-11-06 소유자 결정 — 전에는 CAS가 핸들의 claim
operation만 보고 호출의 id는 last_transition_operation_id에 적기만 해서 적용했다). 다른 하나는 같은 operation
id가 다른 인자로 이미 적용된 경우다. complete 재생은 같은 owner token에만 확인한다 — 같은 operation id를 쓴 다른
attempt의 늦은 complete는 NOT_OWNER다(전에는 operation id만 보고 ALREADY_COMPLETED_SAME_RESULT). 시작은 핸들 말고 인자가 없어서,
이미 기록된 시작과 digest가 다르면 다른 핸들이다 — 넘겨받기 전 핸들은 NOT_OWNER, 재생받은 현재 핸들은
NOT_CLAIMED(라운드6 RR6-02-01, 전에는 OPERATION_CONFLICT). renew는 EXECUTING의
lease만 늘리고, 시작 전 CLAIMED는 NOT_IN_PROGRESS다.
outbox V2 (삭제됨)
immutable outbox storage·polling delivery V2(jpa/outbox-storage, jpa/outbox-polling stream과
그 adapter)는 어떤 composition도 location을 설정한 적 없는 미조립 세대라 2026-09-25에 삭제했다
(docs/capability-status.md "제거된 코드"). 실제로 도는 v1 outbox_event relay가 V2의
owner/token CAS를 이어받았다(위 "claim lease와 fencing token").
실제 PostgreSQL task
base task 외에 다음 candidate task가 Docker 부재 시 skip이 아니라 실패하도록 등록돼 있다.
postgresqlIdempotencyIntegrationTest
readiness card 검사 (evidence manifest 폐기)
readiness-cards.yaml의 evidence.scenarios와 evidence.task-claims가 required evidence를 실제
테스트와 task에 연결한다. build-tools의 JPA evidence manifest(ca.jpa-evidence,
ca.jpa-qualification, verifyJpaCandidateEvidence, verifyJpaPrimaryFoundationEvidence,
jpa-r2-evidence.yml)는 소유자 결정 4(2026-09-25)로 폐기했다. 그 manifest가 증명하던 사실은
이제 두 곳에서 확인한다.
JpaReadinessRegistryTest(이 leaf의test): 카드 상태·선행 관계(순환 없음), 구현된 카드가 가리키는 이 leaf의 task가build.gradle에 선언된 lane인지, 인용한 scenario 메서드가src/postgresqlIntegrationTest에 있는지, required evidence가 모두 덮이는지, 소유 schema stream의 location·history table이 고유하고 존재하는지.- readiness lane 자체: 카드가 인용한 scenario마다 lane의 required test가 되고(
requires), lane은 skip을 거절한다(rejectSkipped). 실제 PostgreSQL이 없으면 skip이 아니라 실패한다.
./gradlew :adapter:outbound:persistence-jpa:test --tests '*JpaReadinessRegistryTest' --console=plain
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain # 모든 readiness·platform lane
R2(운영 evidence) 승격은 더 이상 build가 판정하지 않는다. clean revision에서 위 lane을 돌린
CI 결과(jpa-release job의 JUnit XML artifact)를 검토해 결정한다.
stream migration이 중단되면 history/registry/object 상태를 먼저 확인하고 기존 migration을
임의 수정하거나 history를 바로 repair하지 않는다. 장애를 수정한 forward migration으로
복구하는 운영 절차는 docs/runbooks/migration-failed.md를 따른다.
lock — 분산 락
provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다. 여기서는 어댑터/설정 결정 근거만 적는다.
LockRegistryDistributedLock 계약
- D4 — transaction-commit ordering invariant. 이 어댑터는 트랜잭션 경계를 관리하지 않는다.
호출자는 보호된 트랜잭션이 커밋된 뒤에만 핸들(
DistributedLock.close())을 release 해야 한다. 커밋 전(트랜잭션 안)에 release 하면 lost-update race 가 생긴다. - D5 — finite waitTime + lease TTL.
tryAcquire는 Spring IntegrationDistributedLock이면tryLock(waitTime, leaseTtl)로, 일반Lock이면Lock.tryLock(long, TimeUnit)으로 최대waitTime만 블록하고, 잡으면 핸들을, 못 잡으면LockAcquisitionTimeoutException을 던진다. 무한 블로킹은 쓰지 않는다. leaseTtl > configuredTtl은IllegalArgumentException으로 거부한다. provider 기본 TTL 보다 긴 lease 를 약속하는 건 false contract 다. shipped 와이어링에선leaseTtl == configuredTtl(둘 다LockSettings.leaseTtl()바인딩)이라 이 가드는 mis-wired 호출자/테스트에서만 fail-fast 로 발동한다.- 반환 핸들은
lock::unlock람다(SAM 인터페이스 충족).InterruptedException은 interrupt flag 를 복원하고LockAcquisitionTimeoutException으로 변환한다.
TTL 주의 (SI 7.0)
JdbcLockRegistry: 기본 TTL 은JdbcLockRegistry(LockRepository, Duration)생성자로 설정하고, acquisition 별 TTL 은DistributedLock.tryLock(Duration waitTime, Duration ttl)로 전달한다. 크래시한 JVM 의 row 는 lock TTL 만료 후 다음 acquire 시도에서 회수된다.DefaultLockRegistry: TTL 은 advisory 이고 무의미하다 — JVM 크래시가 in-JVM 락을 프로세스와 함께 자동으로 떨군다.
SI-LOCK-C5 — lease 만료 후 release
반환 핸들은 lock::unlock 이다. lease TTL 이 close() 전에 만료된 JdbcLockRegistry
의 경우, 내부 JdbcLock.unlock() 이 ConcurrentModificationException 을 던진다(row 가 이미
회수됨). 이 어댑터는 여기서 일부러 잡지 않는다 — metered distributedLockProvider 데코레이터
(컴포지션 루트)가 SI-LOCK-C5 계약을 소유한다: 로그 + lock.lease.expired metric 후 close() 에서
정상 return 해, 만료가 호출자의 보호작업 예외를 가리지 않게 한다. in-process DefaultLockRegistry
경로는 만료가 없어 그 close() 가 이 예외를 던질 수 없다.
DistributedLockPersistenceConfig 와이어링 결정
jdbcDistributedLock빈은 일부러@Primary가 아니다. 같은 설정이 이를 metrics 데코레이터(MeteredDistributedLock, package-private)로 감싸@PrimarydistributedLockProvider빈으로 노출한다. 예전에는 app-bootstrap의DistributedLockConfig가 감쌌지만, JDBC 락이 있을 때만 의미가 있는 코드라 이 모듈로 옮겼다. SI 타입은 여전히 이 모듈 밖으로 보이지 않는다(SI 는implementation의존).DefaultLockRepository는InitializingBean/SmartLifecycle을 구현해 Spring 이 lifecycle 을 자동 관리하고,ApplicationContextAware로PlatformTransactionManager를 auto-discover 한다. app-bootstrap Testcontainers 테스트가 와이어링 갭을 드러내면 부트스트랩이setTransactionManager로 명시 전달할 수 있다.setCheckDatabaseOnStart(false):INT_LOCK테이블은 첫 lock acquire 전에 Flyway V4/V5 가 provision 하므로 DDL 체크를 건너뛴다.JdbcLockRegistry(lockRepository, settings.leaseTtl()): Spring Integration 7.0 이후 기본 TTL 은 repository setter 가 아니라 registry 생성자에서 설정한다. 어댑터는 호출별leaseTtl도DistributedLock.tryLock(waitTime, leaseTtl)로 전달한다.
LockSettings
app.lock.* 에서 바인딩되는 yaml-only 기본값이다(config/module-defaults/persistence-jpa.yml).
새 APP_* env 키가 아니므로 env-keys.yaml 엔트리가 필요 없다. DistributedLockPersistenceConfig의
@EnableConfigurationProperties가 바인딩한다. cross-field invariant: leaseTtl >= waitTime
이어야 한다 — TTL 이 waitTime 보다 먼저 만료되면 첫 holder 의 보호작업이 끝나기 전에 두 번째
holder 가 락을 잡을 수 있다.
MeteredDistributedLock (app-bootstrap에서 이동)
DistributedLockPort를 감싸는 얇은 Micrometer 데코레이터다.tryAcquire호출마다lock.acquisition카운터를outcome태그와 함께 1 증가시킨다. 태그 값은 세 가지:acquired(락 획득 성공, 위임 핸들 반환),timeout(LockAcquisitionTimeoutException발생),error(그 외 모든RuntimeException발생). 메트릭 이름과 태그 값은docs/registries/metrics.yaml의lock.acquisition행과 일치해야 한다.- 리스 만료(lease-expiry) CME 흡수. 보유자가
close()를 호출하기 전에 리스(저장소 TTL)가 만료되면 그 락 행은 이미 다른 인스턴스가 회수해 갔을 수 있고, 그 시점에 내부JdbcLock.unlock()은ConcurrentModificationException(CME)을 던진다. 이 예외를 호출자의finally { lock.close(); }블록 밖으로 그대로 전파하면 보호 구간(critical section)에서 발생한 본래 예외를 가려버린다 (masking). 그래서 CME 만 잡아 WARN 로그를 남기고 태그 없는lock.lease.expired카운터를 1 증가시킨 뒤close()는 정상 복귀시킨다. 이렇게 해야 신호(로그+메트릭)는 남기면서도 호출자의 정상 흐름과 예외 전파를 방해하지 않는다. 오직ConcurrentModificationException만 흡수하며, DB 장애 같은 다른 예외(예:DataAccessResourceFailureException)는 리스 만료 신호가 아니므로 손대지 않고 그대로 전파한다. - MeterRegistry 부재 시 no-op. 레지스트리를
ObjectProvider.getIfAvailable()로 해석하므로 클래스패스에MeterRegistry빈이 없으면(Actuator 미탑재) 모든 메트릭 연산이 조용히 no-op 이 된다.BackgroundJobMetrics선례와 동일한 패턴이다. - 메트릭 실패가 락 경로를 절대 깨뜨리지 않음. 카운터 등록·증가는 모두 try/catch 로 감싸 예외를 로깅 후 삼킨다(log-and-swallow). Micrometer 쪽 실패가 락 획득·보유·실패 보고를 막는 일은 없어야 하기 때문이다.
startup — 관계형 기동 정책 (app-bootstrap에서 이동)
JpaStartupAutoConfiguration(package-private, 모듈 스위치 app.persistence-jpa.enabled
아래)이 아래 가드를 등록한다. 전부 adapter:outbound:support의 StartupFailures로 실패하므로 exit
코드(78/70/71)와 구조화 로그 필드(startup.phase/error.code/error.category)는 옮기기 전과 같다.
migrationStartupRunner는 @ConditionalOnMissingBean(FlywayMigrationStrategy)라, 자기 전략을 둔
애플리케이션(sample-portfolio의 두 번째 마이그레이션 스트림)에는 끼어들지 않는다.
FlywayProdSafetyValidator
prod프로파일에서 Flyway 안전장치가 꺼지지 못하도록 런타임에서 강제한다. Flyway 옵션은application.yml에 안전값으로 고정돼 있지만(baseline-on-migrate=false,out-of-order=false,clean-disabled=true), 환경별 override 가 프로덕션에서 이 값을 조용히 되돌릴 수 있다. 이 검증기는 그런 override 를 시작 시점에 잡아PROFILE_MISMATCH(exit 71)로 부팅을 막는다.- 금지하는 옵션은 각각 "복구 불가능한 위험" 때문이다.
baseline-on-migrate=true는 누락된 마이그레이션을 감지하는 안전망을 없애고,out-of-order=true는 개발자 간 마이그레이션 적용 순서 일관성을 깨며,clean-disabled=false는 스키마 전체를 드롭하는 파괴적clean명령을 다시 활성화한다. - 프로파일 비교는 대소문자를 무시한다.
SPRING_PROFILES_ACTIVE=PROD처럼 대문자 오타가 나도 가드가 우회되지 않게 하기 위함이다. - Flyway repair 는 가드 대상이 아니다. repair 는 property 가 아니라 Flyway 명령이고 스켈레톤은
repair 호출 경로 자체를 배선하지 않으므로, "prod 에서 repair 금지"는 런타임 트리거가 없는
문서화된 정책으로 남는다. 부분 스키마 복구는 in-prod Flyway repair 가 아니라
runbook(
runbook://migration/manual-recovery)을 통한 수동 복구로 가도록 실패 메시지에 명시한다. (프로젝트가 repair 경로를 추가한다면 동일하게 prod 게이트 + non-prod 감사 로그를 걸어야 한다.)
RequiredEnvironmentValidator
- datasource 연결 환경변수를 마이그레이션 실행 전에 검증해 부팅을 빨리 실패시킨다. Flyway
forward-only 마이그레이션은 context refresh 동안 애플리케이션 datasource 에 대해 실행된다. 연결
환경변수가 빠져 있으면 마이그레이션은 시작 단계 구분자 없이 불투명한 driver/connection 에러로
한참 뒤에야 실패한다. 이 검증기는 그것을 명시적인 env 검증 실패(
STARTUP_VALIDATION_FAILED, exit 78)로 바꿔, 누락된 운영자용 env 키를 전부 이름으로 짚어준다. - 검증 범위를 datasource 3종(url/username/driver)으로 의도적으로 좁혔다. 이것들이 이 브랜치가
소유하는 마이그레이션 전제조건이기 때문이다. app-name(
BootstrapSettings), issuer-uri(security settings) 등 다른 필수값은 각 모듈의 가드가 책임지므로 여기서 중복 검증하지 않는다. - 값이 없거나(blank) 공백이면 모두 "누락"으로 본다. spring-dotenv 에서 미설정 placeholder
${...}가 빈 문자열로 해석되기 때문에, null 뿐 아니라 blank 도 누락으로 처리해야 빈틈이 없다. - 메시지는 env 키 이름순으로 정렬해 출력한다. Map 순회 순서와 무관하게 결정적이고 안정적인 실패 메시지를 보장하기 위함이다.
JpaStartupAutoConfiguration (옛 MigrationStartupConfig·PersistenceJpaRootAutoConfiguration·JpaPlatformRuntimeAutoConfiguration)
- 마이그레이션 전략과 관계형 기동 가드를 한곳에 모은다. app-bootstrap에서는 네 개 설정 클래스와
RuntimeSafetyConfig의 validator 목록에 흩어져 있었고, JPA 스위치를 합성 루트가 알아야 했다.JpaPlatformAutoConfiguration(플랫폼 조립 factory)은 지웠고, 보고서 조립은JpaPlatformReport로 옮겼다. migrationStartupRunner빈 이름은 유지한다. Spring Boot Flyway 오토컨피규레이션이migrate()를 위임하는FlywayMigrationStrategy다.
MigrationStartupRunner
FlywayMigrationStrategy로 등록해 context refresh 중에 마이그레이션을 직접 실행한다(오토컨피그 기본값을 그대로 두지 않는다). refresh 안에서 실행한다는 것은 마이그레이션이 완료되거나 부팅을 실패시키는 일이 애플리케이션이 readiness 를 보고하기 전에 일어난다는 뜻이다. 따라서 절반만 마이그레이션된 스키마가 트래픽을 받는 일이 구조적으로 없다(actuator readiness probe 의 형태 자체는 health-lifecycle 브랜치가 소유하고, 여기서는 "마이그레이션 → ready" 순서만 책임진다).FlywayException을StartupFailures.migrationFailed(MIGRATION_FAILED, exit 70)로 번역한다. 일반적이고 구분 안 되는 스택트레이스 대신 구조화된MIGRATION_FAILED로그와 표준 exit 코드를 남기기 위함이다.- 멀티 인스턴스에서는 in-app 마이그레이션 + Flyway 자체 schema-history 락에 의존하는 것이 기본
전략이다. 여러 레플리카의 동시
migrate()를 Flyway 의 락이 직렬화한다. 대안인 "in-app 마이그레이션을 끄고 플랫폼 one-shot Job 으로 돌리기"는 "migration=Job"을 강제하는 공개 표준이 없는 배포 선택이라 스켈레톤 기본값이 아니다. Job 으로 돌리는 프로젝트는 이 빈의migrate()를 no-op 으로 만들면 된다.
HikariPoolConstraintValidator
- HikariCP 노브 사이의 상호 제약을 부팅 실패로 바꾼다. Hikari/Tomcat 은 잘못된 값을 결국
거부하지만 pool/connector 초기화 시점에 난해한 메시지로만 거부한다. 이 검증기는 계약을 일찍·명확
하게 만든다: resolved Spring property 를 읽고, 위반을 모두 모아 운영자가 실제로 설정한
APP_*환경 키를 메시지에 담아IllegalStateException을 던진다. 속성이 없으면 건너뛰고(placeholder/ 프레임워크 기본값이 소유), 있을 때만 검사한다. - 강제하는 제약과 그 숫자의 근거.
connection-timeout >= 250ms(너무 짧으면 정상 연결도 타임 아웃).validation-timeout < connection-timeout(둘 다 있을 때; validation-timeout 기본 5000ms 가 흔한 connection-timeout 5s/5000ms 와 같아지는 충돌을 해소).keepalive-time < max-lifetime(둘 다 있을 때; keepalive 가 lifetime 보다 길면 의미 없음).leak-detection-threshold는 0(비활성)이 아니라면>= 2000ms(너무 작으면 정상 사용을 누수로 오탐). - Spring Boot와 같은 Duration 문법을 검증한다.
env-keys.yaml의connection-timeout기본값은5s인데src/.env는30000(ms)을 준다. resolved 값을String으로 읽은 뒤DurationStyle로 plain milliseconds, simple duration(5s)과 ISO-8601(PT5S)을 같은 milliseconds 계약으로 변환한다. present-but-invalid 값은 부재로 조용히 취급하지 않고 property 이름을 포함한 startup validation failure로 거절한다. - env 키가 아직 없는 노브는 "env key pending" 문구를 쓴다.
connection-timeout/max-lifetime만env-keys.yaml에 등록돼 있고, greenfield 노브(validation-timeout, keepalive-time, leak-detection-threshold)는 env 키가 없다. 없는 키 이름을 지어내는 대신 pending 문구를 메시지에 넣는다.
OpenInViewSafetyValidator
- OSIV(Open Session In View) OFF 를 hard stop 으로 강제한다. OSIV 가 켜져 있으면 Hibernate
세션이 view 렌더링까지 열려 있어, presentation 레이어에서 lazy 연관을 건드리면 거기서 조용히 DB
쿼리가 나간다 — 이것이 정확히 금지된 레이어 경계 위반이다. Spring Boot 는
spring.jpa.open-in-view가 암묵 기본값일 때 WARN 만 찍을 뿐 명시적으로true로 설정한 배포는 막지 못한다. WARN 은 놓치기 쉬우므로, resolved 값이true면 운영자가 실제 설정한APP_DATASOURCE_OPEN_IN_VIEW키를 메시지에 담아 부팅을 실패시킨다. - 읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.
StartupRule로 위반만 돌려주고 support의StartupRuleRunner가 다른 싱글톤(DataSource·Flyway)을 만들기 전에 한 번 실행하며, 값이 없으면 Spring Boot 기본(이 스켈레톤은application.yml에서 OSIV off 가 기본)에 맡기며 *있는true*만 거부한다.
JpaDangerousConfigurationGuard (ddl-auto)
- Flyway를 physical schema의 유일한 writer로 유지한다. local convenience profile만으로 이뤄진
profile 집합이 아니면(
prod,staging, profile 없음,local+prod혼합 모두)spring.jpa.hibernate.ddl-auto가none또는validate일 때만 허용한다.update,create,create-drop, 빈 값, 그 밖의 값이면APP_DATASOURCE_DDL_AUTO를 이름으로 포함한PROFILE_MISMATCH로 부팅을 중단한다. mode 비교는 대소문자를 무시한다. - 검사는 이 guard 하나다. prod만 보던
JpaSchemaSafetyValidator는 이 guard보다 늦게 돌아 한 번도 발동하지 않았고, 실제 prod 거부는PROFILE_MISMATCH가 아닌IllegalStateException이었다. 두 검사를 합치면서 guard가PROFILE_MISMATCH를 던진다.