Files
clean-architecture-backend-…/docs/jpa/migration-guide.md
T
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.

고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
  gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
  `` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
  lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
  한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
  - support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
    `JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
  - repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
    `src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
    `composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
    plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
    `JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
    여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
  - experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
  증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
  고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.

버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.

위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
  `JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
  `PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
2026-11-07 17:56:34 +09:00

17 KiB

마이그레이션 가이드

설계서 §31-§32. 스키마는 Flyway가 가지고, Hibernate는 검증만 한다.

이 문서의 절 셋은 코드와 다른 문서가 영어 제목으로 가리킨다. 그래서 그 절 제목에는 영어 이름을 괄호로 함께 둔다: 「누가 스키마를 바꾸나 (Who may change the schema)」, 「잠금 대기에 상한을 둔다 (Bound the lock wait)」, 「동시 인덱스 빌드 (Concurrent index builds)」.

누가 스키마를 바꾸나 (Who may change the schema)

환경 방식
local, test, dev 마이그레이션 자격 증명으로 기동할 때 migrate한다
staging, prod 배포가 가진 마이그레이션. 애플리케이션은 검증만 한다

운영에서 애플리케이션 안에서 migrate하면 rolling deploy의 모든 인스턴스가 같은 스크립트를 적용하려고 경주하고, 진 쪽의 실패는 진짜 실패와 구별되지 않는다.

마이그레이션을 돌리는 쪽은 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, 또는 그 도구 설정 파일의 위 키).

세션 잠금은 Flyway가 잡은 연결이 실행 내내 Flyway의 것으로 남는다고 가정한다. 템플릿의 직접 Hikari 연결이 그것을 준다. 트랜잭션 모드 pooler(PgBouncer pool_mode = transaction) 뒤에서는 unlock이 다른 서버 연결로 가서 아무것도 풀지 못하고, 다음 마이그레이션은 풀의 연결이 아직 쥔 잠금을 기다린다. 마이그레이션은 직접 연결이나 세션 모드 풀로 돌린다.

ddl-auto는 validate나 none이다. update는 절대 쓰지 않는다. 그것은 아무것도 지우거나 좁히지 않으므로, 옛 스키마도 아니고 마이그레이션이 설명하는 스키마도 아닌 스키마를 만든다. 조용히, 먼저 뜬 인스턴스에서.

검증은 닫힌 채 실패하고, repair하지 않는다

기동할 때 Flyway 자신의 검증(과 Hibernate ddl-auto=validate)이 checksum 불일치, 빠진 마이그레이션, Hibernate가 동의하지 않는 스키마를 거부한다. 애플리케이션의 어떤 것도 repair를 부르지 않는다. 테스트에서는 testkit의 FlywayValidationGate가 실패한 ValidateResult를 SchemaMismatchException으로 바꾸고, 마이그레이션 계약 테스트가 그것을 쓴다.

repair는 schema history 테이블을 디스크에 있는 스크립트에 맞춰 다시 쓴다. 그것은 증거를 지워서 증상을 없앤다. checksum 불일치는 배포한 스크립트가 적용된 것과 다르다는 뜻이고, 물어야 할 것은 이 DB에 어느 변경이 빠졌느냐다. repair는 그 질문을 물을 수 없게 만든다. repair는 운영자, 이유, 승인이 있는 명시적 관리 작업으로만 있다(설계서 §8.4).

운영자가 이력에 하는 변경은 repair보다 좁은 것 하나다. 동시 인덱스 마이그레이션이 실패한 뒤, 그 버전을 다시 돌릴 수 있게 그 한 버전의 실패 행을 지운다(아래 「동시 인덱스 빌드」). 적용된 행과 그 checksum은 모두 그대로다.

예외에는 Flyway의 구조화된 오류 코드만 닿는다. Flyway의 메시지는 스크립트 경로와 실패한 문장 일부를 담는다.

잠금 대기에 상한을 둔다 (Bound the lock wait)

이미 쓰는 테이블을 잠그는 마이그레이션은, 잠금을 잡는 첫 문장 전에 SET LOCAL lock_timeout = '5s';로 시작한다. ALTER TABLE은 가장 강한 잠금을 잡아 평범한 읽기와도 부딪친다. 동시가 아닌 CREATE INDEX는 모든 쓰기를 멈추는 잠금을 잡는다. UPDATE와 DELETE는 다른 트랜잭션이 쥔 행을 기다린다. 상한이 없으면 마이그레이션은 그 테이블을 건드린 가장 오래된 열린 트랜잭션을 기다린다. psql에서 운영자가 잊은 BEGIN에는 마감이 없다. 그사이 도착하는 모든 읽기와 쓰기가 마이그레이션 뒤에 줄을 서고, 기다리는 동안 풀 연결을 쥔다. 상한이 있으면 마이그레이션은 5초 뒤 실패하고, Flyway가 통째로 롤백하고, DB는 그 앞 버전에 남고, 새 릴리스는 뜨지 않는다. 장애 대신 실패한 배포다. 그 트랜잭션이 끝난 뒤 다시 배포한다.

