Migration với Atlas — declarative state thay Flyway/Liquibase imperative

Dev local thêm column priority vào bảng tasks. Commit, push. Code review pass. Merge vào main. CD pipeline deploy production. Nhưng migration file bị quên — không có trong repo. Kết quả: production thiếu column, app ném lỗi column "priority" does not exist, on-call thức lúc 2 giờ sáng rollback.

Migration tool tồn tại để ngăn đúng kịch bản này: track schema version, đảm bảo mỗi environment chạy đúng set migration theo thứ tự, và block deploy nếu schema chưa đồng bộ. Từ 2022, một paradigm mới xuất hiện cạnh Flyway và Liquibase — declarative migration với Atlas. Bài này map 2 paradigm, Atlas workflow thực tế, CI lint gate, và license change của Liquibase năm 2024 để bạn có đủ context cho quyết định 2025+.

1. Analogy — Git declarative state vs imperative patches

Hình dung bạn restore một project file bị mất. Có 2 cách:

• Imperative: replay từng patch theo thứ tự — patch 1, patch 2, patch 3... đến trạng thái cuối. Nếu patch 2 bị lỗi hoặc áp sai thứ tự, kết quả sai.
• Declarative: mô tả trạng thái cuối mong muốn — tool tự tính diff so với trạng thái hiện tại và sinh ra patch tối thiểu để đạt đến đó.

Flyway và Liquibase theo mô hình imperative: dev viết từng SQL migration file theo thứ tự version. Atlas theo mô hình declarative: dev mô tả desired state bằng schema file, tool tự sinh SQL migration.

2. Imperative (Flyway/Liquibase) — pattern và lifecycle

Dev viết SQL file rõ ràng từng bước, tool chỉ track và execute:

-- Flyway: migrations/V001__create_users.sql
CREATE TABLE users (
  id    BIGSERIAL PRIMARY KEY,
  email TEXT UNIQUE NOT NULL
);

-- migrations/V002__add_name.sql
ALTER TABLE users ADD COLUMN name TEXT;

-- migrations/V003__add_email_index.sql
CREATE INDEX idx_users_email ON users(email);

Workflow Flyway:

• Dev viết SQL migration với prefix version (V001, V002...)
• flyway migrate apply theo thứ tự version tăng dần
• Track applied migrations trong bảng flyway_schema_history
• Re-run: skip version đã apply (idempotent qua checksum)
• Rollback: Flyway Community không có — dev phải tự viết U001__undo_create_users.sql

Liquibase tương tự nhưng dùng XML/YAML/SQL changeset, có rollback command với Pro license.

Pros:

• Explicit, predictable — SQL rõ ràng do dev kiểm soát hoàn toàn
• Versioned history dễ đọc — git log migrations/ cho toàn bộ lịch sử schema
• Mature ecosystem — Flyway từ 2010, Liquibase từ 2006, cộng đồng lớn
• Framework integration tốt — Spring Boot auto-apply Flyway/Liquibase khi start

Cons:

• Manual SQL → dev phải tự biết pattern an toàn (expand-contract, CONCURRENTLY, NOT VALID)
• Không có lint tự động — dev có thể viết blocking DDL vào production
• Diff giữa env phức tạp — phải compare từng version file, không compare state
• Flyway Pro (paid) cho features nâng cao: rollback, dry run, diff với target

3. Declarative (Atlas) — schema.hcl và auto-diff

Dev mô tả desired state, Atlas sinh SQL:

# schema.hcl -- desired state, single source of truth
table "users" {
  schema = schema.public
  column "id" {
    type = bigserial
    null = false
  }
  column "email" {
    type = text
    null = false
  }
  column "name" {
    type = text
    null = true
  }
  primary_key {
    columns = [column.id]
  }
  index "users_email_unique" {
    columns = [column.email]
    unique  = true
  }
}

Atlas so sánh schema.hcl với DB hiện tại, sinh ra migration SQL tối thiểu:

-- Atlas-generated: migrations/20260504143000_add_users_name.sql
-- Phat sinh tu diff: schema.hcl them column "name", chua co trong DB
ALTER TABLE "users" ADD COLUMN "name" text;

Pros:

