Files
clean-architecture-backend-…/docs/runbooks/migration-failed.md
T
DongHyeonka a81e92faca docs(runbooks): runbook을 한국어로 옮기고 상태를 초안·운영으로 바꾼다
문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.

고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
  lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
  머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
  - adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
    `failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
    곳은 `RoutingNotifier`뿐이다.
  - startup-required-adapter-disabled: `startup.phase=adapter-check` →
    `adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
  - cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
    그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
  - db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
    → `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
  - dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
    (`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
  - management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
    (`config/observability.yml`).
  - runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
    경로(`src/Dockerfile`)를 적었다.
  - auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
  - grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
    `GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
  - grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
  migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
  쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
  밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.

버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.

위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
  `-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.

검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.

검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
  `:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
  `postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
  `postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
  rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
  `:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
  `everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
2026-11-07 17:56:34 +09:00

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
MIGRATION_FAILED
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가 아니다.

진단

  1. rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지 않는다.

  2. src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml에서 정확한 stream을 찾는다. stream마다 location과 history-table이 따로 있다. 넓은 classpath:db/migration 스캔으로 소유를 짐작하지 않는다.

  3. 권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 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>';
    
  4. 성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만 비교한다. 상관없는 relation은 지우지 않는다.

  5. 실패를 분류한다(Classify the failure).

    • 락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는 마이그레이션은 자기 SET LOCAL lock_timeout(5 s, SQLState 55P03 lock_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 이력을 바꾸지 않고 전송이나 자격 증명을 고친다.

조치

  1. forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을 그 정확한 이력 테이블로 다시 돌린다.

  2. 한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임 어댑터를 꺼 둔다.

  3. 마이그레이션이 성공하면 확인한다.

    • 이력에 기대한 버전의 성공 행만 있다.
    • core_epoch와 feature_revision이 readiness registry와 같다.
    • 표시가 INSTALLED_INACTIVE다.
    • 소유 객체와 제약이 있다.
  4. 맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를 ACTIVE로 바꾼다. 애플리케이션 코드를 끄거나 되돌리면 표시가 INSTALLED_INACTIVE로 바뀐다. 이력이나 소유 데이터는 지우지 않는다.

  5. 승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음).

    cd src
    ./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain
    
  6. 실패한 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 소유자와 함께 다시 맞춘다.

  1. 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면 빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다.
SELECT pid, relid::regclass AS table_name, index_relid::regclass AS index_name, phase
FROM pg_stat_progress_create_index
WHERE datname = current_database();
  1. 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지 않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는 자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에 한다. 3단계의 DROP INDEX CONCURRENTLY도 같은 트랜잭션을 기다린다.
  2. 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다. 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>;
  1. stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다. <version>은 진단 쿼리가 보여 주는 실패 행의 version 칸이다(V22_1__…이면 22.1). 정확히 한 행을 지워야 한다. 한 행도 지우지 않으면 이 절이 다루는 실패가 아니므로 다시 분류한다.
DELETE FROM <owned_history_table>
WHERE version = '<version>' AND NOT success;
  1. 다시 배포한다. 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 결과다.