Skip to main content

Setup Your Migration Workflow

With your schema defined as code, the next step is to set up how changes are applied to your database. If you haven't chosen a workflow yet, see Choose a workflow.

How it works​

Atlas keeps track of schema changes in a migration directory containing SQL migration scripts. Each file is named with a version and an optional label:

<version>_<label>.sql

For example: 20240520182336_add_users_table.sql. By default, Atlas uses a YYYYMMDDHHMMSS timestamp as the version.

Step 1: Configuration​

Add a migration block to your atlas.hcl to define where migration files are stored:

atlas.hcl
env "local" {
  url = getenv("DB_URL")
  dev = "docker://postgres/16/dev"
  schema {
    src = "file://schema"
  }
  migration {
    dir = "file://migrations"
  }
}

Step 2: Create the baseline migration​

The first migration in your directory is called the baseline. It captures the full schema as it exists today, so that all future migrations are diffs on top of it.

Generate the baseline by running:

atlas migrate diff --env local baseline

Two new files are created under the migrations/ directory:

migrations/
├── 20240604131146_baseline.sql
└── atlas.sum
  • 20240604131146_baseline.sql contains the full CREATE TABLE, CREATE INDEX, etc. statements for your current schema.
  • atlas.sum is the integrity file that protects against conflicts between developers working in parallel.

How does migrate diff work?​

  1. Reads the desired schema from the location defined in the schema.src field in atlas.hcl.
  2. Reads the state represented by your migrations directory.
  3. Calculates the diff and verifies the migration plan on the dev database.
  4. Writes a new migration file and updates atlas.sum.

Step 3: Apply the baseline​

How you apply the baseline depends on whether you are starting with a new (empty) database or adopting Atlas on an existing database that already has tables.

New database​

For a new database with no existing tables, apply migrations normally:

atlas migrate apply --env local

Atlas executes the baseline migration and records it in the revision table.

Existing database​

If your database already contains the schema described by the baseline (e.g. a production database you are now bringing under Atlas management), the baseline migration should not be executed. Instead, use the --baseline flag to tell Atlas to mark it as already applied and start tracking from the next migration:

atlas migrate apply --env local --baseline "20240604131146"

Replace 20240604131146 with the version from your baseline filename.

Migrating from another tool?

If your project already uses Flyway, Liquibase, goose, or another migration tool, see Importing an Existing Database for instructions on importing your existing migration history into Atlas.

Step 4: Verify​

Confirm the migration directory is in sync with your schema by running migrate diff again:

atlas migrate diff --env local
The migration directory is synced with the desired state, no changes to be made.