Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Deployment and Releases

Release Phase and Database Migrations

Use the Heroku release phase to run database migrations and other tasks before new code goes live, understand what happens when it fails, and make migrations safe to rerun.

Almost every real app has a step that must happen after the build but before the new version starts serving traffic: apply database migrations, rebuild a search index, warm a cache. If you do that by hand (heroku run python manage.py migrate after a deploy) there is a window where new code runs against the old schema, and a human has to remember the step every time.

Heroku solves it with the release phase: a command that runs automatically on every deploy, in between the build and the release. If it fails, the release is cancelled.

Defining a release command

Add a release process type to the Procfile:

TEXT
web: gunicorn mysite.wsgi
release: python manage.py migrate --noinput

Examples for other stacks:

TEXT
# Rails
release: bundle exec rails db:migrate
# Node with a migration tool
release: npm run migrate
# Laravel
release: php artisan migrate --force

When you push, the sequence becomes:

flowchart LR
  A["Build slug"] --> B["Release phase<br/>runs 'release' command"]
  B -->|"exit 0"| C["New release goes live<br/>dynos restart"]
  B -->|"non-zero exit"| D["Release cancelled<br/>old release keeps running"]

A failed release phase leaves the previous release serving traffic. Nothing half-deployed reaches users.

How it behaves

  • The command runs in a one-off dyno with the new slug and the app's config vars, so it can reach the database through DATABASE_URL.
  • Output streams to your terminal during git push, and you can read it later with heroku releases:output.
  • A non-zero exit code aborts the release. The app keeps running the old release, and the failed release appears in heroku releases with a failed status.
  • The command has a time limit (about an hour), but you should keep it short; long migrations block deploys.
  • The release dyno has no access to a filesystem that persists, like any dyno, and it cannot use heroku run-style interactive input.
  • The release type is not part of your normal formation: you do not scale it.

It runs on deploys. For when else it runs (for example for particular kinds of config or add-on changes), read the Dev Center article for the current rules instead of relying on memory.

Migrations must be rerunnable and compatible

Because the release command runs on every deploy, a good migration tool tracks which migrations it has already applied and applies only new ones. Django, Rails and most migration tools do that with a bookkeeping table in your database.

During a deploy there is an overlap: the release phase changes the schema while the old dynos are still serving requests, and only then do new dynos start. So the new schema must be compatible with the old code. The safe pattern is expand then contract:

Step Release 1 Release 2 Release 3
Rename name to full_name Add full_name, code writes both Backfill, code reads full_name Drop name

Dropping a column that old code still reads, in the same deploy, breaks the old dynos for the seconds they are alive, and it also makes a rollback unsafe.

Beyond migrations

Other good uses of the release phase: building a search index, copying a static data file into the database, checking that required config vars exist, and failing the deploy early if they do not. A tiny release script that verifies configuration saves you from broken dynos:

TEXT
release: python scripts/release.py

Do not use it for long-running jobs or anything that must run only once per business event; it runs on each deploy.

Stand-in: a migration runner with bookkeeping

This stand-in uses Python's built-in SQLite in memory to show how a tool applies only new migrations. Running it again does nothing, which is what makes the release command safe to run on every deploy.

Python Stand-in: apply only new migrations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Deploy 2 applies nothing. Deploy 3 applies only the new migration.

Stand-in: the release pipeline decision

This model captures the decision the platform makes: only a successful release command lets the new release take over. It also prints which release is serving traffic.

Python Stand-in: a failed release phase keeps the old release

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical checklist

  1. Put migrations in the release command, not in the web command (otherwise every dyno tries to migrate at start).
  2. Make each migration quick; avoid locks on large tables during business hours.
  3. Test migrations on a copy of production-like data on a review app or staging app.
  4. Prefer additive changes; remove columns in a later release.
  5. Read heroku releases:output when a deploy is cancelled.

Never run destructive commands in release by default. A line such as rails db:reset or migrate:fresh would run on every deploy and wipe your data. Use only forward, idempotent operations.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does the release phase command run?

    The release phase sits between build and release. If it succeeds, the new release goes live.
  2. 2. What happens if the release command exits with a non-zero code?

    A failed release phase cancels the release, so a broken migration never reaches users.
  3. 3. Why should a migration be compatible with the old code?

    During the deploy, old dynos keep running while the release command changes the database.
  4. 4. Where can you read the output of a past release phase?

    heroku releases:output shows the release command output for a release.

Summary

  • Define release: in the Procfile to run migrations and similar tasks before new code goes live.
  • A failed release command cancels the release and leaves the old release running.
  • Migrations must be rerunnable and compatible with the previous code version (expand, then contract).
  • Read heroku releases:output to debug a cancelled release.

Next: Container deploys with Docker