Verifying migration safety

With the atlas migrate lint command, users can analyze the migration directory to detect potentially dangerous changes to the database schema. This command may be incorporated in continuous integration pipelines to enable teams to enforce desired policies with regard to schema changes.

Learn more about Atlas's analyzers

Flags

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

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

Changeset detection

When we run the lint command, we need to instruct Atlas on how to decide what set of migration files to analyze. Currently, two modes are supported.

• --git-base <branchName>: which selects the diff between the provided branch and the current one as the changeset.
• --latest <n> which selects the latest n migration files as the changeset.

nolint directive

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

All changes

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;

Class of changes

Using --atlas:nolint [names...] excludes reporting specific analyzers for the annotated statements.

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

-- Ignore reporting destructive and data-dependent changes.
--atlas:nolint destructive data_depend
ALTER TABLE `t2` DROP COLUMN `c2`, ADD COLUMN `d2` varchar(255) NOT NULL;

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

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

Specific checks

Using --atlas:nolint [checks...] excludes reporting specific checks for the annotated statement.

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

File level

The --atlas:nolint directive can be used to exclude the whole file (given at top) from analysis, or to exclude specific statements in the file from specific checks or analyzers.

-- atlas:nolint

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

DROP TABLE `t2`;

Skip a specific analyzer for all statements in the file:

-- atlas:nolint destructive

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

DROP TABLE `t2`;

note

File directives are located at the top of the file and should not be associated with any statement. Hence, double new lines are used to separate file directives from its content.

Output

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

Examples

Analyze all changes relative to the master Git branch:

atlas migrate lint \
  --dir "file://my/project/migrations" \
  --dev-url "mysql://root:pass@localhost:3306/dev" \
  --git-base "master"

Analyze the latest 2 migration files:

atlas migrate lint \
  --dir "file://my/project/migrations" \
  --dev-url "mysql://root:pass@localhost:3306/dev" \
  --latest 2

Format output as JSON:

atlas migrate lint \
  --dir "file://my/project/migrations" \
  --dev-url "mysql://root:pass@localhost:3306/dev" \
  --git-base "master" \
  --format "{{ json .Files }}"

Use the configuration defined in atlas.hcl:

atlas migrate lint --env "local"

Reference

CLI Command Reference