# Database migrations (experimental feature)

Database migrations exist to run one-time queries against the database, typically to modify the tables structure or the data when upgrading the Strapi application.

🚧 Experimental

The feature is to be considered as unfinished and experimental.

# General logic

Migrations are run using JavaScript migration files stored in ./database/migrations.

Migration files should export 2 functions up() and down().

  • The up() function is used when upgrading (e.g. adding a new table my_new_table).
  • The down()function is used to reverse the up() function when downgrading (ex: deleting my_new_table)

Strapi will automatically detect migration files and run them once at the next startup in alphabetical order. Every new file is executed once.

Migrations are run before the database tables are synced with the content-types schemas.

There is no CLI to run the migration manually for the moment.

There are no ways to use the downgrade feature for the moment, hence, the down()is not usable for the moment.

up() and down() functions run in a database transaction which means if a query fails during the migration, the whole migration will be cancelled and no changes will be applied to the database. It also means that if an other transaction is created within the migration function, it will be a nested transaction.

# Creating a migration file

To create a migration file:

  1. In the ./database/migrations folder, create a new file named after the date and the name of the migration (e.g. 2022.05.10T00.00.00.name-of-my-migration.js). Make sure that the file name follows this naming pattern, because the alphabetical order of the files defines the order in which the migrations have to run.

  2. Copy and paste the following template in the previously created file:

'use strict'

async function up(trx) {}

async function down(trx) {}

module.exports = { up, down };
  1. Fill in the template by adding actual migration code inside the up() and down() functions. up() and down() receive a Knex instance (opens new window) that can be used to run the database queries.

← React →