Skip to main content

Setup CI/CD for Versioned Migrations

Continuous integration and continuous deployment (CI/CD) are essential practices for modern software development. Applying these principles to your database migrations helps ensure that schema changes are validated, tested, and deployed safely across all environments.

This doc introduces how to set up a CI/CD pipeline for database schema migrations with Atlas. It covers automated validation, testing, policy-based review, and deployment of schema changes so the final migrations are correct, predictable, and safe to apply for production.

Diagram showing the modern database CI/CD workflow: Develop, Review, Deliver, and Deploy.

For a deeper understanding of the principles behind this workflow, see our Modern Database CI/CD blueprint.

Choose Your Workflow​

Atlas supports two types of schema management workflows: versioned migrations and declarative (state-based) migrations. This guide focuses on setting up CI/CD for versioned migrations.

Versioned Migrations (Used in this guide)

Changes are defined as explicit migration files (SQL scripts) that are applied in sequence. Each migration is tracked, version-controlled, and reviewable in pull requests.

Declarative (State-based) Migrations

Define the desired state of your database, and Atlas automatically calculates the migration plan. This approach is covered in detail in platform-specific guides.

To understand the differences and tradeoffs between these approaches, see Declarative (State-based) vs Versioned Migrations.

Prerequisites​

Before setting up CI/CD, ensure you have the following:

Installing Atlas​

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

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

Atlas Pro for CI/CD​

Using Atlas in CI/CD requires Atlas Pro. To activate it in your pipelines, you'll need a bot token from Atlas Cloud.

If you don't have an account yet, sign up for a free trial at auth.atlasgo.cloud or run atlas login in your terminal.

Privacy and Security

Atlas Cloud does not access your repositories or databases. By default, Atlas Cloud only handles authentication (login) for Atlas Pro, and using the Schema Registry is optional.

The Schema Registry allows you to store, version, and maintain a single source of truth for your database schemas, and database migrations. If you prefer not to use the Schema Registry, you can use alternative storage options such as S3-compatible object storage, or any other storage solution accessible from your CI/CD pipeline.

Setup Your Migration Directory​

If you haven't set up a versioned migrations project yet, create a migration directory before configuring CI/CD. Choose one of the following options:

Getting Started with a Fresh Project

Create your first migration directory by defining your desired schema in SQL, HCL, or through an ORM. Atlas will automatically generate migration files that you can review, version control, and apply to your databases.

Import Existing Database

Import an existing database to code, then baseline it by generating an initial migration file that represents its current state. This baseline migration serves as the starting point for future migrations and allows Atlas to begin managing your database schema going forward.

CI Platform Selection​

Atlas provides native integrations for all popular CI/CD platforms, with support for code comments, code suggestions, PR and run summaries, PR status updates, and more. Choose your CI platform to get started:

GitHub Actions

Set up CI/CD pipelines using GitHub Actions with Atlas. Supports both versioned and declarative workflows.

GitLab CI

Integrate Atlas with GitLab CI/CD pipelines using GitLab CI components. Full support for versioned and declarative workflows.

Azure DevOps

Use Azure DevOps Pipelines with Atlas. Supports GitHub and Azure Repos repositories with versioned migrations.

CircleCI

Automate database migrations with CircleCI Orbs. Complete CI/CD integration for versioned workflows.

Bitbucket Pipelines

Set up CI/CD using Bitbucket Pipes. Full support for versioned migrations and schema management.

Continuous Integration (CI)​

CI validates and tests schema changes before merging to the main branch, ensuring they are safe, correct, and ready for production. The workflow follows this pattern:

  1. Pull Request - Developer or an AI Code Assistant (such as Cursor or Claude Code) creates a PR with schema or migration changes
  2. Lint - Atlas validates migrations for safety and correctness and comments a report on the PR
  3. Diff Generation - (Optional) Automatically generate migrations from schema changes
  4. Tests - (Optional) Atlas runs migration and schema tests and comments the results on the PR
  5. Review - Team reviews Atlas reports and generated migrations
  6. Merge - Changes are merged to main branch
  7. Push to Registry - Migration directory is pushed to Atlas Registry

Linting Migrations​

