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 workflow, which automatically runs a migration and then deploys 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 workflows 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 this 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.

You can add a migration step to your workflow to run database migrations automatically as part of your deployment process.

1. Open your workflow in the visual editor

2. Add a Run job node after your build node and before your deployment node

3. Configure the job node:

   • Job: Select or create a job that runs your migration script
   • Build: Use the same build as your deployment
   • Environment variables: Include database connection details from secret groups

4. Connect the migration node between your build and deployment nodes

5. Click Save workflow

This ensures migrations run after building but before deploying the new code.

Create a dedicated job for running migrations:

1. Navigate to Jobs

2. Click Create job

3. Configure:

   • Name: e.g., run-migrations
   • Build source: Same repository as your application
   • Command: Script that runs your migrations (e.g., npm run migrate, python manage.py migrate, rake db:migrate)
   • Environment variables: Database credentials from addon secret groups

4. Click Create job

The job is now available to use in workflow migration nodes.

Run before deployment

Place the migration node before the deployment node. New schema is applied before the updated service starts.

Use when new code requires new schema, migrations add columns or tables, or downtime is acceptable.

Run after deployment

Place the migration node after the deployment node. New code deploys first, then schema is updated.

Use when old code works with new schema, migrations are backwards compatible, or zero downtime is required.

Separate migration workflow

Create a dedicated workflow for migrations, separate from deployment workflows.

Use when migrations take a long time, you want manual control over when migrations run, or multiple services share the same database.

Make migrations backwards compatible:

Add new columns as nullable initially. Deploy code that works with both old and new schema. Run migration after deployment. Deploy code that requires new columns. Make columns non-nullable if needed.

Test migrations:

Run migrations in preview environments first. Verify migrations work with test data. Check migration rollback procedures.

Monitor migrations:

View migration logs in the job run. Set up alerts for migration failures. Track migration execution time.

Backup before migrations:

Add a backup node before the migration node. Restore from backup if migration fails. Keep backups of pre-migration state.

A safe migration workflow:

1. Start build node: Build application code
2. Run backup node: Backup database before migration
3. Run job node: Execute database migration
4. Condition node: Check if migration succeeded
5. Deploy build node: Deploy new code only if migration succeeded
6. Run action node: Restart services if needed

This pattern ensures migrations are applied safely with backup and failure handling.

If a migration causes issues:

1. Navigate to the workflow run

2. Find the backup created before the migration

3. Run a new workflow to restore from the backup

4. Deploy the previous version of your code

Some migration frameworks support automatic rollback. Configure your migration job to support rollback commands.