Skip to main content

Verifying migration safety

The atlas migrate lint command enables team members to work together on database schemas, ensuring they are synchronized and avoid stepping on each other's toes. Atlas analyzes new schema changes in the migration directory that might be dangerous, violate best practices, or break the team's policies. Learn more about Atlas's analyzers.

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 on how to integrate Atlas into your GitHub Actions or GitLab CI pipelines.

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