• Ít manual SQL → ít cơ hội viết unsafe DDL
• Schema file duy nhất — đọc 1 file biết toàn bộ state của DB
• Diff giữa env tự động — Atlas compare state, không compare version number
• Open-source forever (Apache 2.0) — không lo license thay đổi
• CI lint built-in — 50+ rule catch dangerous DDL trước merge

Cons:

• SQL do tool sinh ra có thể không optimal cho trường hợp cụ thể — cần review
• Learning curve HCL và Atlas DSL
• Ít mature hơn Flyway/Liquibase — Atlas từ 2022, ecosystem nhỏ hơn
• HCL không quen thuộc với team Java/Spring đã dùng XML config

4. Atlas hands-on demo

# 1. Install Atlas CLI (Mac)
brew install ariga/tap/atlas

# 2. Define desired state: schema.hcl (xem section 3)

# 3. Generate migration tu diff
atlas migrate diff add_users_name \
  --dir  "file://migrations" \
  --to   "file://schema.hcl" \
  --dev-url "docker://postgres/16/dev"
# Output: migrations/20260504143000_add_users_name.sql
# Content: ALTER TABLE "users" ADD COLUMN "name" text;

# 4. Review SQL output (recommend pair review trong PR)

# 5. Apply to target DB
atlas migrate apply \
  --dir "file://migrations" \
  --url "$DATABASE_URL"

# 6. Check status
atlas migrate status \
  --dir "file://migrations" \
  --url "$DATABASE_URL"
# Output: 3 migrations applied, 0 pending

--dev-url docker://postgres/16/dev khởi động container Postgres tạm thời để Atlas thực hiện diff — không cần dev database riêng cho quá trình generate migration. Container tự xoá sau khi diff xong.

Revert migration:

# Rollback 1 migration cuoi
atlas migrate down \
  --dir "file://migrations" \
  --url "$DATABASE_URL" \
  --amount 1

Atlas tự sinh SQL revert (DROP COLUMN, DROP TABLE...) từ context của migration file — không cần dev viết undo script thủ công như Flyway Community.

5. Atlas linting — 50+ rule catch unsafe DDL

Lint chạy trước khi merge, ngăn dangerous DDL vào production:

# Lint migration moi nhat
atlas migrate lint \
  --dir "file://migrations" \
  --latest 1 \
  --dev-url "docker://postgres/16/dev"

Ví dụ rules quan trọng:

Khi lint phát hiện vi phạm:

-- Atlas lint output vi du:
L1: Destructive change "DROP COLUMN name" detected.
    DS101: Dropping column "name" from table "users" is destructive.
    To suppress, add:  --allow-destructive

Dev phải explicit chấp nhận (--allow-destructive) hoặc sửa migration. Không thể merge ngẫu nhiên.

6. CI gate — block PR nếu unsafe DDL

# .github/workflows/migration-check.yml
name: Migration lint

on:
  pull_request:
    paths:
      - "migrations/**"
      - "schema.hcl"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Atlas
        uses: ariga/setup-atlas@v0

      - name: Lint migrations
        run: |
          atlas migrate lint \
            --dir "file://migrations" \
            --latest 1 \
            --dev-url "docker://postgres/16/dev"

PR chứa migration bị unsafe DDL → CI fail → không thể merge. Dev phải fix hoặc justify explicit. Pattern này catch hầu hết blocking DDL trước khi vào production — không phụ thuộc vào dev nhớ check thủ công.

7. Liquibase 2024 — license thay đổi sang FSL

Liquibase Core (open-source hơn 20 năm) chuyển sang Functional Source License (FSL) từ tháng 4/2024. FSL không được OSI công nhận là open-source:

• Cho phép: use, modify, distribute nội bộ
• Không cho phép: cung cấp "competitive offering" — vendor SaaS chạy Liquibase as a service để cạnh tranh với Liquibase Inc.
• Sau 4 năm: tự động chuyển về Apache 2.0 (delayed open-source)

Implications thực tế:

• Team tự host, dùng nội bộ → vẫn OK, không vi phạm FSL
• Cloud vendor tích hợp Liquibase vào SaaS → phải review kỹ FSL terms
• Greenfield 2025+ → consider Atlas (Apache 2.0 vĩnh viễn) hoặc Flyway Community (Apache 2.0)

FSL khác gì BSL (Business Source License) của Terraform: cả hai có delayed open-source clause, nhưng FSL restriction hẹp hơn (chỉ competitive offering), BSL rộng hơn (production use threshold). Cả hai không phải OSI open-source.

