Skip to main content

Verifying Migration Safety

Atlas helps you ensure safe schema migrations for your database by automatically analyzing migration files for potentially dangerous or breaking changes. It is driven by the atlas migrate lint command, which can be used both locally and in CI pipelines at pull-request (merge-request) time.

Having this setup helps your team work collaboratively on database schemas, ensuring schema migrations are streamlined, safe, best practices are enforced, and no one steps on another's toes. Atlas analyzes every schema migration change in the migration directory for issues like:

  • Destructive operations (e.g., dropping columns or tables).
  • Breaking schema changes that could cause application errors.
  • Table locks or rewrites that could lead to downtime.
  • Custom policies that can be defined using the Atlas Schema Rule language.
  • And more. Learn more about the Atlas analyzers that power these checks.

While this command is commonly used locally, migration linting is frequently incorporated into CI pipelines, allowing teams to detect changes early before merging them into the main branch. Learn more about how to integrate Atlas into your GitHub Actions, GitLab CI Components, CircleCI, or Bitbucket Pipes workflows.

Flags​

When using migrate lint to analyze migrations, users must supply multiple parameters:

  • --dev-url - URL to a Dev-database that will be used to simulate the changes and verify their correctness.
  • --dir - URL of the migration directory, by default it is file://migrations, e.g a directory named migrations in the current working directory.
  • --web / -w (optional) - open the lint report in the browser.

Changeset detection​

When we run the lint command, we need to instruct Atlas on how to decide which set of migration files to analyze. Currently, three ways are supported. Let's go over them one by one:

Compare against the latest state of the migration directory​

Teams that have pushed their project to the Atlas Schema Registry (see setup for more details), can simply run the following command to analyze the changes detected by comparing the local state of the migration directory to the latest state, as defined in Atlas Cloud. For example, either by running atlas migrate push or by connecting it to a CI pipeline.

atlas migrate lint \
  --dev-url "docker://mysql/8/dev" \
  -w
Preventing non-additive changes

By using this method, Atlas warns you if your local migration directory is not up-to-date with the latest state of the project and rebasing is required. For example, while working on a feature branch, another team member might have pushed a new migration file to the main branch.

Here is an example of how a report of atlas migrate lint looks like:

CI for schema changes

Analyze the latest N migration files​

Users can instruct Atlas to analyze the latest N migration files by running atlas migrate lint --latest N:

atlas migrate lint \
  --dev-url "docker://mysql/8/dev" \
  --latest 1

Similarly to the previous method, the -w/--web can be used to open the report in the browser, see the changes in ERD format, and more.

Compare against a specific branch​

Users can instruct Atlas to detect which changes to analyze by comparing the current branch to a specific branch. For example, in order to analyze the changes between the current branch and the main branch, and open the report in the browser, run the following command:

atlas migrate lint \
  --dev-url "docker://mysql/8/dev" \
  --git-base "master" \
  -w

nolint directive​

Annotating a statement with the --atlas:nolint directive allows excluding it from the analysis reporting. For example:

Using --atlas:nolint excludes the annotated statement from all linters.

-- atlas:nolint
ALTER TABLE `t1` DROP COLUMN `c1`, ADD COLUMN `d1` varchar(255) NOT NULL;

--atlas:nolint
ALTER TABLE `t2` DROP COLUMN `c2`, ADD COLUMN `d2` varchar(255) NOT NULL;

/*atlas:nolint*/
ALTER TABLE `t3` DROP COLUMN `c3`, ADD COLUMN `d3` varchar(255) NOT NULL;

#atlas:nolint
ALTER TABLE `t4` DROP COLUMN `c4`, ADD COLUMN `d4` varchar(255) NOT NULL;

Open in the browser​

In order to open the migration linting report in the browser, you first need to be logged in to Atlas, then use one of the example commands above with the -w/--web flag. For example:

atlas login
atlas migrate lint \
  --dev-url "docker://mysql/8/dev" \
  --latest 1 \
  -w
Screenshot example

CI for schema changes

Output​

Users may supply a Go template string as the --format parameter to format the output of the lint command.

Reference​

CLI Command Reference