Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw 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

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 + 운영 사례 부족으로 채택 안 함.

같은 주제 다른 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 비교용.

10 KiB Raw Blame History