Files
clean-architecture-backend-…/docs/jpa/migration-guide.md
T
DongHyeonka 6764246ac9 fix(architecture): Flyway 규칙이 설정 객체를 직접 만드는 길도 막는다
문제 (재리뷰 round7 RR7-03-06)
- 규칙 문장은 "코드로 만드는 Flyway는 모두 FlywaySchemaPolicy.configure()
  에서 시작한다"(persistence-jpa CLAUDE.md, FlywaySchemaPolicy Javadoc,
  migration-guide)인데 JpaProductionArchitectureTest는 Flyway.configure()
  호출만 막는다. new FluentConfiguration(), new ClassicConfiguration(),
  FluentConfiguration::new로 만든 Flyway는 검사를 지나 Flyway의
  PostgreSQL 잠금 기본값(트랜잭션 안의 잠금)을 되찾는다. 그 잠금 아래
  동시 인덱스 마이그레이션은 끝나지 않는다(RR6-03-01).

고른 방법
- 규칙을 상수 EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY로 빼고, Flyway
  Configuration에 대입 가능한 타입의 생성자 접근(호출과 생성자 참조)을
  더 막는다. 하위 클래스와 직접 구현도 같은 접근이라 함께 걸린다.
  new Flyway(...)는 허용한다 — 정책의 설정 위에서는 정책의 Flyway다.
- 위반 fixture 4개(configure 호출, FluentConfiguration·ClassicConfiguration
  생성, 생성자 참조)와 허용 fixture 1개(정책 빌더, 정책 설정 위의
  new Flyway)를 ArchitectureViolationFixtureTest로 평가한다.
- 버린 안: callConstructor를 생성자 시그니처마다 나열 — Flyway 버전마다
  생성자 목록이 바뀌고 생성자 참조를 못 본다. new Flyway(...)까지 금지 —
  정책 설정 위의 정당한 사용까지 막는다.

위험·한계
- 하위 클래스 fixture는 두지 않았다. SpotBugs가 Flyway 설정을 상속한
  클래스를 분석하다 lombok.Generated를 못 찾아 testQualityCheck가 실패한다
  (빌드는 불완전 분석을 실패로 본다). 이 경우는 GREEN 1차 실행에서 규칙이
  잡는 것을 확인했고(g0306-archtest.log), 규칙 Javadoc에 이유를 적었다.
- 리플렉션이나 Configuration 맵으로 잠금 값을 덮어쓰는 것은 막지 않는다.
- 이 규칙을 이미 지키는 파생 서비스(업그레이드 안내 2절 15번)는 바꿀 것이
  없다. 설정 객체를 직접 만들던 서비스는 architectureTest가 새로 실패한다
  (안내 15번과 5절 「Flyway 잠금」 행에 적었다).

검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/)
RED — 6ec0c4f7 + 규칙 상수 추출(규칙 그대로)과 fixture·테스트:
- :app-bootstrap:architectureTest 1차 233건 중 3건 실패
  (FluentConfiguration·ClassicConfiguration·하위 클래스 fixture 통과),
  2차(생성자 참조 fixture 추가) 234건 중 4건 실패. Flyway.configure()
  fixture는 잡히고 허용 fixture는 통과 (red0306-arch*.log)
GREEN — 이 커밋의 트리 e7e19298:
- :app-bootstrap:architectureTest rc=0 (233건 실패 0; 위반 fixture 4개
  모두 걸리고 허용 fixture와 운영 코드는 통과)
- architectureCheck rc=0
- :adapter:outbound:persistence-jpa:check rc=0, :app-bootstrap:check rc=0
- :app-bootstrap:documentContractTest rc=0 (66건 실패 0)
- :app-bootstrap:testQualityCheck rc=0. 하위 클래스 fixture를 둔 1차
  트리(f8fecd1e)에서는 spotbugsArchitectureTest가 "missing analysis class
  lombok.Generated"로 실패했고, 그 fixture만 빼자 통과했다
  (g0306-testquality.log, g0306b-testquality.log)
- 같은 우회가 다른 곳에 있는지: 운영 코드 전체(src 아래 main·testFixtures)
  에서 Flyway를 만드는 곳은 FlywaySchemaPolicy와 규칙이 예외로 둔
  MessagingInboxSchemaStream의 Flyway.configure()뿐이다. optional 빌드와
  src/messaging에는 운영 Flyway 생성이 없다

Refs: docs/reviews/2026-11-03-rereview/README.md 18.5절 round7 1차 Declined 판정 (cb340001)
2026-11-07 01:28:33 +09:00

14 KiB

Migration Guide

Design §31-§32. Flyway owns the schema; Hibernate only validates.

Who may change the schema

Environment Mode
local, test, dev migrate at startup with the migration credential
staging, prod deployment-owned migration; the application validates only

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.

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).

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.

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.

Validation fails closed and never repairs

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.

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).

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.

Only Flyway's structured error codes reach the exception. Its messages embed the script path and part of the failing statement.

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.

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.

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.

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 runs it over every tree this leaf's database runs, SampleMigrationLockWaitTest over the sample's stream; a service stream copies the latter with its own directory. Both find the migrations the way Flyway does, decimal versions (V22_1__) included (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).

Concurrent index builds

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:

# 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. 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 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.

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.

Alone, a failed build 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 "Recover a failed concurrent index migration": confirm no build is running, drop the invalid index, remove the cause, delete that version's failed row and nothing else, deploy again. 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 shows both mixed files above.

An invalid index is not merely useless — the planner ignores it while every write still maintains it. 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.

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

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.