Run migrations | Release | Northflank Application docs

Release /

Run migrations

When you make changes to your database schema you may need to update your application and change your production database simultaneously.

You can handle database schema migrations on Northflank in various ways:

  • By configuring a release flow, which automatically runs a migration and then promotes the deployment only when the migration is successful (recommended)
  • Using a job triggered by CI
  • Restarting your deployment with command overrides
  • Executing commands in a container's shell

We recommend using release flows to automate your migration process, especially for production deployments, as this makes the process easy and ensures the migration has run before deploying your updated application.

To release a new version of your application with a migration it is recommended you follow the workflow:

  1. Back up your database, in case you need to restore it
  2. Run your migration
  3. If the migration is successful, deploy the new release to the deployment service

If your updated application is deployed before the migration has completed it may crash or not function as expected, and you may need to redeploy it.

Migrate using a release flow

You can handle a migration with a release flow by creating and populating a pipeline with your relevant deployments and database addons.

You can then configure a release flow to automate the various steps of your release workflow.

You could create, for example, a sequential workflow that backs up the database, executes your migration, and then promotes the deployment. The migration could be executed by using a job node to run a job with your migration code, or by using an action node to execute a command in a running container.

An example release flow to run a migration in the Northflank application

Migrate using a job triggered by CI

You can run a migration automatically by configuring a job to run whenever a new build is completed.

You can:

  • build directly from the same repository and branch as the deployment that requires migration, with CI and CD enabled on the job
  • deploy an image from a build service that also builds the image for your deployment service, with CD enabled

Create a new manual job with the source for your migration code, either from a repository or a build service. Enable run on image change on your job, select CD & pipeline promotion or always, depending on your desired workflow.

Enter any necessary configuration details to run your migration, for example a command override if your migration code needs to be called with a command other than the default.

Your job will now execute when your latest commit to the repository is built, so your migration should occur at the same time as your new deployment. You can check the logs for the job run to ensure it has executed successfully.

Configuration settings for a job in the Northflank application to run a migration when a new build is available

Migrate using command override

You can run a migration using command override to execute the migration code when deploying your latest commit. This allows you to chain commands to run a migration and then start your application whenever it is redeployed.

Your deployment will begin redeploying as soon as you save the custom command.

Enter command manually

## Run migration, then start the server
bin/sh -c "node migrate/migration-code.js; node built/server.