Migration Directory Import

Atlas supports the generation of custom migration file formats for a variety of existing migration management tools, e.g. Flyway or golang-migrate/migrate. But Atlas has its own format as well and provides a convenient command to import existing migration directories of supported tools into the Atlas format.

Flags

When using atlas migrate import to import a migration directory, users must supply multiple parameters:

• --from the URL to the migration directory to import, the format query parameter controls the migration directory format, e.g. file://migrations?format=flyway. Supported formats are atlas (default), golang-migrate, goose, flyway, liquibase and dbmate.
• --to the URL of the migration directory to save imported migration files into, by default it is file://migrations.

Limitations

Importing an existing migration directory has some limitations:

Comments not directly preceding a SQL statement will get lost.

source.sql

-- This comment will get lost

-- This will be preserved
/*
    This will be preserved as well
/*
CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
); -- This will get lost.

imported.sql

-- This will be preserved
/*
    This will be preserved as well
/*
CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
);

Rollback migrations will not get imported.

Atlas does not have the concept of rollback migrations. Therefore migrations to undo an applied migration, often called "down" or "undo" migrations, will not be imported into the new migration directory. For migration formats having the rollback migration part of one file separated by some directive, the rollback parts are stripped away.

source.sql

-- +goose Up
CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
);

-- +goose Down
DROP TABLE `users`;

imported.sql

CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
);

Repeatable Migrations

Flyway has the concept of repeatable migrations, however, Atlas does not. In Flyway repeatable migrations are run last, if their contents did change. Atlas tries to reproduce this behavior by creating versioned migrations out of each repeatable migration file found and giving them the character R as version suffix.

V1__users.sql

CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
);

R__users_view.sql

CREATE VIEW `users_over_30` AS SELECT * FROM `users` where `age` > 30;

1_users.sql

CREATE TABLE `users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `age` bigint(20) NOT NULL,
    `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `age` (`age`)
);

1R_users_view.sql

CREATE VIEW `users_over_30` AS SELECT * FROM `users` where `age` > 30;

Examples

Import existing golang-migrate/migrate migration directory:

atlas migrate import \
  --from "file://migrations?format=golang-migrate" \
  --to "file://atlas-migrations"

Import existing Flyway migration directory:

atlas migrate import \
  --from "file://migrations?format=flyway" \
  --to "file://atlas-migrations"

Reference

CLI Command Reference