The short answer

Database migrations on deploy are one release step. They run once, before the new version takes traffic. They are not part of the image build, and they are not part of starting each replica.

A rollback of that code does not undo the schema. There is no command that puts the database back. You design the change so the previous release still works: expand, copy the data, then contract. On Unbroker the release step is the pre-deploy command, and migration commands require Pro.

Where the database itself runs is a separate choice, a container you operate or a managed cluster. That map is Docker Compose in production and managed Postgres. Operating the server is Postgres in production.

Three places to run database migrations on deploy

People run the migration in one of three places. Two of them break once you have more than one build, or more than one copy of the app.

Migrations in the Docker build

The Dockerfile runs the migration while the image is built. That happens on every build, not once for the release that is about to go live.

The Django guide says to run database migrations once, as a controlled release step, with the required runtime credentials. It says to avoid putting migrations in the Docker image build. The FastAPI guide says not to run migrations during image building.

On startup of every replica

The process migrates, then serves. Each copy does that. Those copies can run at the same time and compete for the same schema change. The Django guide says to avoid running competing migrations in every web process.

Once, before the new version is live

One command, from the new image, before traffic reaches it. That is the release step. Run migrations before deploy, not after the new code is already serving. On Unbroker that command is the pre-deploy command. On Heroku that step is the release line in the Procfile. The map of each line is a Heroku Procfile, line by line.

What the pre-deploy command should do

The command applies the schema once and then exits. Write it so a second run does nothing when the schema is already at that version. A later release may call it when there is nothing new to apply.

Set lock_timeout in the session that runs the migration, so a lock wait ends instead of sitting on the table. Do not set it in postgresql.conf. PostgreSQL says that would affect every session. The default is 0, which disables the timeout. If you omit the unit, the number is milliseconds. The '1s' below is an illustration of the syntax, not a PostgreSQL default and not an Unbroker setting.

SET lock_timeout = '1s';

If the migration fails, the command should exit with a non-zero status. Print which migration ran and the error. Do not print the connection string. Then read the deployment log for that run. The docs and the changelog do not say what a failed pre-deploy command does to the version that is already live.

Keep secrets in environment variables, not in the command string. The post-deploy section of the deployments docs states that rule for the post-deploy command, and it says the command itself is not printed in the log. Use the same habit for the pre-deploy command. The changelog example is npm run db:migrate.

A rollback does not undo a database migration

ubctl apps rollback promotes a known deployment. It does not rebuild the source commit. The deployments docs show it with a service id and a deployment id:

ubctl apps rollback svc_123 dep_previous

Those two arguments are the service and the deployment you are promoting. Rollbacks do not run the pre-deploy command again, so the migration has to stay compatible with the previous code. That is the August 1 changelog.

Rolling back an image does not undo configuration changes, database writes, volume data, or external side effects. The infrastructure-as-code docs say to keep rollback separate from database migrations. A restore you have actually run is still the way back to old rows. That check is in Postgres in production.

Expand and contract, one release at a time

A rename is the usual case. You want name to become full_name. Doing the code change and the drop in one release means a rollback boots the old code against a column that is already gone.

This is the parallel change pattern, also called expand and contract. An expand and contract migration breaks the change into three phases: expand, migrate, then contract. Each release has to work with the previous one.

  1. Expand. Add full_name. The new code writes both columns and still reads name. The old code only knows name, so a rollback still runs.
ALTER TABLE users ADD COLUMN full_name text;

Adding a column with a non-volatile default stores that value in the table metadata and does not rewrite the table. With no default, PostgreSQL uses NULL and also skips the rewrite. A volatile default, such as clock_timestamp(), rewrites the table and its indexes. Most forms of ALTER TABLE take an ACCESS EXCLUSIVE lock unless the docs note a weaker one. The lock section is below.

  1. Migrate. Copy existing rows in batches, with a one-off command or a scheduled job, not inside each web request. The new code reads full_name and still writes name, so a rollback to the expand release still sees new writes in name.
UPDATE users
SET full_name = name
WHERE id IN (
  SELECT id FROM users
  WHERE full_name IS NULL
  LIMIT 1000
);

The 1000 is a batch size for the illustration. It is not a PostgreSQL setting. Repeat until no row is left with full_name null.

  1. Contract. The new code reads and writes only full_name. Leave name in place. Drop it in a later release, after you will not roll back to a release that still reads or writes it.
ALTER TABLE users DROP COLUMN name;

DROP COLUMN makes the column invisible to SQL. It does not immediately shrink the table on disk. Later updates reclaim that space as they rewrite rows. The source for the column and drop behavior is ALTER TABLE.

Postgres operations that lock

An ALTER TABLE takes an ACCESS EXCLUSIVE lock unless the form you use says otherwise. Several subcommands in one statement take the strictest lock any of them needs.

ADD FOREIGN KEY is one exception: it takes SHARE ROW EXCLUSIVE on the table you alter and on the referenced table. Adding a check or not-null constraint scans the table, and other updates wait until that statement commits. NOT VALID skips that scan. A later VALIDATE CONSTRAINT takes SHARE UPDATE EXCLUSIVE and does not lock out concurrent updates. The source is ALTER TABLE.

A normal CREATE INDEX locks out writes, and not reads, until the build finishes. CREATE INDEX CONCURRENTLY does not take locks that block inserts, updates, or deletes. It takes longer, because PostgreSQL scans the table twice and waits for transactions that could still use the index. It cannot run inside a transaction block. A regular CREATE INDEX can. A migration runner that wraps the file in one transaction cannot put CREATE INDEX CONCURRENTLY inside that transaction.

