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:
DongHyeonka
2026-11-07 01:14:09 +09:00
parent 73d39212f5
commit 6ec0c4f7fa
18 changed files with 587 additions and 95 deletions
+35 -11
View File
@@ -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
+5 -1
View File
@@ -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.
+62 -2
View File
@@ -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.
+35 -14
View File
@@ -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개 독립 스트림
+4
View File
@@ -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` |