Atlas validates migrations through linting that catches destructive changes, backward-incompatible operations and changes, and policy violations. It also performs automatic drift detection to ensure migrations align with your schema, and history integrity checks to maintain linear migration order.

Atlas automatically posts lint results as comments on your pull/merge requests, providing immediate feedback to developers:

GitHub Actions pull request comment showing Atlas migration lint results

To learn more about migration linting, see the Migration Linting guide.

Automatic Diff Generation​

When developers define their schema as code (HCL, SQL, or ORM) and make changes, Atlas can automatically generate migration files using the ariga/atlas-action/migrate/diff action. If migrations weren't generated locally, Atlas automatically plans the migrations and commits the files to the working PR.

The diff action also checks for drift between your schema code and migration files, ensuring they stay in sync. To keep your pull request up to date with the latest changes from the main branch, use the ariga/atlas-action/migrate/autorebase action, which automatically rebases your branch and avoids manual rebasing.

The migrate-diff functionality is available on most CI platforms:

This creates a seamless workflow where schema changes automatically become reviewable migration files.

Schema and Migration Tests​

Modern databases contain real application logic: constraints enforce business rules, triggers execute code on events, functions and procedures encapsulate complex operations, and views abstract data access. This is code, and it deserves the same engineering discipline as the rest of your system. Atlas brings software engineering practices to the database, such as version control, static analysis, migrations, and testing, so you can treat database logic with the same rigor as application code.

  • Schema tests verify that the schema behaves the way you expect. You can write unit tests for functions, triggers, views, procedures, constraints, and more. Atlas testing framework allows you to seed data, run queries, assert results, test failure cases, and run tests in parallel to keep things fast.

  • Migration tests ensure that your database migrations are semantically correct. They run against isolated databases, let you seed data, apply the migrations, and make assertions. They are especially important for data migrations, where correctness depends on the existing data and small mistakes can slip through without careful comparison of the results.

To learn more about testing, see:

Push to Registry​

When a pull request is merged into the main branch, Atlas lets you push your migration directory to the Atlas Schema Registry. This creates an immutable, versioned artifact (like pushing a Docker image to a container registry) that becomes the single source of truth for your migrations.

The registry stores the exact migration files that passed review and testing, ensuring only approved migrations can be deployed. Once in the registry, migrations can be deployed to any environment without needing access to your source code repository, using URLs like atlas://myapp?tag=latest or atlas://myapp?version=20231201182011.

atlas migrate push

Migration Directory created with atlas migrate push

$ atlas migrate push app \
  --dev-url "docker://postgres/15/dev?search_path=public"

The migrate-push functionality is available on all CI platforms:

Continuous Deployment (CD)​

Once your migrations are validated and pushed to the registry, you can deploy them to your environments. Choose the deployment method based on your infrastructure needs:

ArgoCD

GitOps deployment for Kubernetes using ArgoCD. Deploy migrations declaratively with full GitOps workflow.

GitHub Actions

Deploy migrations directly from your CI/CD pipeline. Simple and straightforward deployment for any environment.

Terraform

Infrastructure as Code deployment using the Atlas Terraform Provider. Manage migrations alongside your infrastructure.

Kubernetes Operator

Native Kubernetes resource management using the Atlas Operator. Deploy migrations as Kubernetes resources.

Flux CD

GitOps deployment alternative for Kubernetes. Continuous delivery with Git-based configuration.

Other Options

Additional deployment methods including ECS Fargate, Helm, and more. Find the right solution for your infrastructure.

Next Steps​

Enhance your CI/CD pipeline with advanced features, such as environment promotion workflows with compliance support, real-time schema monitoring and drift detection, custom policy rules, and webhook notifications:

Environment Promotion

Implement progressive deployments across Dev, Staging, and Production with environment segregation and compliance support for SOC 2, ISO 27002, and more.

Schema Monitoring & Drift Detection

Get live visibility of your database schema with automated ER diagrams, changelogs, and real-time monitoring. Automatically detect when your schema drifts from its intended state and get instant alerts via Slack or webhooks.

Custom Policy Rules

Define custom linting rules to enforce team practices, naming conventions, and compliance requirements. Write rules in HCL to automate policy enforcement.

Webhooks & Notifications

Set up webhooks to receive notifications about schema changes, drift detection, and deployment events in Slack or custom HTTP endpoints.