Atlas - Manage Your Database Schema as Code

Atlas is a language-agnostic tool for managing and migrating database schemas using modern DevOps principles. It offers two workflows:

• Declarative: Similar to Terraform, Atlas compares the current state of the database to the desired state, as defined in an HCL, SQL, or ORM schema. Based on this comparison, it generates and executes a migration plan to transition the database to its desired state.

• Versioned: Unlike other tools, Atlas automatically plans schema migrations for you. Users can describe their desired database schema in HCL, SQL, or their chosen ORM, and by utilizing Atlas, they can plan, lint, and apply the necessary migrations to the database.

Supported Databases

PostgreSQL · MySQL · MariaDB · SQL Server · SQLite · ClickHouse · Redshift · Oracle · Snowflake · CockroachDB · TiDB · Databricks · Spanner · Aurora DSQL · Azure Fabric

Installation

macOS + Linux:

curl -sSf https://atlasgo.sh | sh

Homebrew:

brew install ariga/tap/atlas

Docker:

docker pull arigaio/atlas

NPM:

npx @ariga/atlas

See installation docs for all platforms.

Key Features

• Declarative schema migrations: The atlas schema command offers various options for inspecting, diffing, comparing, planning and applying migrations using standard Terraform-like workflows.
• Versioned migrations: The atlas migrate command provides a state-of-the-art experience for planning, linting, and applying migrations.
• Schema as Code: Define your desired database schema using SQL, HCL, or your chosen ORM. Atlas supports 16 ORM loaders across 6 languages.
• Security-as-Code: Manage roles, permissions, and row-level security policies as version-controlled code.
• Data management: Manage seed and lookup data declaratively alongside your schema.
• Cloud-native CI/CD: Kubernetes operator, Terraform provider, GitHub Actions, GitLab CI, ArgoCD, and more.
• Testing framework: Unit test schema logic (functions, views, triggers, procedures) and migration behavior.
• 50+ safety analyzers: Database-aware migration linting that detects destructive changes, data-dependent modifications, table locks, backward-incompatible changes, and more.
• Multi-tenancy: Built-in support for multi-tenant database migrations.
• Drift detection: Monitoring as Code with automatic schema drift detection and remediation.
• Cloud integration: IAM-based authentication for AWS RDS and GCP Cloud SQL, secrets management via AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, and more.

Getting Started

Get started with Atlas by following the Getting Started docs.

Inspect an existing database schema:

atlas schema inspect -u "postgres://localhost:5432/mydb"

Apply your desired schema to the database:

atlas schema apply \
  --url "postgres://localhost:5432/mydb" \
  --to file://schema.hcl \
  --dev-url "docker://postgres/16/dev"

📖 Getting Started docs

Migration Linting

Atlas ships with 50+ built-in analyzers that review your migration files and catch issues before they reach production. Analyzers detect destructive changes like dropped tables or columns, data-dependent modifications such as adding non-nullable columns without defaults, and database-specific risks like table locks and table rewrites that can cause downtime on busy tables. You can also define your own custom policy rules.

atlas migrate lint --dev-url "docker://postgres/16/dev"

Schema Testing

Test database logic (functions, views, triggers, procedures) and data migrations with .test.hcl files:

test "schema" "postal" {
  # Valid postal codes pass
  exec {
    sql = "SELECT '12345'::us_postal_code"
  }
  # Invalid postal codes fail
  catch {
    sql = "SELECT 'hello'::us_postal_code"
  }
}

test "schema" "seed" {
  for_each = [
    {input: "hello", expected: "HELLO"},
    {input: "world", expected: "WORLD"},
  ]
  exec {
    sql    = "SELECT upper('${each.value.input}')"
    output = each.value.expected
  }
}

atlas schema test --dev-url "docker://postgres/16/dev"

📖 Testing docs

Security-as-Code

Manage database roles, permissions, and row-level security as version-controlled code:

role "app_readonly" {
  comment = "Read-only access for reporting"
}

role "app_writer" {
  comment   = "Read-write access for the application"
  member_of = [role.app_readonly]
}

user "api_user" {
  password   = var.api_password
  conn_limit = 20
  comment    = "Application API service account"
  member_of  = [role.app_writer]
}

permission {
  for_each   = [table.orders, table.products, table.users]
  for        = each.value
  to         = role.app_readonly
  privileges = [SELECT]
}