Reference chính thức: Liquibase License FAQ (mục Deep Dive dưới).

8. Pitfall — generated migration không đảm bảo zero-downtime

Ví dụ cụ thể:

-- Atlas generate tu schema.hcl them column priority:
ALTER TABLE tasks ADD COLUMN priority TEXT NOT NULL DEFAULT 'normal';

-- Tren PG 11+: metadata-only change, instant, khong lock
-- Tren PG 10 tro xuong: full table rewrite, lock toan bo table
--   Voi 50 trieu row: co the mat hang gio downtime

Atlas lint không catch case này nếu DB target là PG 11+ (lint chạy trên dev container PG 16, pass). Nhưng nếu production chạy PG 10 vì chưa upgrade, migration này blocking.

Trường hợp khác lint chưa catch đầy đủ:

-- ADD FOREIGN KEY voi data volume lon
ALTER TABLE tasks ADD CONSTRAINT fk_project
  FOREIGN KEY (project_id) REFERENCES projects(id);
-- Scan toan bo tasks de validate, giu ShareRowExclusiveLock
-- Tren bang 100 trieu row: block write hang chuc phut
-- An toan hon: ADD FOREIGN KEY ... NOT VALID, roi VALIDATE CONSTRAINT rieng

Defensive practice:

• Test migration trên staging với data volume tương đương production trước khi apply prod
• Profile lock duration với EXPLAIN (ANALYZE, BUFFERS) trên staging
• Apply trong maintenance window cho risky DDL không thể tránh lock
• Forward: Module 11 của khoá này deep dive production migration safe pattern — CONCURRENTLY, expand-contract, lock_timeout, statement_timeout

9. Atlas vs Flyway vs Liquibase — comparison table

10. Applied — TaskFlow migration với Atlas

Schema HCL cho TaskFlow:

# schema/users.hcl -- desired state
table "users" {
  schema = schema.public
  column "id" {
    type = bigserial
    null = false
  }
  column "email" {
    type = text
    null = false
  }
  column "name" {
    type = text
    null = false
  }
  column "created_at" {
    type    = timestamptz
    null    = false
    default = sql("now()")
  }
  primary_key {
    columns = [column.id]
  }
  index "users_email_unique" {
    columns = [column.email]
    unique  = true
  }
}

CI/CD flow cho TaskFlow:

1. Dev thay doi schema.hcl (them column, them table, them index...)
2. atlas migrate diff <name> -- generate SQL migration file
3. Commit ca schema.hcl va migration file vao PR
4. CI chay: atlas migrate lint --latest 1 -- check unsafe DDL
5. Reviewer approve SQL generated (pair review)
6. CD: atlas migrate apply -> staging -> smoke test
7. CD: atlas migrate apply -> production (sau khi staging pass)

Apply staging trước production cho phép phát hiện timing issue (lock duration quá lâu, data validation fail) mà CI lint không catch được vì staging có data thực.

11. Deep Dive — Migration tools

Liên kết khoá học khác

• Khoá Spring — bài 4.6 Flyway Migration — Flyway imperative migration trong Spring Boot, so sánh với Atlas declarative.

12. Tóm tắt

• 2 paradigm: imperative (Flyway, Liquibase — dev viết SQL từng step) vs declarative (Atlas — dev mô tả desired state, tool diff và sinh SQL).
• Atlas declarative: schema.hcl là single source of truth, atlas migrate diff tự động sinh SQL migration từ diff giữa desired và current state.
• Atlas linting 50+ rule catch unsafe DDL (drop column, blocking index, blocking FK) trong CI — block PR trước khi merge vào main.
• Liquibase chuyển FSL tháng 4/2024 — không còn fully open-source per OSI; greenfield 2025+ nên cân nhắc Atlas hoặc Flyway Community thay thế.
• Generated migration không đảm bảo zero-downtime — lint không catch tất cả trường hợp, human review và test trên staging với production data volume vẫn bắt buộc.
• CI/CD pattern chuẩn: schema change trong PR → lint gate → pair review SQL → apply staging → apply production.
• Forward: Module 11 của khoá này đi sâu production migration safe pattern — CONCURRENTLY, expand-contract, lock_timeout, statement_timeout.

13. Tự kiểm tra

Bài tiếp theo: Module 5 — Indexing internals