Skip to main content

Using Migration Baseline in GitHub Actions

Question​

How to use the baseline option with ariga/atlas-action/migrate/apply when adopting Atlas for an existing database?

Answer​

When adopting Atlas for an existing database that already has schema objects, you need to create a baseline migration that reflects your current database schema. This step is required because it sets the starting point for Atlas's versioning system. This lets future migrations safely reference existing schema elements, like adding a foreign key to an existing table or creating a view that refers to existing tables.

note

When a migration is marked as baseline, Atlas adds it to the revisions (history) table without running the SQL in it, but just marks it as already applied.

If you're using GitHub Actions for CI/CD, you can apply migrations with the ariga/atlas-action/migrate/apply action. Since this action doesn't expose a direct --baseline flag, you'll need to configure the baseline setting in your atlas.hcl file instead.

Complete Workflow​

Step 1: Generate a Baseline Migration​

First, create a migration that represents your existing database schema:

atlas migrate diff baseline \
  --dir "file://migrations" \
  --dev-url "docker://postgres/15/dev" \
  --to "postgres://user:pass@host:5432/mydb"

This creates a migration file like 20240115120000_baseline.sql containing your current schema.

Step 2: Configure Baseline in atlas.hcl​

Add the baseline configuration to your atlas.hcl:

atlas.hcl
env "prod" {
  url = "postgres://user:pass@host:5432/mydb"
  migration {
    dir = "file://migrations"
    baseline = "20240115120000"  # Version without .sql extension
  }
}

Step 3: Use GitHub Action​

The action will respect the baseline configuration:

.github/workflows/deploy.yml
- name: Apply migrations
  uses: ariga/atlas-action/migrate/apply@v1
  with:
    config: "file://path/to/atlas.hcl"
    env: prod

For more details on working with existing databases, see the versioned migrations documentation.