125 lines
12 KiB
Markdown
125 lines
12 KiB
Markdown
---
|
|
title: "Flyway — Concepts, Repair, and baseline_on_migrate / out_of_order"
|
|
source_type: official-doc
|
|
url: https://documentation.red-gate.com/flyway/flyway-concepts
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-skeleton, migration, startup, flyway, schema, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-migration-startup-contract, feature-runtime-health-lifecycle-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 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 에서도 인용:
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — migration startup canonical section
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl `feature-migration-startup-contract`의 기본 결정 — **Flyway app startup runner default + prod에서 `flyway.repair` forbidden + `baseline_on_migrate`/`out_of_order` 기본 false**. 본 source는 그 결정의 외부 근거.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL (현행): https://documentation.red-gate.com/flyway/flyway-concepts
|
|
- 보조 URL (현행):
|
|
- https://documentation.red-gate.com/flyway/flyway-concepts/migrations/flyway-schema-history-table
|
|
- https://documentation.red-gate.com/flyway/reference/commands/repair
|
|
- https://documentation.red-gate.com/flyway/reference/configuration/flyway-namespace/flyway-out-of-order-setting
|
|
- https://documentation.red-gate.com/flyway/reference/configuration/flyway-namespace/flyway-baseline-on-migrate-setting
|
|
- 이전 URL (404, 2026-05-27 확인): https://documentation.red-gate.com/fd/concepts-184127422.html → Redgate 가 `/fd/` 경로를 `/flyway/` 로 리디렉션. 인용 문구는 현행 페이지에서 재확인.
|
|
- 저자/조직: Flyway / Redgate
|
|
- 발행일: Flyway 10.x reference (current)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / 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 / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/migration-liquibase-official-changelog-xml-yaml]] — Group G-D 대안 2 (Liquibase)
|
|
- [[raw/official-docs/migration-atlas-schema-as-code]] — Group G-D 대안 4 (Atlas, schema-as-code)
|
|
- [[raw/official-docs/migration-k8s-init-container-job-pattern]] — Group G-D 대안 3 (K8s Job 패턴)
|
|
- 적용 branch-note:
|
|
- [[raw/branch-notes/feature-migration-startup-contract]]
|
|
- [[raw/branch-notes/feature-runtime-health-lifecycle-contract]]
|
|
- canonical contract:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — migration startup canonical section (예정 `wiki/projects/ca-skeleton-operational-contract`)
|
|
- 대안 그룹: **Group G-D — Migration startup**. 본 source 의 위치: 대안 1 — Flyway (ca-tmpl 채택, baseline).
|