Skip to main content

What Are Changesets in Atlas?

In version control systems like Git, a changeset represents an atomic unit of change. It groups related file modifications under a single hash, allowing them to be reviewed, applied, or reverted together.

In database migrations, a changeset is a unit of schema or data changes made up of SQL statements stored in a migration file, typically executed together in a single transaction.

In Atlas, a changeset is represented by a migration file that includes a version number, an optional description, and a collection of elements, such as: transaction configuration, DDL and DML statements, pre-migration checks, an integrity hash (to ensure content and order haven't changed after apply), optional annotations for masking sensitive values, and more.

Once a changeset is created by a developer or with CI automation, Atlas lets you validate (lint), test, deploy, monitor, and revert it. The rest of this document explains how Atlas handles changesets in detail.

Changeset generation with Atlas​

Unlike traditional migration tools that require writing SQL by hand, Atlas automates changeset generation by diffing your current schema against the desired state of the schema. The process is fully automated and policy-aware, so migrations are consistent, predictable, and follow your rules by default. Here's how it works:

  1. Define the desired schema using SQL schema, Atlas HCL syntax, another database, an ORM, or any combination of these options.
  2. Run atlas migrate diff.
  3. Atlas computes the diff, applies your migration policies, and generates the changeset needed to reach the target schema state.
  4. Atlas updates the atlas.sum file with a hash of the new changeset to guarantee integrity and enforce ordering.

Since this process is automated (locally or in CI), you get deterministic, minimal diffs that respect policies like create indexes concurrently for existing tables or never drop a table without a backup.

Read more at:

Validating and linting changesets​

Atlas provides two commands to validate changesets early in the workflow: atlas migrate validate and atlas migrate lint. These commands work both locally and in CI to help catch mistakes before they reach production.

Highlights of the validation and linting process include:

  • Built-in checks include destructive change detection, rename safety, table-lock detection, concurrent index creation, naming conventions, and more.
  • Custom policies can be written using the Atlas Schema Rule language, allowing you to enforce project-specific standards like: all tables must have timestamp columns, primary keys must be bigint, column and index names must follow naming conventions, and more.
  • Atlas simulates the migration changeset against a temporary dev-database to make sure both generated and manual SQL statements are syntactically and semantically correct.
  • Atlas supports CI integration such as GitHub Actions, GitLab CI, BitBucket, Azure DevOps, and more. Once a PR is created, the changeset is automatically validated and linted, and the results are reported back to the PR as comments or warnings.

Read more at:

Testing changesets​

Atlas includes a built-in testing framework that makes it easy to write both unit and integration tests for your schema and migration logic. Tests are written in HCL, with logic in plain SQL, and can run both locally and in CI.

There are two test types:

  • Schema tests ensure your desired schema can be applied cleanly on a blank database, and let you validate constraints, triggers, functions, data logic, and queries.
  • Migration tests simulate real-world upgrades by applying one or more changesets and validating the result. Common use: seed data before a changeset version, apply the changeset, then assert that logic like a data transformation worked as expected.

Tests support parallel execution, input variables, executing external tools (other programming languages), and automatic creation using Atlas Copilot.

Read more at:

Deploying changesets​

Once changes are merged to the main branch, the CD (delivery) pipeline can package them so they're available at the deployment stage. Migration changesets can be pushed to Atlas Registry, built into a custom Docker image, or uploaded to a blob store like S3 for Atlas to consume during migrate apply.

atlas migrate push

Migration Directory push with atlas migrate push to Atlas Registry

Atlas provides a variety of ways to apply changesets as part of your deployment pipelines:

  • CI/CD runners: Use Atlas official integration from GitHub Actions, GitLab CI, CircleCI, Bitbucket, Azure Pipelines, and more.
  • Atlas Kubernetes Operator: Use the Atlas Operator to manage migrations in Kubernetes clusters. Works out of the box with ArgoCD and Flux.
  • Terraform Provider: Use the atlas_migration resource to apply schema changes as part of terraform apply.

Read more at:

Undoing and rolling back changesets​

Atlas makes it easy to safely revert changesets. If a changeset was applied by mistake or if a deployment needs to be rolled back, use the atlas migrate down command.

Unlike traditional tools, that require pre-written down files, Atlas computes rollback plans automatically based on the current database state. The plan includes reverse SQL statements that bring the database back to a previous version or tag, and can be reviewed with --dry-run before applying.

Highlights of Atlas generated rollback plans:

  • Revert the last changeset, a series of changesets, or jump back to a named version or tag.
  • Supports reverting partially applied changesets in case the database is in a bad state due to implicit commits or incorrect transaction configuration.
  • Automatically protects against unintended data loss by validating the plan for destructive changes.
  • Validates and simulate the plan to detect issues before applying.
  • Integrates with approval workflows to protect production environments.

Read more at:

Monitoring and detecting schema drift​

Atlas helps you detect and respond to schema drift, when the actual state of a database diverges from the expected state defined by the latest changeset applied on the database. Drift can happen when someone bypasses the migration workflow and makes direct changes on the database. These ad-hoc changes introduce risk: queries may break, migrations may fail, and CI assumptions become invalid.

Atlas provides two options for detecting drift:

  • Atlas Schema Monitoring – Choose a source (e.g., a deployed changeset or another environment) and let Atlas periodically compare it to the live database. If a drift is found, Atlas will notify you with a detailed report via Slack or a webhook.
  • CI or scheduled checks – Use Atlas CI integrartions to auto-compare the live database against the latest changeset or a specific changeset version. This can be done as part of your CI/CD pipeline or scheduled checks.

Read more at:

Managing multi-tenant environments​

Atlas includes built-in support for managing multi-tenant database environments, commonly used in database-per-tenant architectures.

Teams can define logical tenant groups and apply the same changeset across many databases or schemas in a single operation. This makes it easier to manage large fleets while ensuring that each tenant stays consistent with the intended schema state.

With Atlas multi-tenancy support, you can:

  • Roll out the same changeset to multiple databases using a single command.
  • Track which changesets were applied to which tenants.
  • Control the target databases and their orders at runtime using Atlas HCL language.
  • Gradually deploy or safely revert changesets per tenant if needed.

Read more in the Database-per-Tenant guide.

Read more​

For more information about changesets in Atlas, check out the following resources: