118 lines
11 KiB
Markdown
118 lines
11 KiB
Markdown
---
|
|
title: "Liquibase — Changelog Formats (XML / YAML / JSON / SQL) and Rollback"
|
|
source_type: official-doc
|
|
url: https://docs.liquibase.com/concepts/changelogs/home.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: medium
|
|
tags: [ca-skeleton, migration, startup, liquibase, schema, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-migration-startup-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Liquibase — Changelog Formats (XML / YAML / JSON / SQL) and Rollback
|
|
|
|
> Layer: `raw/official-docs/` — Liquibase 공식 문서 발췌 (docs.liquibase.com + GitHub README). ca-tmpl Group G-D 대안 2. Flyway 와 비교 baseline 용.
|
|
|
|
> **2026-05-27 정독 시 docs.liquibase.com 의 모든 deep-link 가 HTTP 403 반환** (자동화 접근 차단). 본 문서의 "핵심 인용" 중 일부 (changelog 정의·DATABASECHANGELOG checksum 동작·rollback 자동 생성 동작) 는 이전 정독 시점의 인용을 보존하되, 직접 재확인이 불가능하여 `confidence: medium` + 해당 claim 의 strength 는 `needs-confirmation` 으로 표시한다. 직접 재확인 가능했던 GitHub `liquibase/liquibase` README 인용은 `official-vendor-doc` 으로 분리.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-migration-startup-contract]] | Liquibase = ca-tmpl Group G-D 대안 2 (채택 X, "조직 표준일 때만 허용"). DB-agnostic changelog + rollback 자동 생성의 장점과 XML/YAML verbose + rollback "guaranteed safe 아님" 단점을 baseline 으로 보존하여 Flyway 채택을 정당화 |
|
|
|
|
또한 다음 project hub 에서도 인용:
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — migration startup canonical section
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl `feature-migration-startup-contract`의 결정은 **Flyway default + Liquibase는 조직 표준일 때만 허용**. 본 source는 Liquibase의 strength (DB-agnostic changelog + rollback) 와 weakness (XML/YAML 복잡도)를 baseline으로 보존.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL (자동화 접근 차단): https://docs.liquibase.com/concepts/changelogs/home.html (HTTP 403 — 2026-05-27 재확인)
|
|
- 보조 URL (자동화 접근 차단): https://docs.liquibase.com/workflows/liquibase-community/using-rollback.html (HTTP 403)
|
|
- 직접 재확인 가능 보조 URL: https://github.com/liquibase/liquibase (Liquibase 공식 GitHub README, 2026-05-27 정독)
|
|
- 저자/조직: Liquibase Inc.
|
|
- 발행일: Liquibase 4.x reference (current)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
### A. 2026-05-27 직접 재확인 가능 (GitHub README)
|
|
|
|
> [§GitHub liquibase/liquibase README — Overview] "Liquibase helps millions of developers track, version, and deploy database schema changes."
|
|
|
|
> [§GitHub README — Capabilities (verbatim bullets)] "Control database schema changes for specific versions" / "Eliminate errors and delays when releasing databases" / "Automatically order scripts for deployment" / "Easily rollback changes" / "Collaborate with tools you already use"
|
|
|
|
> [§GitHub README — Getting started examples] examples/sql 및 examples/xml 디렉터리 참조 — SQL / XML format 의 존재만 명시적으로 확인 가능 (YAML/JSON 의 README 내 직접 언급은 없음).
|
|
|
|
### B. 이전 정독 시점 인용 (docs.liquibase.com, 2026-05-27 현재 자동화 재확인 불가 — `needs-confirmation`)
|
|
|
|
> [§docs.liquibase.com / Concepts / Changelogs — needs-confirmation] "Liquibase uses a changelog to track, version, and deploy database changes. The changelog is a file that you create to list all the changes that need to run against the database. Changelogs can be written in SQL, XML, YAML, or JSON format."
|
|
|
|
> [§docs.liquibase.com / Concepts / Changelogs — needs-confirmation] "Each changeSet contains one or more refactorings (changes) that should be applied to the database. A changeSet is uniquely identified by the combination of an id, author, and changelog file path/name. ... Once executed, the changeSet is recorded in the `DATABASECHANGELOG` table."
|
|
|
|
> [§docs.liquibase.com / Using rollback — needs-confirmation] "Liquibase generates rollback statements automatically for some change types (e.g., `createTable`, `addColumn`). For other change types you must provide explicit `<rollback>` blocks. ... Rollback in production is not guaranteed to be safe — data loss may occur."
|
|
|
|
> [§docs.liquibase.com / Concepts — needs-confirmation] "Liquibase changesets are checksum-validated against `DATABASECHANGELOG.MD5SUM`. Modifying an applied changeset changes the checksum and Liquibase will fail at startup unless `runOnChange` or `validCheckSum` is set."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| LIQUIBASE-C1 | Liquibase 는 "track, version, and deploy database schema changes" 를 위한 공식 도구 (수백만 dev 가 사용) | [§GitHub README] "Liquibase helps millions of developers track, version, and deploy database schema changes." | `official-vendor-doc` | Liquibase 일반 도입 결정 | "Flyway 보다 좋다" 라는 비교 우위는 본 인용에 없음 |
|
|
| LIQUIBASE-C2 | Liquibase 공식 capability 에 "Easily rollback changes" 가 포함됨 (= rollback 이 first-class 기능) | [§GitHub README — Capabilities] "Easily rollback changes" | `official-vendor-doc` | Liquibase rollback 기능의 공식 마케팅 포지션 | "모든 change type 에 rollback 이 자동 생성됨" 또는 "rollback 이 prod 에서 항상 안전함" 은 본 인용으로 증명 안 됨 (B 섹션의 `needs-confirmation` claim 필요) |
|
|
| LIQUIBASE-C3 | Liquibase 는 최소한 SQL 및 XML format 의 changelog 를 지원 (GitHub README 의 examples 디렉터리 명시) | [§GitHub README] examples/sql 및 examples/xml 디렉터리 참조 | `official-vendor-doc` | SQL / XML changelog 작성 | YAML / JSON format 지원은 본 README 인용으로는 직접 증명 안 됨 (실제로 공식 지원되나, 본 자료에서 직접 인용 확보 못함 → `LIQUIBASE-C4` 참조) |
|
|
| LIQUIBASE-C4 | (이전 정독) changelog 는 SQL/XML/YAML/JSON 4가지 format 으로 작성 가능 | [§docs.liquibase.com / Concepts] "Changelogs can be written in SQL, XML, YAML, or JSON format." | `needs-confirmation` | Liquibase 4.x changelog 작성 | 2026-05-27 자동화 재확인 불가 (403). 수동 브라우저 재확인 필요 |
|
|
| LIQUIBASE-C5 | (이전 정독) changeSet 은 `id + author + 파일 경로/이름` 의 조합으로 고유 식별되고 실행 후 `DATABASECHANGELOG` table 에 기록됨 | [§docs.liquibase.com / Concepts] "A changeSet is uniquely identified by the combination of an id, author, and changelog file path/name. ... Once executed, the changeSet is recorded in the DATABASECHANGELOG table." | `needs-confirmation` | Liquibase changeSet 식별 메커니즘 | 2026-05-27 자동화 재확인 불가. column 정확한 이름은 공식 schema reference 별도 확인 필요 |
|
|
| LIQUIBASE-C6 | (이전 정독) rollback statement 는 일부 change type (`createTable`, `addColumn` 등) 에서 자동 생성되고 그 외는 명시적 `<rollback>` 블록 필요. **prod rollback 은 "guaranteed safe 아님" — data loss 가능** | [§docs.liquibase.com / Using rollback] "Liquibase generates rollback statements automatically for some change types ... Rollback in production is not guaranteed to be safe — data loss may occur." | `needs-confirmation` | rollback 운영 결정 | 2026-05-27 자동화 재확인 불가. 자동 생성되는 정확한 change type 전체 목록은 별도 reference |
|
|
| LIQUIBASE-C7 | (이전 정독) 이미 applied 된 changeset 이 수정되면 `DATABASECHANGELOG.MD5SUM` checksum mismatch 로 startup 시 실패하며, `runOnChange` 또는 `validCheckSum` 설정으로만 우회 가능 | [§docs.liquibase.com / Concepts] "Liquibase changesets are checksum-validated against DATABASECHANGELOG.MD5SUM ... Liquibase will fail at startup unless runOnChange or validCheckSum is set." | `needs-confirmation` | Liquibase startup validation | 2026-05-27 자동화 재확인 불가. checksum 알고리즘 (MD5 외) 의 정확한 버전별 차이는 별도 확인 필요 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것 (높은 신뢰)**:
|
|
- `LIQUIBASE-C1`: Liquibase 의 공식 포지션 (track/version/deploy schema changes)
|
|
- `LIQUIBASE-C2`: rollback 이 공식 capability 로 마케팅됨
|
|
- `LIQUIBASE-C3`: SQL + XML format 지원 (examples 디렉터리)
|
|
- **이 자료가 직접 증명하지 않는 것 (자동화 재확인 불가, `needs-confirmation`)**:
|
|
- `LIQUIBASE-C4`~`C7`: changelog 포맷 4종 전체, changeSet 식별 정확한 구성, rollback 자동 생성 change type, MD5SUM checksum 동작 — docs.liquibase.com 403 차단으로 자동 재확인 못함. **수동 브라우저로 재확인 후 strength 승급 필요**
|
|
- "Liquibase 가 Flyway 보다 enterprise-friendly 하다" 같은 비교 주장 (본 자료 범위 밖)
|
|
- 한국/일본 기업의 Liquibase 운영 사례 (별도 case study 필요)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- docs.liquibase.com 의 자동화 접근 차단을 우회할 archive.org snapshot URL 확보 (현재 미수집)
|
|
- rollback 자동 생성되는 change type 의 정확한 목록 (`createTable`, `addColumn` 외 어디까지인지)
|
|
- Spring Boot 와의 통합 시 default 동작 (Liquibase Spring Boot starter)
|
|
- DB-agnostic XML/YAML 의 실제 portability 한도 (vendor-specific 기능 사용 시)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
|
|
|
- 적용 시나리오: 여러 DB(Oracle / PostgreSQL / MySQL 등)를 동시에 지원해야 하는 enterprise 환경, rollback이 명시적 요구사항인 환경.
|
|
- 장점:
|
|
- XML/YAML changelog는 DB-agnostic — 같은 changeset이 여러 DB에 deploy 가능 (`databaseChangeLog`의 `dbms` attribute).
|
|
- 일부 change type에서 rollback 자동 생성.
|
|
- changelog include / property substitution 등 modularization 기능이 풍부.
|
|
- 단점:
|
|
- XML/YAML이 SQL보다 verbose. dev 학습 비용 증가.
|
|
- rollback이 "guaranteed safe"가 아님 — 데이터 손실 가능. forward-only migration이 더 안전하다는 ca-tmpl 결정과 충돌하지 않지만 매력 감소.
|
|
- precondition / context 같은 고급 기능을 잘못 쓰면 silent skip이 발생.
|
|
- ca-tmpl과의 차이: ca-tmpl은 Flyway default. Liquibase는 "조직 표준일 때만 허용"으로 둔다. rollback 지원이 장점이지만 ca-tmpl 결정은 `no in-place rollback, forward-only migration + feature flag`이므로 rollback 자동 생성 가치가 감소.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/migration-flyway-official-concepts-and-repair]] — Group G-D 채택안 (Flyway)
|
|
- [[raw/official-docs/migration-atlas-schema-as-code]] — Group G-D 대안 4 (Atlas)
|
|
- [[raw/official-docs/migration-k8s-init-container-job-pattern]] — Group G-D 대안 3 (K8s Job 패턴)
|
|
- 적용 branch-note:
|
|
- [[raw/branch-notes/feature-migration-startup-contract]]
|
|
- canonical contract:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — migration startup canonical section
|
|
- 대안 그룹: **Group G-D — Migration startup**. 본 source의 위치: 대안 2 — Liquibase. ca-tmpl 채택 안 함 (조직 표준일 때만 허용).
|