문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).
방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.
위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).
검증: GATES
Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# 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 calls `Flyway.configure()` directly. 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).
|
|
|
|
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).
|
|
|
|
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. 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).
|
|
|
|
## Concurrent index builds
|
|
|
|
`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` cannot run
|
|
inside a transaction block. Flyway recognizes `CREATE`/`DROP INDEX CONCURRENTLY` and runs such a
|
|
script outside a transaction on its own (above), but not `REINDEX … CONCURRENTLY`, which it runs in
|
|
the transaction for PostgreSQL to refuse. 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:
|
|
|
|
```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. `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. A failed concurrent build leaves an invalid index behind;
|
|
recovering is a single `DROP INDEX` when the migration did nothing else, and a manual reconstruction
|
|
of partial state when it did.
|
|
|
|
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.
|
|
|
|
## 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.
|