문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
11 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |
|---|---|---|---|---|---|---|---|
| Runbook — MIGRATION_FAILED (DB 마이그레이션 실패) | INTERNAL |
|
P1 | oncall | 2026-11-07 | 운영 |
Runbook: MIGRATION_FAILED (runbook://migration/failed)
증상
- 컨테이너가 코드 70으로 끝난다(마이그레이션 실패 종료).
- 구조화 로그
error.code=MIGRATION_FAILED,startup.phase=migration. - 앱이 뜨기를 거부한다(fail-fast).
- JPA capability 어댑터가 활성화를 거부한다. 그
capability_schema_registry.lifecycle_state가ACTIVE가 아니다.
진단
-
rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지 않는다.
-
src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml에서 정확한 stream을 찾는다. stream마다location과history-table이 따로 있다. 넓은classpath:db/migration스캔으로 소유를 짐작하지 않는다. -
권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 stream 상태를 남긴다.
select installed_rank, version, description, success from <owned_history_table> order by installed_rank; select capability_id, installation_origin, core_epoch, feature_revision, lifecycle_state from capability_schema_registry where capability_id = '<card-id>'; -
성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만 비교한다. 상관없는 relation은 지우지 않는다.
-
실패를 분류한다(Classify the failure).
-
락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는 마이그레이션은 자기
SET LOCAL lock_timeout(5 s, SQLState55P03lock_not_available)이 지나면 포기하고 통째로 롤백한다. 그래서 이력은 그 버전 바로 아래에서 끝난다. 막는 쪽은 그 테이블을 건드린 뒤 아직 열려 있는 트랜잭션이다. 흔히 idle-in-transaction 세션이다. 그 테이블에 쥔 락으로 찾는다(<table>은 실패한 문장이 잠그는 테이블이다.REFERENCES면 참조하는 테이블도 본다).SELECT DISTINCT a.pid, a.state, a.xact_start, a.query FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE l.relation = '<table>'::regclass AND l.granted AND a.pid <> pg_backend_pid() ORDER BY a.xact_start;query는 그 세션의 마지막 문장일 뿐 테이블을 건드린 문장이 아니므로, 거기서 테이블 이름을 찾지 않는다. 대신 긴 트랜잭션을 모두 나열하면 막는 쪽 옆에 상관없는 것(리포트, 배치)도 나온다. 막는 쪽을 끝낸 뒤 다시 돌린다(docs/jpa/migration-guide.md"Bound the lock wait"). -
SQL·데이터 전제 조건: 전제 조건을 드러내는 새 forward 마이그레이션을 만든다. 중복된 outbox 순서 키가 V21(
ux_outbox_event_aggregate_order)을 막는 것이 알려진 경우다.outbox-dead-letter.md§8로 정리하고 다시 돌린다. 마이그레이션은 그대로 둔다. -
checksum 불일치: repair를 생각하기 전에 배포한 산출물과 이미 적용된 스크립트를 비교한다.
-
동시 인덱스 마이그레이션 실패(Flyway가 트랜잭션 밖에서 돌린
CREATE [UNIQUE] INDEX CONCURRENTLY,DROP INDEX CONCURRENTLY,REINDEX … CONCURRENTLY): unique 인덱스의 중복 값, 교착,statement_timeout, 또는 열린 트랜잭션을 기다리다 취소된 문장이다. 트랜잭션 밖이라 아무것도 롤백되지 않았다. 마이그레이션은 무효 인덱스와, 그 버전의success = false이력 행을 남겼다. 그 행이 사라질 때까지 뒤의 배포는 모두 검증에서 실패한다("Detected failed migration to version …"). 인덱스만 지워서는 풀리지 않는다. 아래 「실패한 동시 인덱스 마이그레이션 복구」를 따른다. -
연결·TLS 실패: Flyway 이력을 바꾸지 않고 전송이나 자격 증명을 고친다.
-
조치
-
forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을 그 정확한 이력 테이블로 다시 돌린다.
-
한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임 어댑터를 꺼 둔다.
-
마이그레이션이 성공하면 확인한다.
- 이력에 기대한 버전의 성공 행만 있다.
core_epoch와feature_revision이 readiness registry와 같다.- 표시가
INSTALLED_INACTIVE다. - 소유 객체와 제약이 있다.
-
맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를
ACTIVE로 바꾼다. 애플리케이션 코드를 끄거나 되돌리면 표시가INSTALLED_INACTIVE로 바뀐다. 이력이나 소유 데이터는 지우지 않는다. -
승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음).
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain -
실패한 revision, stream·이력 테이블, 근본 원인, 복구 마이그레이션, 걸린 시간, 검증 산출물을 장애 기록에 남긴다.
하지 않을 것:
- 이미 적용된 마이그레이션을 고친다.
- 검증을 통과시키려고 Flyway 이력을 지우거나 다시 쓴다. 예외는 하나다. 실패한 동시 인덱스 마이그레이션의 실패 행을 아래 「실패한 동시 인덱스 마이그레이션 복구」대로 지운다. 그 행 말고는 아무것도 지우지 않는다.
- checksum의 출처가 증명되고 검토되기 전에
flyway repair를 돌린다. - 첫 대응으로
clean, 파괴적 롤백, 스키마 전체 복원을 쓴다. - 마이그레이션과 어댑터 readiness가 성공하기 전에 capability를
ACTIVE로 표시한다.
장애 중에 커밋 결과를 알 수 없었으면, 업무 작업을 다시 하기 전에 애플리케이션의 OperationId·멱등성 참조로
맞춘다. 결과를 모르는 커밋을 그냥 다시 시도하지 않는다.
실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)
이 runbook이 Flyway 이력을 바꾸는 유일한 경우다(소유자 결정, 2026-11-06). Flyway가 트랜잭션 밖에서 돌린 동시
인덱스 문장 하나만 담은 마이그레이션에 쓴다. 가이드가 요구하는 executeInTransaction=false로 돌렸거나,
CREATE/DROP INDEX CONCURRENTLY라서 Flyway가 알아서 그렇게 돌린 경우다(docs/jpa/migration-guide.md
"Concurrent index builds"). 그리고 stream 이력 테이블의 이 버전 행이 success = false여야 한다. 다른 문장을 섞은
마이그레이션은 그 문장을 이미 커밋했다. 그 상태는 DB 소유자와 함께 다시 맞춘다.
- 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면 빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다.
SELECT pid, relid::regclass AS table_name, index_relid::regclass AS index_name, phase
FROM pg_stat_progress_create_index
WHERE datname = current_database();
- 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지
않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는
자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에
한다. 3단계의
DROP INDEX CONCURRENTLY도 같은 트랜잭션을 기다린다. - 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다.
CREATE [UNIQUE] INDEX CONCURRENTLY가 이름 붙인 인덱스, 또는REINDEX … CONCURRENTLY가 만든 사본이다. 사본은 인덱스 이름 끝에_ccnew(또는_ccold)가 붙는다 (docs/jpa/runbooks.md"An invalid index exists"가 그 목록을 준다).BEGIN안이 아니라 따로 돌린다.CONCURRENTLY는 트랜잭션 블록을 거부한다. 실패한 문장이DROP INDEX CONCURRENTLY면 이 단계를 건너뛴다. 그것이 남긴 무효 인덱스는 마이그레이션이 지우는 인덱스이고, 5단계의 배포가 같은 문장을 돌려 그것을 지운다. 먼저 손으로 지우면 그 문장이42704("index … does not exist")로 실패하고 새 실패 행을 남긴다.
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;
- stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다.
<version>은 진단 쿼리가 보여 주는 실패 행의version칸이다(V22_1__…이면22.1). 정확히 한 행을 지워야 한다. 한 행도 지우지 않으면 이 절이 다루는 실패가 아니므로 다시 분류한다.
DELETE FROM <owned_history_table>
WHERE version = '<version>' AND NOT success;
- 다시 배포한다. Flyway가 같은 마이그레이션을 처음부터 돌린다. 인덱스를 만들거나, 다시 만들거나, 실패한 삭제가 남긴 인덱스를 지운다.
실패 행은 한 번도 적용되지 않은 버전의 기록이다. 그래서 지워도 적용된 모든 버전의 순서와 checksum은 그대로다.
이 일에 flyway repair를 쓰지 않는다. repair는 남은 행의 checksum과 description도 디스크의 스크립트에 맞춰 다시
쓰므로, checksum 불일치가 담은 증거를 지운다.
:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest가 위의 SQL 블록 셋을 이
파일에서 읽어, 이 절이 다루는 문장마다 실제 PostgreSQL에 돌린다. 중복으로 실패하는 unique 빌드, 열린 트랜잭션을
기다리다 취소된 재빌드와 삭제다. 1~4단계를 차례로 돌리고(3단계는 빌드와 재빌드만), 다음 배포가 무효 인덱스 없이
그 버전을 적용하며 앞 버전의 checksum은 바뀌지 않는다.
에스컬레이션
- P1 즉시: 필요한 애플리케이션 revision이 ready가 되지 못한다.
- Flyway 이력 repair, 파괴적 DDL, 시점 복구(PITR), primary failover 전에 DB 소유자에게 넘긴다.
- R3 복원·PITR과 failover 예행연습에는 대상과 비슷한 백업 구성이 필요하다. 로컬 Testcontainers 증거로 대신하지 않는다.
이 runbook은 forward 방향만 다룬다. 감사 근거는 검토한 마이그레이션 산출물과 CI의 readiness lane JUnit 결과다.