LOCAL인 이유: 평범한 SET은 Flyway가 빌린 풀 연결에서 마이그레이션보다 오래 남아, 나중에 그 연결에서 도는 모든 문장을 바꾼다. 값은 0이 아니다. lock_timeout = 0(또는 DEFAULT, 뒤의 RESET)은 상한이 아니다. executeInTransaction=false인 마이그레이션은 그것을 쓸 수 없다. 트랜잭션 밖의 SET LOCAL은 경고만 하기 때문이다. 그래서 테이블을 잠그는 문장은 트랜잭션 안에서 도는 마이그레이션에 넣는다. 같은 마이그레이션이 방금 만든 테이블에 대한 문장은 기다릴 것이 없어 상한이 필요 없다. CREATE TABLE IF NOT EXISTS는 해당하지 않는다. 테이블이 이미 있을 수 있기 때문이다.

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도 거부한다.

기억에 맡기지 않고 강제한다. 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). 규칙 전에 나간 마이그레이션은 상한 없이 기다리고 그대로 둔다 (이미 적용됐고, 적용된 파일은 고치지 않는다). 테스트가 그것을 나열하고 새것은 거부한다.

PostgreSqlMigrationLockWaitIntegrationTest(postgresqlMigrationLockWaitIntegrationTest)가 실제 PostgreSQL에서 보인다. 다른 트랜잭션이 테이블을 쥔 동안 상한 있는 마이그레이션은 상한 안에 포기하고 그 아래 버전을 남긴다. 또 inspector가 가진 Flyway 목록 사본을 그것이 나열한 문장에 대해 Flyway 자신과 비교하고(inspector는 Flyway가 SET LOCAL 옆에서 거부하는 바로 그때 그 문장을 이름 댄다), mixed=true에서 돈 VACUUM FULL이 SET LOCAL에도 불구하고 읽는 쪽을 기다리는 것도 보인다. Flyway 업그레이드가 목록에 더한 문장은 그 비교 밖이다. LockWaitMigrationInspectorTest가 Flyway 자신의 패턴 (PostgreSQLParser)을 고정하므로, 그런 업그레이드는 사본이 따라올 때까지 pull request의 ci를 실패시킨다.

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의 목록을 알 필요가 없다.

# V42__order_index.sql.conf
executeInTransaction=false

트랜잭션 밖에서도 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)을 찾는다.

testkit의 ConcurrentIndexMigrationInspector가 마이그레이션 테스트에서 스크립트를 이 관점으로 확인하고(기동 때 확인하는 것은 없다), 그 마이그레이션에 다른 것이 없기를 더 요구한다. 다른 문장 옆에 두면, 아무것도 설정하지 않았을 때 동시 문장은 Flyway가 파일을 하나도 돌리기 전에 거부하게 만든다. executeInTransaction=false면 Flyway는 문장마다 따로 커밋하고, 실패한 빌드는 그 앞 문장을 적용된 채 남긴다. 손으로 다시 맞춰야 하는 상태다.

혼자 있는 문장이 실패하면 무효 인덱스와 그 버전의 success = false 이력 행을 남기고, 그 행이 사라질 때까지 Flyway는 뒤의 모든 배포를 거부한다("Detected failed migration to version …"). 인덱스를 지우는 것만으로는 안 된다. 복구는 migration-failed.md 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)」다. 도는 빌드가 없는지 확인하고, 원인을 없애고, 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지우고, 그 버전의 실패 행만 지우고, 다시 배포한다. 실패한 DROP INDEX CONCURRENTLY는 지우던 인덱스를 무효로 남긴다. runbook은 그것을 다시 배포가 지우도록 남긴다. 손으로 지우면 같은 문장이 실패하기 때문이다. 이것은 flyway repair가 아니다. repair는 남은 행의 checksum도 다시 쓴다. PostgreSqlConcurrentIndexMigrationIntegrationTest(postgresqlConcurrentIndexMigrationIntegrationTest)가 runbook에서 읽은 runbook의 SQL을, 중복으로 실패한 unique 빌드 뒤와, 열린 트랜잭션을 기다리다 취소된 재빌드와 삭제 뒤에 돌리고, 위의 섞인 파일 둘도 보인다.

무효 인덱스는 쓸모없기만 한 게 아니다. planner는 그것을 무시하는데 모든 쓰기는 여전히 그것을 유지한다. 찾는 쿼리는 runbooks.md에 있다. 아무것도 그것을 자동으로 지우지 않는다. 무효 인덱스는 아직 도는 빌드를 뜻할 수도 있고, 카탈로그만으로는 둘을 구별할 수 없다.

업그레이드 시나리오

셋이고, 저마다 다른 것이 못 잡는 것을 잡는다.

시나리오 잡는 것
empty 뒤 마이그레이션에 맞추려고 고친 앞 마이그레이션이 새 DB에 더는 적용되지 않음
previous-release 실제 배포 경로. 이 릴리스의 마이그레이션을 돌리는 유일한 시나리오
oldest-supported 최근 DB에만 있는 상태를 몰래 가정하는 마이그레이션

시나리오마다 스키마 버전만이 아니라 데이터 불변식을 단언한다. 열 이름을 바꾸면서 내용을 잃은 마이그레이션은 버전은 맞고 데이터는 사라진 채로 남는다.