---
id: new
slug: /versioned/new
title: Manual Migrations
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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](https://dev.mysql.com/doc/refman/8.0/en/mysql-commands.html)

<Tabs
defaultValue="migration_file"
values={[
{label: 'Migration file', value: 'migration_file'},
{label: 'Scanned statements', value: 'statements'},
]}>
<TabItem value="migration_file">

```sql {1,7-8}
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)
```

</TabItem>
<TabItem value="statements">

Statement 1:

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

Statement 2:
```sql
CALL dorepeat(100);
```

</TabItem>
</Tabs>


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

<Tabs
defaultValue="migration_file"
values={[
{label: 'Migration file', value: 'migration_file'},
{label: 'Scanned statements', value: 'statements'},
]}>
<TabItem value="migration_file">

```sql
//highlight-next-line-info
-- 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);
```

</TabItem>
<TabItem value="statements">

Statement 1:

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

Statement 2:
```sql
CALL dorepeat(1000);
```

</TabItem>
</Tabs>


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

<Tabs
defaultValue="migration_file"
values={[
{label: 'Migration file', value: 'migration_file'},
{label: 'Scanned statements', value: 'statements'},
]}>
<TabItem value="migration_file">

```sql
//highlight-next-line-info
-- 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);
```

</TabItem>
<TabItem value="statements">

Statement 1:

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

Statement 2:
```sql
CALL dorepeat(1000);
```

</TabItem>
</Tabs>

### 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:
```shell
atlas migrate new --edit
```

Create a new migration file named "add_user":
```shell
atlas migrate new add_user
```

Create a new migration file in a specific directory:
```shell
atlas migrate new --dir "file://custom/path/to/dir"
```


