Migrations
It uses Postgrator under the hood to run migrations. Please refer to the Postgrator documentation for guidance on writing migration files.
In brief, you should create a file structure like this
migrations/
|- 001.do.sql
|- 001.undo.sql
|- 002.do.sql
|- 002.undo.sql
|- 003.do.sql
|- 003.undo.sql
|- 004.do.sql
|- 004.undo.sql
|- ... and so on
Postgrator uses a table in your schema, to store which migrations have been already processed, so that only new ones will be applied at every server start.
You can always rollback some migrations specifing what version you would like to rollback to.
Example
$ platformatic db migrations apply --to 002
Will execute 004.undo.sql
, 003.undo.sql
in this order. If you keep those files in migrations directory, when the server restarts it will execute 003.do.sql
and 004.do.sql
in this order if the autoApply
value is true, or you can run the db migrations apply
command.
It's also possible to rollback a single migration with -r
:
$ platformatic db migrations apply -r
How to run migrations
There are two ways to run migrations in Platformatic DB. They can be processed automatically when the server starts if the autoApply
value is true, or you can just run the db migrations apply
command.
In both cases you have to edit your config file to tell Platformatic DB where are your migration files.
Automatically on server start
To run migrations when Platformatic DB starts, you need to use the config file root property migrations
.
There are two options in the "migrations"
property
dir
(required) the directory where the migration files are located. It will be relative to the config file path.autoApply
a boolean value that tells Platformatic DB to auto-apply migrations or not (default:false
)
Example
{
...
"migrations": {
"dir": "./path/to/migrations/folder",
"autoApply": false
}
}
Manually with the CLI
See documentation about db migrations apply
command
In short:
- be sure to define a correct
migrations.dir
folder under the config onplatformatic.db.json
- get the
MIGRATION_NUMBER
(f.e. if the file is named002.do.sql
will be002
) - run
npx platformatic db migrations apply --to MIGRATION_NUMBER