Release Phase (Beta)

Last updated 12 September 2016

Release phase (beta) enables you to run scripts or executables in a slug when a new release is created. You may find release phase useful for tasks such as:

• Sending CSS, JS, and other assets from the slug to a CDN or S3 bucket
• Priming or invalidating cache stores
• Running database schema migrations

Defining a release command

Heroku will run the command defined by the release process type in your Procfile. A one-off dyno will be started to run the command and it can run for up to 24 hours.

In this Procfile example, release executes a Django database migration:

release: python manage.py migrate
web: gunicorn myproject.wsgi --log-file -

In this Procfile example, release copies static assets to a CloudFront S3 bucket:

release: aws s3 cp staticfiles/*.* s3://<bucket-name>/staticfiles/
web: gunicorn myproject.wsgi --log-file -

When does the release command run?

The release command is run immediately after a release is created, but before the release is deployed to the app’s dyno formation. That means it will be run after an event that creates a new release:

• An app build
• A pipeline promotion
• A config var change
• A rollback
• A release via the platform API

The app dynos will not boot on a new release until the release command finishes successfully.

If the release command exits with a non-zero exit status, or if it’s shut down by the dyno manager, the release will be discarded and will not be deployed to the app’s formation.

Checking release status & debugging

To check on the status of a release, including failed releases and those pending due to a long running release command, run heroku releases.

$ heroku releases
=== limitless-savannah-19617 Releases - Current: v52
v53  Deploy ad7c527 release command failed        jbyrum@heroku.com
v52  Deploy b41eb7c                               jbyrum@heroku.com
v51  Deploy 38352d3                               jbyrum@heroku.com
...

To check the status of a release programmatically, you can curl the Platform API for a specific release, or list all releases (see Platform API documentation for more detail). In the following example, the status key has a value of failed:

$ curl -n https://api.heroku.com/apps/<app_id_or_name>/releases/ \
          -H "Accept: application/vnd.heroku+json; version=3"

{
    "app":{
      "id":"a933b6af-b2e3-4a03-91a9-1c758110a553",
      "name":"limitless-savannah-19617"
    },
    "created_at":"2016-07-29T22:43:20Z",
    "description":"Deploy ad7c527",
    "status":"failed",
    "id":"735a9e8c-ef49-4047-8079-984d40a84051",
    "slug":{
      "id":"a49ed40f-801a-45ff-8b90-758c5a33637f"
    },
    "updated_at":"2016-07-29T22:43:20Z",
    "user":{
      "email":"jbyrum@heroku.com",
      "id":"cbcd34ce-c556-4289-8bc7-2dc160649fb7"
    },
    "version":53,
    "current":true
  }

You can see the output of running the release command with the heroku logs command or wherever you currently inspect your Heroku app logs.

Canceling a release command

To cancel a release command, you should find the one-off dyno executing the command:

$ heroku ps
=== release (Free): bundle exec rake db:migrate
release.5129: up 2016/02/01 12:17:45 (~ 2s ago)

Now terminate the dyno, substituting the dyno name:

$ heroku ps:stop release.5129

Design considerations

Not suggested for asset compilation or other tasks requiring filesystem persistence

Release phase is not suitable for tasks that require filesystem persistence, as filesystem changes during release phase will not be deployed to your app’s dyno formation (the dyno filesystem is ephemeral). Asset compilation should happen during builds. Release phase can be used to upload the compiled assets to a CDN.

Use transactions for database migrations

If you perform a database migration, you should always use transactions. A transaction ensures that all migration operations are successful before committing changes to the database. This minimizes the possibility of a failed partial migration during release phase. If a database migration fails during release phase (i.e., the migration command exits with a non-zero status), your new release will not be deployed. If transactions were not used, this can leave your database in a partially migrated state. We suggest using heroku run, rather than release phase, to correct your schema/data.

Check whether a database has already been migrated, before executing a migration

Many actions create a new release, such as a setting a config var or adding a new addon to your app. Your database migration script should check whether a database has already been migrated, before executing a new migration (e.g., does table/column exist, if not add it). This will prevent a new release – such as one created from a new config var – from rerunning your database migration.

Before running a migration, grab an advisory lock on the database

Heroku releases can run concurrently, which can be a problem if release phase is executing a database migration. Many popular relational databases, such as Postgres and MySQL, offer advisory lock functionality, which can be used to prevent concurrent migrations. Advisory locks are application enforced database locks; when acquired, your tables are not locked for writing, so your application will continue to behave normally.

In Postgres, before running your migration, you can acquire an advisory lock. In the example below we try to get an advisory lock with the key migration:

SELECT pg_try_advisory_lock(migration);

If the lock is successful, Postgres will return t. Now it should be safe to run your migration. If unsuccessful, f is returned and you can fail your migration.

If the advisory lock is acquired within a transaction, it will be automatically released when the transaction is committed. You can also release a lock by calling:

SELECT pg_advisory_unlock_all();

or

SELECT pg_advisory_unlock(key);

Known issues

• Deploy hooks will send a deployment success message, when release phase fails. This will be fixed for GA.
• Release phase currently only works in the Common Runtime. It cannot be used in Private Spaces, however we are working on support for general availability.
• It is possible for a release command to fail due to an add-on not being fully provisioned when the command is run; for example, you’re trying to run a db migration, but the db add-on isn’t finished with provisioning. You can work around this issue with the addon-wait tool, or its buildpack equivalent if you’re using review apps.
• When running addons:create a new release is created. It is possible for the release command to fail, but the CLI will output a success message.
• Review apps provide the ability to run a postdeploy script. We suggest using either a postdeploy script or release phase, but not both, as they may run out of sequence.