Rehearse a Postgres schema change

Ship schema changes that stay readable by the previous application until you retire it. Bex pre-deploy commands run the new image before promotion, keep the previous Deployment while the gate runs, and block that revision on failure. Image rollback does not undo schema or data.

This page points at a downloadable rehearsal you can run on local disposable Postgres 16 — never against a customer database.

What the sample rehearses​

The postgres-schema-rollout example renames notes.display_name to notes.title in stages:

1. initial — v1 serves display_name
2. add_title — add nullable title (both versions can dual-write)
3. backfill_title — copy values and require title
4. cleanup_display_name — drop display_name only after every v1 replica is gone

npm run migrate takes a Postgres advisory lock with finite lock and statement timeouts and stays under the platform's ten-minute pre-deploy deadline. Long backfills that cannot finish in that window need a separately planned, resumable procedure — do not hide them behind a command that exits early.

Run the rehearsal​

curl -fsSLO https://bex.co/examples/postgres-schema-rollout-latest.zip
curl -fsSLO https://bex.co/examples/postgres-schema-rollout-latest.zip.sha256
shasum -a 256 -c postgres-schema-rollout-latest.zip.sha256
unzip postgres-schema-rollout-latest.zip
cd postgres-schema-rollout
npm install
export DATABASE_URL=postgres://rollout:rollout@127.0.0.1:55432/rollout
npm run setup
npm run migrate -- --to backfill_title
npm test
npm run teardown -- --container

The sample refuses non-local connection strings and database names that do not look like rehearsal/tmp/test fixtures.

Attach to a Blueprint​

See render.yaml in the sample for a preDeployCommand: npm run migrate shape with a Postgres connectionString env binding. Confirm migrate exit codes and /healthz before enabling auto-deploy on a real service.

Related​

• Pre-deploy commands
• Postgres
• Rollbacks
• CI image deploy