112 lines
10 KiB
Markdown
112 lines
10 KiB
Markdown
---
|
|
title: "Atlas — Schema as Code, Declarative Migrations, and Versioned Workflow"
|
|
source_type: official-doc
|
|
url: https://atlasgo.io/concepts/declarative-vs-versioned
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-skeleton, migration, startup, atlas, schema-as-code, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-migration-startup-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Atlas — Schema as Code, Declarative Migrations, and Versioned Workflow
|
|
|
|
> Layer: `raw/official-docs/` — Atlas (atlasgo.io) 공식 문서 발췌. ca-tmpl Group G-D 대안 4 (schema-as-code 모델). Flyway/Liquibase 와 비교 baseline 용.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-migration-startup-contract]] | Atlas = ca-tmpl Group G-D 대안 4 (채택 X). schema-as-code (declarative) 모델 + `atlas.sum` integrity hash 의 baseline 보존. ca-tmpl 이 Spring Boot stack 가정 + 한국 운영 사례 부족으로 채택하지 않은 결정의 근거 |
|
|
|
|
또한 다음 project hub 에서도 인용:
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — migration startup canonical section
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl `feature-migration-startup-contract` Group G-D 대안 후보. Atlas는 **schema-as-code** 모델로 Flyway/Liquibase와는 다른 운영 모델을 제공. ca-tmpl이 검토한 후 default로 채택하지 않은 이유를 baseline으로 보존.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://atlasgo.io/concepts/declarative-vs-versioned
|
|
- 보조 URL: https://atlasgo.io/concepts/migration-directory-integrity
|
|
- 저자/조직: Ariga Inc. (Atlas)
|
|
- 발행일: 0.x reference (current)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Declarative Migrations] "With declarative migrations, the desired state of the database schema is given as input to the migration engine, which plans and executes a set of actions to change the database to its desired state."
|
|
|
|
> [§Versioned Migrations] "Instead of describing the desired state ('what the database should look like'), developers describe the changes themselves ('how to reach the state')."
|
|
|
|
> [§Declarative Migrations — input sources] "The desired state can be defined using HCL schema files, SQL schema files, another database, ORM providers (such as GORM, Drizzle, Django, or SQLAlchemy), or a combination of these sources."
|
|
|
|
> [§Combining Declarative and Versioned Workflows] "They run `atlas migrate diff` against the updated desired state. Atlas computes the difference between the current migration history and the new schema and writes a migration file into the migrations directory. The file is then committed to source control as part of a pull request."
|
|
|
|
> [§Migration Directory Integrity — atlas.sum] "The `atlas.sum` file contains the checksum of each migration file (implemented by a reverse, one branch merkle hash tree), and a sum of all files."
|
|
|
|
> [§Migration Directory Integrity — sample] "This file is simply another file in your migration directory called `atlas.sum` and looks something like: h1:KRFsSi68ZOarsQAJZ1mfSiMSkIOZlMq4RzyF//Pwf8A=20220318104614_team_A.sql"
|
|
|
|
> [§Migration Directory Integrity — VCS effect] "Adding new files results in a change to the sum file, which will raise merge conflicts in most version control systems."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| ATLAS-C1 | Atlas 의 declarative workflow 는 "원하는 schema 의 desired state" 를 입력으로 받아 migration engine 이 그 state 로 가는 action set 을 자동으로 plan + 실행 | [§Declarative Migrations] "the desired state of the database schema is given as input to the migration engine, which plans and executes a set of actions to change the database to its desired state." | `official-vendor-doc` | Atlas declarative workflow | "Flyway/Liquibase 보다 안전하다" 라는 비교 우위는 본 인용에 없음 |
|
|
| ATLAS-C2 | Atlas 의 versioned workflow 는 desired state ("무엇") 대신 변경 자체 ("어떻게") 를 dev 가 직접 기술하는 방식 — declarative 와 명시적으로 대비되는 별도 모델 | [§Versioned Migrations] "Instead of describing the desired state ('what the database should look like'), developers describe the changes themselves ('how to reach the state')." | `official-vendor-doc` | Atlas versioned workflow (Flyway/Liquibase 와 동일 카테고리) | Atlas versioned 가 Flyway versioned 와 동등한 기능을 제공한다는 직접 비교는 본 인용 범위 밖 |
|
|
| ATLAS-C3 | declarative 입력 source 는 HCL, SQL, 다른 DB, ORM provider (GORM/Drizzle/Django/SQLAlchemy 등) 또는 조합 가능 | [§Declarative Migrations] "The desired state can be defined using HCL schema files, SQL schema files, another database, ORM providers (such as GORM, Drizzle, Django, or SQLAlchemy), or a combination of these sources." | `official-vendor-doc` | declarative schema 정의 시 input format 선택 | Spring/JPA/Hibernate 가 같은 list 에 포함된다는 직접 진술은 없음 — ORM provider list 에 JPA/Hibernate 미명시 |
|
|
| ATLAS-C4 | `atlas migrate diff` 명령은 현재 migration history 와 새 schema 의 차이를 계산하여 migration file 을 migrations directory 에 작성하며, 그 file 은 PR 의 일부로 source control 에 commit 됨 | [§Combining Declarative and Versioned Workflows] "Atlas computes the difference between the current migration history and the new schema and writes a migration file into the migrations directory. The file is then committed to source control as part of a pull request." | `official-vendor-doc` | Atlas declarative-to-versioned hybrid workflow | "자동 생성된 SQL 이 항상 정확하다" 또는 "사람 review 가 불필요하다" 는 뜻 아님 — review 책임은 별도 |
|
|
| ATLAS-C5 | Atlas 는 migration directory 에 `atlas.sum` 파일을 두고 (a) 각 migration file 의 checksum + (b) 전체 sum 을 reverse-one-branch merkle hash tree 로 저장 | [§Migration Directory Integrity] "The `atlas.sum` file contains the checksum of each migration file (implemented by a reverse, one branch merkle hash tree), and a sum of all files." | `official-vendor-doc` | Atlas migration directory 일반 | hash 알고리즘의 정확한 함수 (h1: prefix 이름) 는 별도 spec 문서 필요 |
|
|
| ATLAS-C6 | migration file 추가/수정 시 `atlas.sum` 이 자동 변경되어 VCS 에서 merge conflict 를 일으킴 → 동시 변경 감지 메커니즘 역할 | [§Migration Directory Integrity] "Adding new files results in a change to the sum file, which will raise merge conflicts in most version control systems." | `official-vendor-doc` | Git 등 VCS 위의 Atlas migration 운영 | "applied 후 file 을 수정하면 CI 가 자동으로 fail 한다" 는 직접 진술은 본 인용 범위 밖 — VCS conflict 가 1차 방어선, CI 검증은 별도 atlas migrate validate 등 추가 단계 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `ATLAS-C1`/`C2`: declarative vs versioned 의 정확한 정의 (desired state vs changes)
|
|
- `ATLAS-C3`: declarative input source 의 정확한 list (HCL/SQL/DB/ORM)
|
|
- `ATLAS-C4`: `atlas migrate diff` 의 정확한 동작 + PR 워크플로
|
|
- `ATLAS-C5`/`C6`: `atlas.sum` 파일의 구조 + VCS conflict 메커니즘
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- Spring Boot / Java 생태계와의 통합 성숙도 (본 페이지에 비교 없음)
|
|
- declarative 모드의 generated SQL 검증 비용 (운영 해석 영역)
|
|
- "한국 기업 사례가 적다" 같은 시장 통계 (본 자료에 없음 — 별도 한국어 conf talks/case studies)
|
|
- destructive change detection (linter/policy) 의 정확한 명령 / rule 목록 (`atlas migrate lint` 별도 문서)
|
|
- production 운영 시 backwards-incompatible diff 의 처리 정책
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- Spring Boot stack 에서 Atlas CLI 와 application lifecycle 통합 방법 (Maven/Gradle plugin 여부)
|
|
- ca-tmpl 의 "schema migration = application deploy 와 묶음" 결정과 Atlas declarative workflow 의 정합성
|
|
- declarative 모드에서 발생한 destructive change 의 ca-tmpl deploy gate 통합 방안
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
|
|
|
- 적용 시나리오: Go 중심 stack 또는 schema-as-code를 적극 도입하려는 신규 프로젝트, 다중 DB 환경에서 declarative 모델을 원할 때.
|
|
- 장점:
|
|
- declarative 모델 — desired state만 정의하면 diff가 자동 계산.
|
|
- destructive change detection이 plan 단계에서 작동 (linting + policy).
|
|
- migration directory integrity hash로 history tampering 방지.
|
|
- 단점:
|
|
- Java/Spring Boot 생태계와의 통합 성숙도가 Flyway/Liquibase 대비 낮음 (CLI 기반 운영).
|
|
- declarative 모드는 generated migration의 인간 검증 비용이 큼 (auto-generated SQL을 사람이 review).
|
|
- 한국 기업 사례가 적어 운영 노하우 / 인력 풀이 좁다.
|
|
- ca-tmpl과의 차이: ca-tmpl은 Spring Boot stack을 가정하므로 Flyway default. Atlas는 schema-as-code 가치가 있지만 stack mismatch + 운영 사례 부족으로 채택 안 함.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/migration-flyway-official-concepts-and-repair]] — Group G-D 채택안 (Flyway)
|
|
- [[raw/official-docs/migration-liquibase-official-changelog-xml-yaml]] — Group G-D 대안 2 (Liquibase)
|
|
- [[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의 위치: 대안 4 — Atlas (schema-as-code). ca-tmpl 채택 안 함, baseline 비교용.
|