policy "tenant_isolation" {
  on    = table.orders
  for   = ALL
  to    = ["app_writer"]
  using = "(tenant_id = current_setting('app.current_tenant')::integer)"
  check = "(tenant_id = current_setting('app.current_tenant')::integer)"
}

📖 Security-as-Code docs

Data Management

Manage seed and lookup data declaratively alongside your schema:

CREATE TABLE countries (
  id INT PRIMARY KEY,
  code VARCHAR(2) NOT NULL,
  name VARCHAR(100) NOT NULL
);

INSERT INTO countries (id, code, name) VALUES
  (1, 'US', 'United States'),
  (2, 'IL', 'Israel'),
  (3, 'DE', 'Germany');

📖 Data management docs

ORM Support

Define your schema in any of the 16 supported ORMs. Atlas reads your models and generates migrations:

📖 ORM integration docs

Integrations

Lint, test, and apply migrations automatically in your CI/CD pipeline or infrastructure-as-code workflow:

AI Agent Integration

Atlas provides Agent Skills, an open standard for packaging migration expertise for AI coding assistants: Claude Code, GitHub Copilot, Cursor, OpenAI Codex. Learn more at AI tools docs.

CLI Usage

schema inspect

Easily inspect your database schema by providing a database URL and convert it to HCL, JSON, SQL, ERD, or other formats.

Inspect a specific MySQL schema and get its representation in Atlas DDL syntax:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl

table "users" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  ...
}

Inspect the entire MySQL database and get its JSON representation:

atlas schema inspect \
  --url "mysql://root:pass@localhost:3306/" \
  --format '{{ json . }}' | jq

{
  "schemas": [
    {
      "name": "example",
      "tables": [
        {
          "name": "users",
          "columns": [
            ...
          ]
        }
      ]
    }
  ]
}

Inspect a specific PostgreSQL schema and get its ERD representation in Mermaid syntax:

atlas schema inspect \
  --url "postgres://root:pass@:5432/test?search_path=public&sslmode=disable" \
  --format '{{ mermaid . }}'

erDiagram
    users {
      int id PK
      varchar name
    }
    blog_posts {
      int id PK
      varchar title
      text body
      int author_id FK
    }
    blog_posts }o--o| users : author_fk

Use the split format for one-file-per-object output:

atlas schema inspect -u '<url>' --format '{{ sql . | split | write }}'

├── schemas
│   └── public
│       ├── public.sql
│       ├── tables
│       │   ├── profiles.sql
│       │   └── users.sql
│       ├── functions
│       └── types
└── main.sql

📖 Schema inspection docs

schema diff

Compare two schema states and get a migration plan to transform one into the other. A state can be specified using a database URL, HCL, SQL, or ORM schema, or a migration directory.

atlas schema diff \
  --from "postgres://postgres:pass@:5432/test?search_path=public&sslmode=disable" \
  --to file://schema.hcl \
  --dev-url "docker://postgres/15/test"

📖 Declarative workflow docs

schema apply

Generate a migration plan and apply it to the database to bring it to the desired state. The desired state can be specified using a database URL, HCL, SQL, or ORM schema, or a migration directory.

atlas schema apply \
  --url mysql://root:pass@:3306/db1 \
  --to file://schema.hcl \
  --dev-url docker://mysql/8/db1

-- Planned Changes:
-- Modify "users" table
ALTER TABLE `db1`.`users` DROP COLUMN `d`, ADD COLUMN `c` int NOT NULL;
Use the arrow keys to navigate: ↓ ↑ → ←
? Are you sure?:
  ▸ Apply
    Abort

📖 Declarative workflow docs

migrate diff

Write a new migration file to the migration directory that brings it to the desired state. The desired state can be specified using a database URL, HCL, SQL, or ORM schema, or a migration directory.

atlas migrate diff add_blog_posts \
  --dir file://migrations \
  --to file://schema.hcl \
  --dev-url docker://mysql/8/test

📖 Versioned workflow docs

migrate apply

Apply all or part of pending migration files in the migration directory on the database.

atlas migrate apply \
  --url mysql://root:pass@:3306/db1 \
  --dir file://migrations

📖 Versioned workflow docs

Supported Version Policy

To ensure the best performance, security and compatibility with the Atlas Cloud service, the Atlas team will only support the two most recent minor versions of the CLI. For example, if the latest version is v0.25, the supported versions will be v0.24 and v0.25 (in addition to any patch releases and the "canary" release which is built twice a day).

Community

Documentation · Discord · Twitter