donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/official-docs/migration-flyway-official-concepts-and-repair.md
T

12 KiB
Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
Flyway — Concepts, Repair, and baseline_on_migrate / out_of_order official-doc https://documentation.red-gate.com/flyway/flyway-concepts raw high
ca-skeleton
migration
startup
flyway
schema
official-doc
ca-skeleton-operational-contract
feature-migration-startup-contract
feature-runtime-health-lifecycle-contract
2026-05-22 2026-05-27

Flyway — Concepts, Repair, and baseline_on_migrate / out_of_order

Layer: raw/official-docs/ — Flyway 공식 문서 (Redgate maintained) 원문 발췌. ca-tmpl feature-migration-startup-contract 의 "Flyway app startup runner default + prod 에서 flyway.repair forbidden + baseline_on_migrate/out_of_order 기본 false" 결정의 1차 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-migration-startup-contract Flyway = ca-tmpl Group G-D 채택안 (baseline). schema history table 기반 audit trail + 위험 옵션 (outOfOrder, baselineOnMigrate) 기본 false 결정 근거
raw/branch-notes/feature-runtime-health-lifecycle-contract migration 완료 전 readiness healthy 금지 — schema history 가 "applied" 로 기록되기 전에는 app 이 traffic 을 받지 않아야 한다는 결정 근거

또한 다음 project hub 에서도 인용:

컨텍스트 / 왜 저장했는지

ca-tmpl feature-migration-startup-contract의 기본 결정 — Flyway app startup runner default + prod에서 flyway.repair forbidden + baseline_on_migrate/out_of_order 기본 false. 본 source는 그 결정의 외부 근거.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§Flyway Schema History Table — purpose] "To keep track of which migrations have already been applied when and by whom, Flyway adds a special schema history table to your schema."

[§Migrations — change detection] "It will compare them to the migrations that have been applied to the database. If any difference is found, it will migrate the database to close the gap."

[§Migrations — error handling] "In case an error is returned Flyway displays it with all necessary details, marks the migration as failed and automatically rolls it back if possible."

[§Repair command — core functions] "Remove any failed migrations (User objects left behind must still be cleaned up manually)" / "Realign the checksums, descriptions and types of the applied migrations with the ones of the available migrations" / "Mark all missing migrations as deleted"

[§Repair command — locations constraint] "As a result, repair must be given the same locations as migrate!"

[§outOfOrder setting — description + default] "Allows migrations to be run 'out of order'. If you already have versions 1.0 and 3.0 applied, and now a version 2.0 is found, it will be applied too instead of being ignored." / Default: "false"

[§baselineOnMigrate setting — description + warning] "Whether to automatically call baseline when migrate is executed against a non-empty schema with no schema history table." / "Be careful when enabling this as it removes the safety net that ensures Flyway does not migrate the wrong database in case of a configuration mistake!"

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
FLYWAY-C1 Flyway 는 적용된 migration 을 추적하기 위해 schema 에 schema history table 을 추가하며, 이것이 "언제 누구에 의해" 적용되었는지의 audit trail 역할을 한다 [§Schema History Table] "To keep track of which migrations have already been applied when and by whom, Flyway adds a special schema history table to your schema." official-vendor-doc Flyway 가 관리하는 모든 DB schema table 이름이 모든 환경에서 항상 flyway_schema_history 라는 hard-coded 사실은 아님 — table setting 으로 변경 가능
FLYWAY-C2 Flyway 는 available migrations 와 applied migrations 를 비교하여 차이가 있으면 그 차이를 메우기 위해 migrate 한다 (= "어떤 migration 을 다음에 적용할지" 결정 메커니즘) [§Migrations] "It will compare them to the migrations that have been applied to the database. If any difference is found, it will migrate the database to close the gap." official-vendor-doc Flyway migrate 명령 일반 동작 applied migration 의 checksum 변경 감지가 자동 차단으로 이어진다는 구체 동작까지는 본 인용에 없음 (validate 명령은 별도)
FLYWAY-C3 repair 는 (a) 실패한 migration 을 schema history 에서 제거하고, (b) applied migration 의 checksum/description/type 을 현재 file 들의 값과 재정렬하며, (c) 사라진 migration 을 "deleted" 로 표시한다 [§Repair command] "Remove any failed migrations (User objects left behind must still be cleaned up manually)" / "Realign the checksums, descriptions and types of the applied migrations with the ones of the available migrations" / "Mark all missing migrations as deleted" official-vendor-doc Flyway 가 관리하는 모든 DB schema 에 대한 repair 명령 "prod 에서 절대 쓰면 안 된다" 라는 직접적인 금지 문구는 본 인용에 없음 — User objects 수동 정리 책임만 명시. ca-tmpl 의 prod-forbidden 결정은 audit trail tampering 우려에 기반한 운영 정책 (별도 정당화)
FLYWAY-C4 repair 는 migrate 와 동일한 locations 로 실행되어야 한다 (그렇지 않으면 정상 동작 보장 안 됨) [§Repair command] "As a result, repair must be given the same locations as migrate!" official-vendor-doc Flyway repair 명령 실행 시 locations 외 다른 옵션 (placeholder, encoding 등) 의 일치 의무까지는 본 인용에 없음
FLYWAY-C5 outOfOrder 의 default 는 false. true 로 설정 시 이미 1.0/3.0 이 applied 된 상태에서 2.0 이 발견되면 ignored 되지 않고 적용된다 [§outOfOrder setting] "Allows migrations to be run 'out of order'." + "If you already have versions 1.0 and 3.0 applied, and now a version 2.0 is found, it will be applied too instead of being ignored." + Default: "false" official-vendor-doc Flyway outOfOrder 설정 일반 "out-of-order = inconsistent history in production" 같은 운영 결론은 본 인용에 없음 — 동작 정의만. ca-tmpl 의 "prod 금지" 결정은 운영 해석
FLYWAY-C6 baselineOnMigrate 는 schema history table 이 없는 non-empty schema 에 migrate 가 실행될 때 자동으로 baseline 을 호출하는 설정이며, 활성화 시 "잘못된 DB 를 migrate 하지 않게 해주는 safety net 이 제거됨" — 공식 경고 [§baselineOnMigrate setting] "Whether to automatically call baseline when migrate is executed against a non-empty schema with no schema history table." + "Be careful when enabling this as it removes the safety net that ensures Flyway does not migrate the wrong database in case of a configuration mistake!" official-vendor-doc Flyway baselineOnMigrate 설정 "production 에서 schema drift 를 mask 한다" 같은 구체적 위협 모델은 본 인용에 명시 없음 — 일반적인 "configuration mistake → wrong database" 경고. ca-tmpl 의 "drift detection 실패" 해석은 운영적 일반화

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • FLYWAY-C1: schema history table 의 존재와 audit-trail 역할
    • FLYWAY-C2: applied vs available 비교 메커니즘
    • FLYWAY-C3/C4: repair 의 정확한 3가지 동작 + locations 일치 의무
    • FLYWAY-C5: outOfOrder default false + 정확한 동작 정의
    • FLYWAY-C6: baselineOnMigrate 의 동작 + 공식 "safety net 제거" 경고
  • 이 자료가 증명하지 않는 것:
    • "prod 에서 repair 절대 금지" 라는 공식 정책 (본 페이지의 경고는 "User objects 수동 정리" 수준에 한정. ca-tmpl 의 prod-forbidden 결정은 운영 정책)
    • outOfOrder=true 가 prod 에서 "inconsistent history" 를 일으킨다는 직접 진술 (동작 정의만 있음)
    • baselineOnMigrate=true 가 "silent 하게 schema drift 를 mask 한다" 는 구체적 위협 모델 (공식 경고는 "wrong database migrate" 일반 케이스)
    • Spring Boot auto-configuration 의 정확한 통합 방식 (별도 Spring Boot reference 참조)
    • multi-instance startup race 에서 Flyway lock 의 정확한 동작 (별도 lock 문서 참조)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • ca-tmpl 의 "prod repair forbidden" 운영 정책이 본 공식 문서의 어떤 조항을 어떻게 운영적으로 해석한 것인지 명문화 (audit trail 무결성 관점)
    • baselineOnMigrate 의 default 가 Spring Boot 환경에서도 false 인지 (Spring Boot 가 override 하지 않는지 확인)
    • multi-instance 환경에서 schema lock 의 timeout/deadlock 거동 (별도 lock 문서 + 실측 필요)
    • URL 변경 이력 (/fd/ → /flyway/) 으로 인한 stale link 점검을 정기 lint 항목에 포함할지

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

  • 적용 시나리오: schema migration이 application 코드와 함께 deploy되는 환경 (대다수의 Spring Boot 앱).
  • 장점:
    • SQL 그대로 migration 작성 가능 (low cognitive load).
    • schema history table 모델이 단순하고 검증된 패턴.
    • Spring Boot auto-configuration이 spring-boot-starter-data-jpa 등과 통합.
  • 단점:
    • repair는 prod에서 사용 시 schema history를 임의 조작 → audit trail 손상. ca-tmpl이 forbidden 처리한 이유.
    • baseline_on_migrate=true는 silent하게 "이 schema는 untracked이다"를 허용 → drift detection 실패. ca-tmpl이 default false인 이유.
    • out_of_order=true는 dev에서는 편하지만 prod에서는 migration history가 일관되지 않게 됨.
    • app startup runner는 multi-instance startup race를 일으킬 수 있음 (ca-tmpl이 별도 migration lock / one-shot job 요구).
  • ca-tmpl과의 일치점:
    • prod Flyway repair 금지, non-prod 한정 허용 + audit log 필수.
    • baseline_on_migrate, out_of_order 기본 false.
    • migration 완료 전 readiness healthy 금지.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink