fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다
문제 (재리뷰 round7 영속성 RR7-03-01~05) - 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가 "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의 이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에 다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다. docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서 멈춘다. - 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다. 가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다 커밋해 앞 문장이 남는다. - 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX … CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다. - LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면 SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은 "늘 거부"라고 쓴다. - ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고 안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개 (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도 모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be executed within a pipeline"으로 실패한다. 고른 방법 - 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에 "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드 확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의 실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고 flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고 postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어 실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기 Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다. - 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와 잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태). - 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와 상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은 PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이 맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라 그대로 둔다. - ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을 두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스 문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어 sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다 (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을 파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로 바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다. 위험·한계 - 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다. 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이 없다(업그레이드 안내 4.1에 적음). - runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라 성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이 지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다. - ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음). - Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라 UP-TO-DATE로 처리됐다. 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 기준73d39212+ 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시 메서드, + 임시 ledger V004): - persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중 2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log) - postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장 대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied, conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데 검사기는 통과 (red2-lockwait.log) - postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 — 옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version 2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김, runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음) (red2-concurrent.log) - ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기 IT "name it as an exception here", 다른 IT 둘 "cannot be executed within a pipeline" (red-ledger.log) GREEN — 이 커밋의 트리b49369e7: - :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0), :testQualityCheck rc=0 - postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0) - postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0) - -p optional-platforms :grpc:grpc-operation-ledger-jpa:check integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0) - :app-bootstrap:documentContractTest rc=0 (66건 실패 0) - 두 빌드의 verifyStrictLaneStages --dry-run rc=0 - ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고 메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면 rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent index statement"로 거부 - python3 scripts/check-work-docs.py --links docs: 깨진 링크 0 Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
This commit is contained in:
+35
-11
@@ -47,6 +47,10 @@ applied one, and the interesting question is which change is missing from this d
|
||||
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.
|
||||
|
||||
@@ -84,7 +88,9 @@ Flyway's list: Flyway runs it in the transaction, PostgreSQL refuses it there, a
|
||||
`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).
|
||||
`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
|
||||
@@ -112,18 +118,25 @@ optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigr
|
||||
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,
|
||||
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).
|
||||
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 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:
|
||||
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
|
||||
@@ -144,9 +157,20 @@ open holds the build, and a file run outside a transaction cannot bound that wai
|
||||
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.
|
||||
(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](../runbooks/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](runbooks.md) has the query that finds them. Nothing drops them automatically: an
|
||||
|
||||
@@ -73,7 +73,11 @@ A concurrent build failed. The index is ignored by the planner and maintained by
|
||||
|
||||
1. Confirm no build is currently running. An in-progress build looks identical in the catalog.
|
||||
2. Run `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;` outside a migration.
|
||||
3. Re-apply the index migration.
|
||||
3. If a migration built it, Flyway recorded that version as failed (`success = false`) and refuses
|
||||
every later deploy until that row is gone: dropping the index does not clear it. Follow
|
||||
[migration-failed.md](../runbooks/migration-failed.md) "Recover a failed concurrent index
|
||||
migration", which removes the cause and deletes that one row.
|
||||
4. Re-apply the index migration.
|
||||
|
||||
The platform does not drop these automatically: on a rolling deploy every instance would race to
|
||||
drop an index another instance was about to finish building.
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [MIGRATION_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-04
|
||||
last_updated: 2026-11-07
|
||||
status: active
|
||||
---
|
||||
|
||||
@@ -63,6 +63,13 @@ status: active
|
||||
case — clean it up with `outbox-dead-letter.md` §8 and rerun, the migration stays as it is;
|
||||
- checksum mismatch: compare the deployed artifact with the already applied script before
|
||||
considering repair;
|
||||
- a concurrent index migration failed (`CREATE [UNIQUE] INDEX CONCURRENTLY` or `REINDEX …
|
||||
CONCURRENTLY` that Flyway ran outside a transaction): a duplicate value for a unique
|
||||
index, a deadlock, `statement_timeout` or a cancelled build. Outside a transaction nothing
|
||||
rolled back: the migration left an invalid index and a history row with
|
||||
`success = false` for that version, and every later deploy fails validation ("Detected failed
|
||||
migration to version …") until the row is gone. Dropping the index alone does not clear it.
|
||||
Follow "Recover a failed concurrent index migration" below;
|
||||
- connection/TLS failure: fix transport or credentials without changing Flyway history.
|
||||
|
||||
## Action
|
||||
@@ -92,7 +99,9 @@ status: active
|
||||
Do not:
|
||||
|
||||
- edit an already applied migration;
|
||||
- delete or rewrite Flyway history to make validation green;
|
||||
- delete or rewrite Flyway history to make validation green. The one exception is the failed row
|
||||
of a failed concurrent index migration, deleted as "Recover a failed concurrent index migration"
|
||||
below says — that row and nothing else;
|
||||
- run `flyway repair` before checksum provenance is proven and reviewed;
|
||||
- use `clean`, destructive rollback, or schema-wide restore as the first response;
|
||||
- mark a capability `ACTIVE` before its migration and adapter readiness succeed.
|
||||
@@ -101,6 +110,57 @@ If commit outcome was indeterminate during the failure, reconcile by the applica
|
||||
`OperationId`/idempotency reference before retrying business work. Never blind-retry a commit whose
|
||||
result is unknown.
|
||||
|
||||
## Recover a failed concurrent index migration
|
||||
|
||||
The one case where this runbook changes Flyway history (owner decision, 2026-11-06). It applies to a
|
||||
migration that holds a single concurrent index statement which Flyway ran outside a transaction —
|
||||
with the `executeInTransaction=false` the guide asks for, or on its own for `CREATE`/`DROP INDEX
|
||||
CONCURRENTLY` (`docs/jpa/migration-guide.md` "Concurrent index builds") — and whose row for this
|
||||
version in the stream's history table says `success = false`. A migration that mixed other
|
||||
statements in has already committed them: reconstruct that state with the database owner instead.
|
||||
|
||||
1. Confirm no build is still running. An index that is still being built looks invalid in the
|
||||
catalog too, and dropping it races the build. This query returns no rows when none is:
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-builds -->
|
||||
```sql
|
||||
SELECT pid, relid::regclass AS table_name, index_relid::regclass AS index_name, phase
|
||||
FROM pg_stat_progress_create_index
|
||||
WHERE datname = current_database();
|
||||
```
|
||||
|
||||
2. Drop the invalid index the build left (`docs/jpa/runbooks.md` "An invalid index exists" lists
|
||||
them). Run it on its own, not inside `BEGIN`: `CONCURRENTLY` refuses a transaction block.
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-drop -->
|
||||
```sql
|
||||
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;
|
||||
```
|
||||
|
||||
3. Remove the cause. For a unique index, clean up the duplicate rows with the data owner (a forward
|
||||
fix, never by editing the migration). For a deadlock or a timeout, end or wait out the
|
||||
transaction that held the build.
|
||||
4. Delete that version's failed row from the stream's history table, and nothing else. `<version>`
|
||||
is the `version` column of the failed row as the Diagnosis query shows it (`22.1` for
|
||||
`V22_1__…`). It must delete exactly one row; if it deletes none, this is not the failure this
|
||||
section is for, so classify it again.
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-history-row -->
|
||||
```sql
|
||||
DELETE FROM <owned_history_table>
|
||||
WHERE version = '<version>' AND NOT success;
|
||||
```
|
||||
|
||||
5. Deploy again. Flyway runs the same migration from the start and builds the index.
|
||||
|
||||
The failed row is the record of a version that never applied, so deleting it leaves the order and
|
||||
the checksum of every applied version as they were. Do not use `flyway repair` for this: it also
|
||||
rewrites the checksums and descriptions of the remaining rows to match the scripts on disk, which
|
||||
removes the evidence a checksum mismatch carries. `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`
|
||||
runs the three SQL blocks above, read from this file, against real PostgreSQL: a unique build fails
|
||||
on a duplicate, steps 1–4 run, and the next deploy applies the version with the index valid and the
|
||||
earlier version's checksum unchanged.
|
||||
|
||||
## Escalation
|
||||
|
||||
- P1 immediate: the required application revision cannot become ready.
|
||||
|
||||
@@ -1337,15 +1337,22 @@ startup 동작으로는 절대 아니다.
|
||||
### 8.2 `ConcurrentIndexMigrationInspector`
|
||||
|
||||
PostgreSQL은 `CREATE INDEX CONCURRENTLY`·`DROP INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`를
|
||||
트랜잭션 블록 안에서 거부한다. Flyway 11은 `CREATE`/`DROP INDEX CONCURRENTLY`가 든 파일을 **스스로
|
||||
트랜잭션 밖에서** 돌린다. `REINDEX … CONCURRENTLY`는 모른다. 그 파일은 트랜잭션 안에서 돌고, 배포 때
|
||||
PostgreSQL이 거부한다. 그래서 검사기는 동시 인덱스 문장이 있으면 `.sql.conf`에
|
||||
`executeInTransaction=false`를 적으라고 요구한다. Flyway가 알아서 빼 주는 문장에도 적는다. 파일이
|
||||
자기에게 필요한 것을 스스로 말하게 하려는 것이다.
|
||||
트랜잭션 블록 안에서 거부한다. Flyway 11은 `CREATE`/`DROP INDEX CONCURRENTLY`나
|
||||
`REINDEX SCHEMA|DATABASE`(`CONCURRENTLY`가 있든 없든)가 든 파일을 **스스로 트랜잭션 밖에서** 돌린다.
|
||||
`REINDEX INDEX|TABLE … CONCURRENTLY`(`REINDEX (CONCURRENTLY) TABLE` 포함)는 모른다. 그 파일은
|
||||
트랜잭션 안에서 돌고, 배포 때 PostgreSQL이 거부한다. 다섯 형태를 실제 PostgreSQL에서 돌린 결과는
|
||||
`PostgreSqlMigrationLockWaitIntegrationTest`에 있다. 그래서 검사기는 동시 인덱스 문장이 있으면
|
||||
`.sql.conf`에 `executeInTransaction=false`를 적으라고 요구한다. Flyway가 알아서 빼 주는 문장에도
|
||||
적는다. 파일이 자기에게 필요한 것을 스스로 말하게 하려는 것이다.
|
||||
|
||||
> 다른 문장과 섞인 파일은 Flyway가 기본값(`mixed=false`)에서 **아무것도 실행하기 전에 거부**한다.
|
||||
> 부분 적용은 일어나지 않는다. 그래도 한 파일에 하나만 두는 이유는 아래 `requireIsolatedStatement`의
|
||||
> 복구 때문이다.
|
||||
> 다른 문장과 섞인 파일은 설정에 따라 결과가 다르다.
|
||||
>
|
||||
> - `.sql.conf`가 없으면 Flyway가 기본값(`mixed=false`)에서 **아무것도 실행하기 전에 거부**한다.
|
||||
> - 검사기가 요구하는 `executeInTransaction=false`를 붙이면 Flyway가 **문장마다 따로 커밋**한다.
|
||||
> 동시 빌드가 실패해도 그 앞 문장은 **이미 적용돼 남는다**(부분 적용).
|
||||
>
|
||||
> 그래서 동시 인덱스 문장은 한 파일에 하나만 둔다. 두 경우 모두
|
||||
> `PostgreSqlConcurrentIndexMigrationIntegrationTest`가 실제 PostgreSQL에서 보여 준다.
|
||||
|
||||
트랜잭션 밖에서도 동시 빌드는 **자기보다 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다.**
|
||||
|
||||
@@ -1366,18 +1373,32 @@ Flyway 기본값: 잠금 트랜잭션(열린 채) ──기다림──▶ 마
|
||||
검사 대상: `CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`
|
||||
(`REINDEX (CONCURRENTLY) TABLE` 같은 괄호 옵션 포함).
|
||||
|
||||
`requireIsolatedStatement`도 있다 — concurrent 빌드가 실패하면 invalid index가 남고, 그
|
||||
복구는 마이그레이션이 다른 걸 아무것도 안 했으면 `DROP INDEX` 하나지만 뭔가 했으면 부분
|
||||
상태를 손으로 재구성해야 한다.
|
||||
`requireIsolatedStatement`도 있다 — concurrent 빌드가 실패하면 invalid index와 그 버전의
|
||||
**실패 이력 행**(`success = false`)이 남는다. Flyway는 그 행이 있는 한 다음 배포를 validate에서 거부한다.
|
||||
그래서 인덱스만 지우고 다시 배포하면 또 멈춘다.
|
||||
|
||||
`FailedConcurrentIndexRecovery`가 `pg_index.indisvalid = false`를 조회해서 리포트한다.
|
||||
**자동으로 지우지 않는다.**
|
||||
```
|
||||
실패한 동시 빌드 → invalid index + 실패 이력 행
|
||||
→ 빌드가 아직 도는지 확인 → DROP INDEX CONCURRENTLY → 원인 정리(중복 행 등)
|
||||
→ 그 버전의 실패 이력 행만 DELETE → 다시 배포
|
||||
```
|
||||
|
||||
- 절차와 SQL은 `docs/runbooks/migration-failed.md` "Recover a failed concurrent index migration"에 있다.
|
||||
`PostgreSqlConcurrentIndexMigrationIntegrationTest`가 그 SQL을 runbook에서 읽어 실제 PostgreSQL에서 돌린다.
|
||||
- 실패 이력 행을 지우는 것은 "이력을 고치지 않는다"의 하나뿐인 예외다(소유자 결정 2026-11-06).
|
||||
실패 행은 적용되지 않은 버전의 기록이라, 지워도 성공한 버전의 순서와 checksum은 그대로다.
|
||||
- `flyway repair`는 여전히 쓰지 않는다. 남은 행의 checksum·설명까지 디스크의 스크립트에 맞춰 다시 쓰기 때문이다.
|
||||
- 마이그레이션이 다른 문장도 담고 있었으면 그 문장은 이미 커밋돼 있다. 부분 상태를 손으로 재구성해야 한다.
|
||||
|
||||
invalid index를 찾는 쿼리는 `docs/jpa/runbooks.md` "An invalid index exists"에 있다(예전의
|
||||
`FailedConcurrentIndexRecovery` 클래스는 호출자가 없어 지웠고, 이 쿼리가 대신한다).
|
||||
플랫폼은 invalid index를 **자동으로 지우지 않는다.**
|
||||
|
||||
> invalid index는 **빌드가 아직 돌고 있다**는 뜻일 수도 있고, 카탈로그만으로는 둘을 구별할 수
|
||||
> 없다. 자동 drop은 곧 끝나려던 concurrent 빌드와 경주하게 되고, rolling deploy의 모든
|
||||
> 인스턴스에서 동시에 그렇게 한다.
|
||||
|
||||
리포트는 운영자가 돌릴 statement를 준다(그 자체가 non-transactional인 `DROP INDEX CONCURRENTLY`).
|
||||
지우는 문장은 운영자가 직접 돌린다(그 자체가 트랜잭션 밖에서만 도는 `DROP INDEX CONCURRENTLY`).
|
||||
|
||||
### 8.3 실제 마이그레이션 트리 — 8개 독립 스트림
|
||||
|
||||
|
||||
@@ -155,6 +155,9 @@
|
||||
`GRANT … REFERENCES ON`과 `REINDEX (CONCURRENTLY) …`는 더 이상 거부하지 않는다. 자기 스트림 검사가 새로 실패하면 그 파일은
|
||||
Flyway가 거부하거나(`mixed=false`) 상한 없이 도는(`mixed=true`) 파일이다. 아직 배포 전이면 문장을 나누고, 이미 배포했으면
|
||||
규칙 이전 목록에 더한다(r9, 재리뷰 RR4-02-01).
|
||||
재리뷰 round7(RR7-03-05) 수정부터는 `.sql.conf`가 `executeInTransaction=true`를 정한 파일의 `VACUUM FULL`·비동시
|
||||
`REINDEX SCHEMA|DATABASE|SYSTEM`도 앞의 `SET LOCAL`과 상관없이 같은 이유로 거부한다. 그런 파일은 PostgreSQL이 배포 때
|
||||
`25001`로 거부하므로 배포된 적이 없다. 새로 걸리면 그 문장을 마이그레이션에서 빼 운영 절차로 옮긴다.
|
||||
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은
|
||||
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
|
||||
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
|
||||
@@ -245,6 +248,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
|
||||
| 서버 로그(GraphQL·gRPC·STOMP) | carrier로 답한 실패를 web과 같은 줄(shared-contract `ServerFailureLog`)로 ERROR에 남긴다: persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. gRPC는 ` (method=…)`, GraphQL은 ` (executionId=…)`를 붙인다. gRPC는 인식 못 한 실패(`INTERNAL_ERROR`)도 `unhandled failure on <method> …`로 남긴다. 클라이언트가 취소한 호출은 남기지 않고, 서비스가 `CANCELLED` status로 끝낸 살아 있는 호출은 남긴다. raw status는 넘겼든 던졌든 설명을 남기지 않는다(원인 예외가 있으면 그것만 붙인다). `IllegalArgumentException`(`BAD_PARAMETER`)은 web과 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입>`(메시지 없음)으로 남긴다. STOMP `@MessageMapping` 실패는 Spring의 `Unhandled exception from message handler method`(예외 전체) 대신 같은 줄로 남는다 | ERROR 로그가 늘어난다(전에는 gRPC가 아무것도 남기지 않았다). GraphQL·gRPC·STOMP는 잘못된 입력마다 WARN 한 줄이 생긴다. STOMP에서 Spring 문구로 경보를 걸었다면 고친다. `IDEMPOTENCY_RECOVERY_REQUIRED`의 scope digest를 모든 전송에서 찾을 수 있다(`docs/runbooks/idempotency-unavailable.md`) | r9 · `src/shared-contract/.../error/ServerFailureLog.java`, `GrpcExceptionHandlingInterceptor.java`, `GraphQlWireErrorMapper.java`, `StompHandlerFailureLog.java` |
|
||||
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
|
||||
| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" |
|
||||
| 실패한 동시 인덱스 마이그레이션 복구 | `docs/runbooks/migration-failed.md`에 「Recover a failed concurrent index migration」을 더했다: 진행 중인 빌드가 없는지 보고, 무효 인덱스를 `DROP INDEX CONCURRENTLY`로 지우고, 원인을 정리하고, 그 버전의 실패 이력 행(`success = false`)만 지운 뒤 다시 배포한다. 「Do not」의 이력 수정 금지에 이 한 가지 예외를 적었다. `flyway repair`는 계속 쓰지 않는다 | 전에는 안내가 "`DROP INDEX` 하나"였고, 그대로 하면 남은 실패 이력 때문에 다음 배포가 validate에서 다시 멈췄다. 동시 인덱스 마이그레이션을 쓰는 서비스의 운영자는 이 절차로 복구한다 | 재리뷰 round7 RR7-03-03, 소유자 결정 2026-11-06 · `docs/jpa/migration-guide.md` "Concurrent index builds", `PostgreSqlConcurrentIndexMigrationIntegrationTest` |
|
||||
| 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` |
|
||||
| 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user