Welcome to the Atlas Documentation

Atlas is a language-independent 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.

Quick Start

Get started with Atlas in under 5 minutes.

Installation

To download and install the latest release of the Atlas CLI, simply run the following in your terminal:

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

Get the latest release with Homebrew:

brew install ariga/tap/atlas

To pull the Atlas image and run it as a Docker container:

docker pull arigaio/atlas
docker run --rm arigaio/atlas --help

If the container needs access to the host network or a local directory, use the --net=host flag and mount the desired directory:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply \
  --url "mysql://root:pass@:3306/test"

GitHub Actions

Use the setup-atlas action to install Atlas in your GitHub Actions workflow:

- uses: ariga/setup-atlas@v0
  with:
    cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}

Other CI Platforms

For other CI/CD platforms, use the installation script. See the CI/CD integrations for more details.

The default binaries distributed in official releases are released under the Atlas MSA. If you would like obtain a copy of Atlas Community Edition (under an Apache 2 license) follow the instructions here.

For users who want to use specific drivers such as Oracle, Snowflake, or Google Spanner that are not included in the standard Atlas CLI release, follow the instructions here.

Set Up With Your Coding Agent

Atlas ships an agent skill for Claude Code, Codex, Cursor, and GitHub Copilot. Paste the prompt for your agent and it installs the skill, then sets up schema management in your project.

Claude Code
OpenAI Codex
Cursor
GitHub Copilot

Paste into Claude Code. Installs for every project on this machine. Use .claude/skills/atlas at the repository root to commit the skill with one repository. See Claude Code with Atlas for the instructions-file alternative.

Install the Atlas skill: download https://atlasgo.io/skills/atlas/SKILL.md to ~/.claude/skills/atlas/SKILL.md and
each reference file listed in its Files section to ~/.claude/skills/atlas/references/<name>.
Overwrite existing files without editing them. Then install the Atlas CLI if it is missing (curl -sSf https://atlasgo.sh | sh) and set up Atlas
for database schema management in this project.

Paste into OpenAI Codex. Installs for every project on this machine. Use .codex/skills/atlas at the repository root to commit the skill with one repository. See OpenAI Codex with Atlas for the instructions-file alternative.

Install the Atlas skill: download https://atlasgo.io/skills/atlas/SKILL.md to ~/.codex/skills/atlas/SKILL.md and
each reference file listed in its Files section to ~/.codex/skills/atlas/references/<name>.
Overwrite existing files without editing them. Then install the Atlas CLI if it is missing (curl -sSf https://atlasgo.sh | sh) and set up Atlas
for database schema management in this project.

Paste into Cursor. Cursor loads skills from .cursor/skills/ at the repository root. Enable Agent Skills under Cursor Settings, Rules, Import Settings. See Cursor with Atlas for the instructions-file alternative.

Install the Atlas skill at the repository root: download https://atlasgo.io/skills/atlas/SKILL.md to .cursor/skills/atlas/SKILL.md and
each reference file listed in its Files section to .cursor/skills/atlas/references/<name>.
Overwrite existing files without editing them. Then install the Atlas CLI if it is missing (curl -sSf https://atlasgo.sh | sh) and set up Atlas
for database schema management in this project.

Paste into GitHub Copilot. Copilot loads skills from .github/skills/ at the repository root. See GitHub Copilot with Atlas for the instructions-file alternative.

Install the Atlas skill at the repository root: download https://atlasgo.io/skills/atlas/SKILL.md to .github/skills/atlas/SKILL.md and
each reference file listed in its Files section to .github/skills/atlas/references/<name>.
Overwrite existing files without editing them. Then install the Atlas CLI if it is missing (curl -sSf https://atlasgo.sh | sh) and set up Atlas
for database schema management in this project.

Schema-as-Code

Choose your preferred way to represent the desired state of your database.

SQL

Describe your database schema with native SQL.

Atlas HCL

The HCL-based language allows developers to describe database schemas in a declarative manner.

ORM

Represent your database with your ORM.

Generating Migrations

Atlas offers two workflows to generate and plan migration changes. In both workflows, Atlas automatically plans schema migrations based on your desired schema. Choose which one works best for you.

Declarative Migrations

Set up a Terraform-like workflow where each migration is calculated as the diff between your desired state and the current state of the database.

Versioned Migration

Set up a migration directory for your project, creating a version-controlled source of truth of your database schema.

Verifying Migration Safety

Atlas verifies your migrations by running them against various checks to ensure their safety and validity. Verify these changes locally or as part of your CI process.

CLI

Verify your migration files in your CLI.

GitHub

Setup automatic migration linting with GitHub Actions.

Gitlab

Setup automatic migration linting with GitLab CI.

Bitbucket

Setup automatic migration linting with Bitbucket Pipes.

Azure DevOps

Setup automatic migration linting with Azure DevOps.

CircleCI

Setup automatic migration linting with CircleCI Orbs.

Deploying Migrations

Deploy migrations to target databases in production by integrating natively with the rest of your infrastructure management.

GitHub

Setup deployments with GitHub Actions.

Gitlab

Setup deployments with GitLab CI.

Bitbucket

Setup deployments with Bitbucket Pipes.

Azure DevOps

Setup deployments with Azure DevOps.

CircleCI

Setup deployments with CircleCI Orbs.

Terraform Provider

Use Atlas with Terraform to manage database schema changes.

Kubernetes Operator

Use the Atlas Kubernetes Operator to manage database schema changes.

Argo CD

Deploy migrations using GitOps with Argo CD.

Crossplane

Manage database schemas with Atlas using Crossplane.

Declarative Security & Data Management

Manage database security objects and seed data as code alongside your schema.

Database Security as Code

Define roles, users, grants, and permissions declaratively in HCL or SQL. Atlas diffs and plans changes automatically.

Declarative Data Management

Manage seed data and lookup table rows declaratively. Atlas computes the minimal diff and generates migration plans.

Atlas Cloud

Gain full visibility into the databases in your development and production environments with visualizations, detailed logs, and troubleshooting capabilities.

Getting Started

Push your database schema to the Cloud to maintain a single source of truth for database schemas with auto-generated documentation.

Setup CI

Simulate and analyze changes to catch destructive changes, backward-incompatibility issues, accidental table locks, and constraint violations way before they reach production.