문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
199 lines
14 KiB
Markdown
199 lines
14 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 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`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스
|
|
스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 Flyway와 같은 방식으로 마이그레이션을 찾고, 소수
|
|
버전(`V22_1__`)도 포함한다(`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:
|
|
|
|
```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: it waits only for the transactions that hold a
|
|
lock on its table. `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 the drop too once it has touched the table, 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 statement 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](../runbooks/migration-failed.md) "Recover a failed concurrent index migration":
|
|
confirm no build is running, remove the cause, drop the invalid index a failed build or rebuild
|
|
left, delete that version's failed row and nothing else, deploy again. A failed `DROP INDEX
|
|
CONCURRENTLY` leaves invalid the index it was dropping; the runbook leaves that one for the deploy
|
|
again to drop, since dropped by hand it makes the same statement fail. 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 after a rebuild and a drop cancelled while they
|
|
waited for an open transaction, 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](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.
|