Skip to main content

Manual Migrations

In some cases it is desirable to add a migration file manually. This could be done to provision resources that Atlas does not yet capture in its DDL (such as triggers and views) or to seed data with INSERT statements.

To manually add a new migration file to the directory use the migrate new command.

Flags​

When using migrate new to create a new migration file users may supply the following flags:

  • --dir the URL of the migration directory, by default it is file://migrations, e.g a directory named migrations in the current working directory.

Migration name​

Users may optionally add a final positional argument to set the name of the migration file. This name will be appended to the migration version number in the filename as such: <version>_<name>.sql.

Custom statements delimiter​

The semicolon character (;) is recognized by Atlas as a statement delimiter. In some cases, however, the delimiter may need to be redefined because the semicolon itself is used in one of the DDL statements. For example, a stored program containing semicolon characters.

Using the DELIMITER command used by MySQL client​

DELIMITER //
CREATE PROCEDURE dorepeat(p1 INT)
    BEGIN
    SET @x = 0;
    REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
END
//
DELIMITER ;
CALL dorepeat(100)

Using the atlas:delimiter directive to set \n\n\n as a separator:​

-- atlas:delimiter \n\n\n

CREATE PROCEDURE dorepeat(p1 INT)
BEGIN
    SET @x = 0;
    REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
END;


CALL dorepeat(1000);

Using the atlas:delimiter directive to set -- end as a separator:​

-- atlas:delimiter -- end

CREATE PROCEDURE dorepeat(p1 INT)
BEGIN
    SET @x = 0;
    REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
END;
-- end
CALL dorepeat(1000);

Recalculating the directory hash​

Atlas maintains a file named atlas.sum in the migration directory. This file is used to ensure the integrity of the migration directory and force developers to deal with situations where migration order or contents was modified after the fact.

After manually editing the contents of a newly created migration file, the checksums for the directory must be recalculated. This can be done by running atlas migrate hash command.

Examples​

Create and edit a new migration file:

atlas migrate new --edit

Create a new migration file named "add_user":

atlas migrate new add_user

Create a new migration file in a specific directory:

atlas migrate new --dir "file://custom/path/to/dir"