문제: 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를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).
검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).
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.
|