CREATE INDEX CONCURRENTLY users_full_name_idx ON users (full_name);

If the concurrent build fails, PostgreSQL can leave an invalid index behind. That index is ignored for queries and still adds overhead on updates. The recovery in the docs is to drop it and run CREATE INDEX CONCURRENTLY again, or to rebuild it with REINDEX INDEX CONCURRENTLY. Only one concurrent index build can run on a table at a time. Concurrent builds on a partitioned table are not supported. You can build the index concurrently on each partition, then create the parent index without CONCURRENTLY. That parent step is metadata only. The source is CREATE INDEX.

lock_timeout aborts a statement that waits longer than the limit while acquiring a lock. The limit applies separately to each lock attempt. It applies to explicit locks and to locks the statement takes on its own. Unlike statement_timeout, it only fires while waiting for a lock. If statement_timeout is set and is shorter or equal, it fires first, so a longer lock_timeout does nothing useful. Do not set lock_timeout in postgresql.conf. The source is client connection defaults.

Keep the data backfill out of the release step

Adding a column and copying every existing row are different jobs. The column belongs in the release step. The copy belongs in a one-off command or a scheduled job, in batches, so one statement is not one long transaction.

A transaction that stays open keeps old row versions visible, and vacuum cannot treat them as garbage yet. That is the long-transaction check in Postgres in production. A migration is also another client against max_connections. Count it with the other clients on that page.

Pre-deploy and post-deploy

Use the pre-deploy command for the migration. It runs once from the new image before that version goes live. Rollbacks do not run it again.

Use the post-deploy command for work that can wait until the new version is already serving, such as a cache purge or a notification. It runs in a one-off copy of the new image, with that service’s environment variables, for at most 10 minutes. The output is appended to the deployment log.

If the post-deploy command fails, the deployment stays live and nothing is rolled back. The failure is in the deployment log. The command does not run when the deploy itself fails. It does not mount a persistent volume. It requires a paid plan, and it is not available for image services. Put secrets in variables, not in the command string. The sources are the deployments docs and the October 26 changelog.

A migration does not belong there. The new code would already be taking traffic, and a failed command would leave that release live.

Test the migration before production

Test the migration on a disposable copy before you apply it to production. The Django guide says that.

A pull request preview is a place to do it, pointed at a database you can throw away. Unbroker does not document a database created for each preview. You choose the database with a Preview-scoped variable. A migration against a shared staging database changes that schema for every other preview. A migration against production changes production. The longer note is pull request preview environments.

How this works on Unbroker

In Settings, a service can set a pre-deploy command such as npm run db:migrate. It runs once from the new image before that version goes live. Rollbacks do not run it again, so keep the migration compatible with the previous code. The August 1 changelog is that release. On October 8 the interactive terminal was removed. One-off commands and scheduled jobs stayed. A one-off command runs once, with the service’s image and variables. A scheduled job has a name, a cron schedule, a command, and a timezone. Each run’s output is under Executions. Choosing a worker, that schedule, or a one-off command is Background workers and cron jobs.

@unbroker/iac v0.2.0 maps preDeploy. Changing the pre-deploy command is a rebuild of the live commit, so a config-only apply does not release a newer branch HEAD. Post-deploy is not in that schema. Set postDeployCommand in the dashboard, or with PATCH /apps/services/:id. Changing the post-deploy command marks the service for redeploy. The infrastructure-as-code docs and the deployments docs are the source.

Pre-deploy and post-deploy commands share the service’s environment isolation and can reach its private databases. That sentence is in service types.

The plans page lists migration commands, one-off commands, and scheduled jobs as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Prices are on pricing.

Checklist

  1. Run the migration once, before the new version is live.
  2. Keep it out of the Docker image build. The Django and FastAPI guides say so.
  3. Keep it out of the start command of every replica.
  4. Make a second run do nothing when the schema is already current.
  5. Set lock_timeout on that session. Leave postgresql.conf alone.
  6. Put secrets in variables, not in the command. Do not print the connection string.
  7. Expand, copy rows in batches, then contract. Drop the old column only when you will not roll back to code that needs it.
  8. Put a large backfill in a one-off command or a scheduled job.
  9. Test on a disposable copy. Point previews at a database that is not production.
  10. Treat a rollback as a previous deployment, not a previous schema. Keep a restore you have run.
  11. On Unbroker, migration commands require Pro. The Django path is Deploy Django. What changes after runserver is Django in production.

FAQ

Should I run migrations in my Dockerfile?

No. The Django guide says to avoid putting migrations in the Docker image build. The FastAPI guide says not to run migrations during image building. Run them once, as a release step, with the runtime credentials, before the new version is live.

Does a rollback revert my database migration?

No. `ubctl apps rollback` promotes a known deployment and does not rebuild the source commit. Rollbacks do not run the pre-deploy command again. Rolling back an image does not undo configuration changes, database writes, volume data, or external side effects.

What if the pre-deploy migration fails?

Read the deployment log for that run. The docs and the changelog do not say what a failed pre-deploy command does to the version that is already live. Write the command so a failed migration exits non-zero, so the failure shows up in that log.

Can I run migrations on the Free plan?

No. The plans page lists migration commands as not available on Free and available on Pro. One-off commands and scheduled jobs are the same. Pro is $25 a month with $25 of usage credit. See pricing.

Should migrations use the pre-deploy or the post-deploy command?

Pre-deploy. It runs once from the new image before that version goes live. Post-deploy runs after the version is already serving. If the post-deploy command fails, the deployment stays live and nothing is rolled back.