MaarkssDN/Birthub-360 / .agents/skills/atlas-migrations
atlas-migrations
VerifiedUse when a team wants declarative, Terraform-style database schema management or migration linting beyond Flyway and Liquibase: Atlas schema apply, migrate diff against a dev database, migrate lint for destructive or locking changes, and migrate hash, across a dozen databases.
atlas-migrations
Overview
Atlas manages and migrates database schemas as code - define the desired schema and Atlas plans, lints, tests, and applies the changes (per atlasgo.io/getting-started). Two operating modes:
- Declarative - define desired state in HCL or SQL; Atlas
computes diff and applies (
atlas schema apply). - Versioned - Atlas generates timestamped migration files from
schema diffs (
atlas migrate diff); migrations apply forward (atlas migrate apply).
Use versioned mode where every change needs a reviewed file and an audit trail; declarative mode suits fast local iteration.
How to use
Follow the steps in order. Lint and validate (Step 5) are the gate:
nothing reaches migrate apply (Step 6) until they pass.
Step 1 - Install
Per at-start:
# Homebrew (macOS / Linux)
brew install ariga/tap/atlas
# Docker: nothing to install, mount the migrations directory
docker run --rm --net=host -v "$(pwd)/migrations:/migrations" \
arigaio/atlas migrate apply --url "$DATABASE_URL"
In GitHub Actions, uses: ariga/setup-atlas@v0 puts the CLI on the
runner (Step 8, per at-gha). The getting-started page also
lists per-platform binaries with md5 and sha256 checksums; verify the
checksum before running a downloaded binary. Prefer these over piping
the vendor install script into a shell, which runs unreviewed remote
code.
Step 2 - Define schema
Per at-start, schema can be SQL (most common) or HCL. SQL example (PostgreSQL):
-- schema.sql
CREATE TABLE users (
id serial PRIMARY KEY,
name varchar(255) NOT NULL,
email varchar(255) UNIQUE NOT NULL,
created_at timestamptz DEFAULT now()
);
For the same schema expressed in Atlas's HCL DSL and guidance on when HCL vs SQL matters, see references/hcl-schema.md.
The dev DB referenced via --dev-url is a temporary scratch
database Atlas uses to compute the diff (Atlas applies the desired
state to the scratch DB, then computes the migration vs production).
Step 3 - Apply schema (declarative mode)
Per at-start:
atlas schema apply --url "$DATABASE_URL" --to file://schema.sql \
--dev-url "docker://postgres/17/dev?search_path=public"
--url = target DB; --to = desired schema definition; --dev-url
= scratch DB for diff computation. Atlas prints the planned changes
and prompts for confirmation by default.
Step 4 - Generate versioned migrations
Per at-start:
atlas migrate diff initial --to file://schema.sql \
--dev-url "docker://postgres/17/dev?search_path=public"
This generates a timestamped migration file in migrations/ (e.g.,
20260506120000_initial.sql). Subsequent calls with a new schema
generate new migrations against the previous state.
Step 5 - Gate: validate and lint before any apply
atlas migrate lint needs Atlas Pro from v0.38 (atlas login first);
without it, keep migrate validate and use the migration-blast-radius-reviewer
agent for the risk review (lint docs).
-
Make the risky analyzers fail. Only
destructivefails lint by default (exit code 1); data-dependent and backward-incompatible findings are only reported (analyzers). Turn them into errors inatlas.hcl:lint { data_depend { error = true } # MF1xx: NOT NULL add, new unique index on existing data incompatible { error = true } # BC1xx: rename / drop of tables and columns } -
Run the gate:
atlas migrate validate --dir "file://migrations" \ --dev-url "docker://postgres/17/dev?search_path=public" atlas migrate lint --dir "file://migrations" \ --dev-url "docker://postgres/17/dev?search_path=public" --latest 1validatechecks the directory againstatlas.sumand, with--dev-url, replays the files to check the SQL (CLI reference). -
Fix and re-lint. For each finding, change the migration, not the rule: add a
DEFAULTor backfill beforeSET NOT NULL(MF103/MF104), split a rename into add-copy-drop across releases (BC), build the indexCONCURRENTLYon PostgreSQL (PG1xx). Re-runatlas migrate diff/atlas migrate hashafter editing an unapplied file, then repeat step 2 until it exits 0. Suppress a finding with-- atlas:nolint <code>only with a comment saying why and a reviewer's sign-off.
Step 6 - Apply versioned migrations
atlas migrate apply --url "$DATABASE_URL" --dry-run # print the SQL
atlas migrate apply --url "$DATABASE_URL"
Read the dry-run SQL before the real run (CLI reference). Atlas
records each applied version in the atlas_schema_revisions table, so
the next apply starts after the last recorded one.
Step 7 - Hash and integrity
atlas.sum holds a hash per migration file. Editing a file changes the
hash and migrate validate / migrate apply fail until
atlas migrate hash is run, which must be a deliberate act: never edit
a migration that has already been applied anywhere; add a new one.
Step 8 - CI integration
- uses: ariga/setup-atlas@v0
- name: Validate and lint (gate)
run: |
atlas migrate validate --dir "file://migrations" \
--dev-url "docker://postgres/17/dev?search_path=public"
atlas migrate lint --dir "file://migrations" \
--dev-url "docker://postgres/17/dev?search_path=public" \
--git-base origin/main
- name: Apply migrations to staging
if: github.ref == 'refs/heads/main'
run: atlas migrate apply --url "${{ secrets.STAGING_DB_URL }}"
--git-base lints every migration the branch adds compared with the
base branch, instead of a fixed --latest N (lint docs).
ariga/setup-atlas puts the CLI on the runner (at-gha).
Step 9 - Composition with sister tools
Atlas lint knows SQL patterns, not your data volumes or release
order. Run the migration-blast-radius-reviewer agent on the PR for
team policies such as "no DROP TABLE without DBA approval", and use
migration-operation-taxonomy to classify each operation's lock and
rollback risk.
Worked example
Add a NOT NULL column status to a 40M-row users table:
- Edit
schema.sqlto addstatus varchar(20) NOT NULL DEFAULT 'active'onusers. atlas migrate diff add_status --to file://schema.sql --dev-url "docker://postgres/17/dev?search_path=public"writesmigrations/20260506120000_add_status.sql.- Step 5 gate:
atlas migrate validateandatlas migrate lint --latest 1with thedata_dependanalyzer set to error. Without theDEFAULT, MF103 (adding a non-nullable column) fails the lint; with it, the gate passes. - CI runs the same gate on the PR; after merge,
atlas migrate apply --dry-runthenatlas migrate applyagainst staging records the version inatlas_schema_revisions. - A teammate later edits that applied file; their
atlas migrate applyfails on hash mismatch until an intentionalatlas migrate hashre-sync - the tamper guard working as designed.
Anti-patterns and limitations
The failure modes (editing applied migrations, skipping --dev-url,
declarative schema apply straight to production, skipping lint in
CI, blind atlas migrate hash) and the tool's limitations (partial
HCL for some DBMS features, general-purpose lint rules, --dev-url
requiring a real DBMS, paid Atlas Cloud) are catalogued in
references/atlas-caveats.md.
References
- at-start - getting-started, install commands,
example schema, all
atlascommands, supported databases - at-gha -
ariga/setup-atlasGitHub Action - at-lint -
migrate lintflags (--latest,--git-base), Atlas Pro requirement from v0.38 - at-an - analyzers, check codes, which fail by default,
error = true - at-cli -
migrate apply --dry-run,migrate validate - atlasgo.io/docs - full documentation
- github.com/ariga/atlas - repository
flyway-migrations,liquibase-migrations- sister tools (imperative versioned migrations);migration-operation-taxonomyandmigration-blast-radius-reviewerfor risk review
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |