fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다

문제: 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 패키지 규칙이 실제로 검사한다.
This commit is contained in:
DongHyeonka
2026-11-05 20:37:55 +09:00
parent 45d2a478b8
commit 2c692554cb
97 changed files with 5152 additions and 934 deletions
+34 -10
View File
@@ -1336,15 +1336,35 @@ startup 동작으로는 절대 아니다.
### 8.2 `ConcurrentIndexMigrationInspector`
PostgreSQL은 `CREATE INDEX CONCURRENTLY`를 트랜잭션 블록 안에서 아예 거부하고, Flyway는
기본적으로 마이그레이션을 트랜잭션으로 감싼다. **그래서 첫 배포에서 실패하는데, 그게 좋은
경우다.**
PostgreSQL은 `CREATE INDEX CONCURRENTLY`·`DROP INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`를
트랜잭션 블록 안에서 거부한다. Flyway 11은 `CREATE`/`DROP INDEX CONCURRENTLY`가 든 파일을 **스스로
트랜잭션 밖에서** 돌린다. `REINDEX … CONCURRENTLY`는 모른다. 그 파일은 트랜잭션 안에서 돌고, 배포 때
PostgreSQL이 거부한다. 그래서 검사기는 동시 인덱스 문장이 있으면 `.sql.conf`에
`executeInTransaction=false`를 적으라고 요구한다. Flyway가 알아서 빼 주는 문장에도 적는다. 파일이
자기에게 필요한 것을 스스로 말하게 하려는 것이다.
> 나쁜 경우는 다른 statement와 섞인 마이그레이션이다: 그것들은 커밋되고, concurrent index는
> 안 되고, 스키마는 **history row가 반대로 말하는 채로 부분 마이그레이션 상태로 남는다.**
> 다른 문장과 섞인 파일은 Flyway가 기본값(`mixed=false`)에서 **아무것도 실행하기 전에 거부**한다.
> 부분 적용은 일어나지 않는다. 그래도 한 파일에 하나만 두는 이유는 아래 `requireIsolatedStatement`의
> 복구 때문이다.
검사 대상: `create index concurrently`, `drop index concurrently`, `reindex index concurrently`,
`reindex table concurrently`, `reindex concurrently`.
트랜잭션 밖에서도 동시 빌드는 **자기보다 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다.**
```
Flyway 기본값: 잠금 트랜잭션(열린 채) ──기다림──▶ 마이그레이션 끝
▲ │
└──────── CIC가 기다림 ◀───────────┘ → 배포가 끝나지 않는다
```
- Flyway는 기본으로 마이그레이션 잠금(PostgreSQL advisory lock)을 트랜잭션 안에 두고, 실행 내내 그
트랜잭션을 열어 둔다.
- CIC는 그 트랜잭션도 기다린다. Flyway는 CIC가 끝나기를 기다린다. 오류도 시간 제한도 없다.
- 템플릿은 잠금을 세션에 둔다. Spring Boot의 Flyway는 module-defaults의
`spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway는
`FlywaySchemaPolicy.configure()`로 받는다. 배포 마이그레이션 도구도 같은 값이어야 한다
(`docs/jpa/migration-guide.md` "Who may change the schema").
검사 대상: `CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`
(`REINDEX (CONCURRENTLY) TABLE` 같은 괄호 옵션 포함).
`requireIsolatedStatement`도 있다 — concurrent 빌드가 실패하면 invalid index가 남고, 그
복구는 마이그레이션이 다른 걸 아무것도 안 했으면 `DROP INDEX` 하나지만 뭔가 했으면 부분
@@ -1700,15 +1720,19 @@ inserted == 1 → Acquired
COMPLETED이고 replay_until 지남 → resetClaim → TakenOverClaimed
request_hash 불일치 → FingerprintMismatch
COMPLETED이고 replay_until 있음 → CompletedReplay(payload, replayUntil)
같은 claim attempt(token+operationId) → ReplayedAcquire
같은 token, 다른 operationId → OwnerOperationConflict
ABANDONED → RecoveryRequired
CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed
FAILED_RETRYABLE → resetClaim → TakenOverClaimed
같은 claim attempt(token+operationId) → ReplayedAcquire
같은 token, 다른 operationId → OwnerOperationConflict
EXECUTING이고 lease 만료 → RecoveryRequired (행은 그대로)
ABANDONED → RecoveryRequired
그 외 → InProgress(retryAfter, attempt)
```
넘겨받기 두 줄이 같은 attempt의 재생보다 앞이다. 시작을 거절당했거나 재시도 가능 실패로 끝난 attempt가
같은 attempt로 다시 오면 재생이 아니라 넘겨받기다. 재생하면 시작할 수 없는 claim을 돌려줘 기록이 사라질
때까지 막혔다(라운드6 RR6-02-01, Redis CLAIM도 같은 순서).
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 reconciliation을 요구하되 행은 바꾸지
않는다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. 행을 그대로 두는 이유는 주인이 아직
돌고 있을 수 있어서다. 주인이 늦게 끝나면 그 결과가 기록되고 다음 claim이 재생한다(2026-11-04 소유자