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 isfile://migrations
, e.g a directory namedmigrations
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
- Class of changes
- Specific checks
- File level
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;
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;
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;
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`;
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"