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 on platformatic.db.json
• get the MIGRATION_NUMBER (f.e. if the file is named 002.do.sql will be 002)
• run npx platformatic db migrations apply --to MIGRATION_NUMBER