A rollback plan before you deploy: version, migrations, checks
From the work/ 10 min read
Write the way back before the deploy: which version, a database the old code survives (expand and contract), and a script that decides. Tested on PGlite.
- Databases
- Migration
- QA
In this article (8)
A rollback plan is a short note you write before you deploy: which version you will return to, how you return, whether the database still works with the old code, and which checks decide it. A few lines written while nothing is broken turn a bad deploy into a routine step instead of an argument.
The examples use a Node web app on a platform that keeps the previous build, plus a small Postgres table. The SQL ran on PGlite (PostgreSQL 18.6 in WebAssembly) and the script against a throwaway local server; the platform steps come from its documentation and were not run on a real deployment. It is the same note you will need for every urgent fix during a code freeze before Black Friday.
Why the rollback plan is decided before you deploy
At 11 pm, with checkout returning errors, nobody thinks well. You must answer four things at once: which version was the last good one, how to get back to it, whether the database works with it, and who decides. If the answers live in someone's head, the first ten minutes go to finding them. The plan moves them to a calm moment and rests on three rules: know the version and the way back, keep migrations compatible with the old code, and verify with a script instead of a feeling.
First, know what a rollback is. Railway's guide to rolling back a bad deploy and its deployment actions page are a clear public example; other platforms differ, so read yours against this table.
| What | Does a rollback bring it back? | Note |
|---|---|---|
| The app image | Yes | Re-activates an earlier deployment's Docker image as a new deployment, with no rebuild |
| Custom variables | Yes | They return as they were, so a bad variable change is reverted too |
| Database schema and data | The guide does not describe it | It never mentions databases or migrations: it is your job (rule 2) |
| Deployments older than the retention window | No | The Rollback option is hidden; Redeploy rebuilds from the original source |
Rule 1: an identifiable version and a way back
Make every deploy identifiable: have /healthz return a release identifier (the short commit hash works). Then name the destination with that identifier, "the last version that worked", not "the previous deploy": if two bad ones went out in a row, the previous one is broken too.
Scroll the figure sideways to see all of it
Write the path. On Railway, per its guide, you open the service's Deployments tab, find the last good deployment and choose Rollback in the three-dot menu. It restores the Docker image and custom variables as a new, active deployment with no rebuild, so it takes seconds, as long as the platform still holds the image: 24 hours on Free/Trial, 72 on Hobby, 120 on Pro, 360 on Enterprise. Beyond that you use Redeploy, which rebuilds from the original source and variables: slower, and it needs the build to succeed again.
Do not mistake the healthcheck for verification. With a healthcheck path set, the platform switches traffic only after a 200 and keeps the previous deployment serving if it fails, but the guide notes it runs only at deploy time. A change that starts fine and breaks the product page passes it.
The template fits on seven lines:
- Version you return to: the identifier.
- How you return: the exact steps and who has access.
- Window: how long the platform keeps the previous image.
- Database: the last migration and whether it has been contracted (rule 2).
- Criterion: what result triggers the rollback, for example "the verification script exits with a non-zero code".
- Who decides: a name, with a phone number.
- Who is told: sales, support, the agency.
Rule 2: migrations the old code survives (expand and contract)
A rollback returns code, not schema. On PGlite, with a customers(id, email, name) table, ALTER TABLE customers RENAME COLUMN name TO full_name made the new code work and the old code fail with column "name" does not exist, on reads and inserts. One step, and the way back is gone.
The fix is the pattern Martin Fowler's site publishes as parallel change, or expand and contract (text by Danilo Sato, May 2014): expand adds the new beside the old, migrate moves the clients over, and contract removes the old once nothing uses it. The expand step, before the deploy:
ALTER TABLE customers ADD COLUMN full_name text;
CREATE FUNCTION customers_sync_name() RETURNS trigger AS $$
BEGIN
IF TG_OP = 'INSERT' THEN
NEW.full_name := COALESCE(NEW.full_name, NEW.name);
NEW.name := COALESCE(NEW.name, NEW.full_name);
ELSIF NEW.full_name IS DISTINCT FROM OLD.full_name THEN
NEW.name := NEW.full_name;
ELSIF NEW.name IS DISTINCT FROM OLD.name THEN
NEW.full_name := NEW.name;
END IF;
RETURN NEW;
END $$ LANGUAGE plpgsql;
CREATE TRIGGER customers_sync_name
BEFORE INSERT OR UPDATE ON customers
FOR EACH ROW EXECUTE FUNCTION customers_sync_name();
UPDATE customers SET full_name = name WHERE full_name IS NULL;
ADD COLUMN full_name textadds the column with no default; per the PostgreSQL documentation, that does not rewrite the table.customers_sync_namekeeps the two columns equal: on anINSERTit fills the one the code left empty, and on anUPDATEit copies whichever changed to the other.CREATE TRIGGERruns it before everyINSERTorUPDATE, row by row.- The final
UPDATEcopies the existing rows. On a large table, do it in batches.
Scroll the figure sideways to see all of it
Then we deployed the new version, which uses only full_name. In any order, each version read the other's rows correctly, including after going back to the old one with rows the new one had written; all four rows ended with name equal to full_name. That is where the rollback is safe. Without the trigger it was not: in a control run, the new version's insert failed with null value in column "name" … violates not-null constraint and the old version's update left full_name stale. The trigger is a minimal version: test it with your own writers.
Contract goes last, and only once you will not go back:
ALTER TABLE customers ALTER COLUMN full_name SET NOT NULL;
DROP TRIGGER customers_sync_name ON customers;
DROP FUNCTION customers_sync_name();
ALTER TABLE customers DROP COLUMN name;
SET NOT NULLmakesfull_namethe required column.DROP TRIGGERandDROP FUNCTIONremove the sync, which is no longer needed.DROP COLUMN nameremoves the old one; the documentation notes it becomes invisible but the space is not reclaimed right away.
After that the old version fails with column "name" does not exist: there is no way back to it. So contract waits until the rollback window has passed, and the plan records whether it has run.
Rule 3: verify after the deploy
A "finished" deploy only means the process started. This script checks four paths, including the release, and exits non-zero on any failure, so a person or a pipeline can act without interpreting anything:
// Usage: node verify.mjs <base-url> <expected-release>
const [base, release] = process.argv.slice(2);
const checks = [
{ path: "/healthz", status: 200, ok: (b) => JSON.parse(b).release === release },
{ path: "/", status: 200, ok: (b) => b.includes("<h1") },
{ path: "/products/blue-shirt", status: 200, ok: (b) => b.includes("Add to cart") },
{ path: "/this-page-does-not-exist", status: 404 },
];
let failed = 0;
for (const c of checks) {
try {
const res = await fetch(base + c.path, { signal: AbortSignal.timeout(5000) });
const body = await res.text();
const pass = res.status === c.status && (!c.ok || c.ok(body));
if (!pass) failed++;
console.log((pass ? "ok " : "FAIL ") + c.path + " " + res.status);
} catch (err) {
failed++;
console.log("FAIL " + c.path + " " + err.name + ": " + err.message);
}
}
console.log(failed ? failed + " check(s) failed: roll back" : "all checks passed");
process.exit(failed ? 1 : 0);
- It takes the base URL and the release you expect; swap the paths for your project's.
- Each check has a path, an expected status and, if needed, a test on the body.
/healthzmust return the release you just deployed (it catches the old version still serving), the product page must contain the "Add to cart" button (a 200 is not enough), and a missing path must return 404 (it catches a server that answers 200 to everything). - The
fetchtimes out after five seconds; a failed request counts as a failure. - It exits
1if anything failed and0if everything passed.
We ran it locally against a test server on 127.0.0.1: healthy new version, exit 0; product page returning 500, exit 1; old version still serving, exit 1; nothing listening, exit 1. The server is a stand-in, so the script is only as good as its paths. For the full purchase flow, add the checkout smoke test.
Scroll the figure sideways to see all of it
Roll back first, investigate second
If verification fails, go back first and understand later. The broken version stops serving, and you reproduce the failure on a copy with the logs in front of you, without customers paying for your time. An improvised fix on production is another deploy with no plan.
The exception is what justifies rule 2: with a migration already contracted there is nowhere to go back to, only a fix going forward. Once you are back, write down what happened and what you change in the plan; the fix ships like any other deploy, with its version, its way back and its verification.
Common mistakes
- Renaming or dropping a column in the same deploy that uses the new name. It leaves the rollback without a compatible database. Expand, migrate and contract separately.
- Assuming the rollback brings the database back. The platform's guide talks about the image and variables, not data.
- Not knowing how long the window is. With 24 hours of retention, a Friday failure found on Monday no longer rolls back with one click.
- Verifying only the home page. A 200 on the home page says nothing about the product page or the cart.
- Treating the healthcheck as post-deploy verification. It runs at deploy time and never looks again.
Frequently asked questions
Can I roll back if I already ran a migration?
Yes, if it is compatible with the previous code. A migration that only expands (a nullable column, a table, an index) does not prevent going back; one that drops or renames does.
How long do I have to roll back?
It depends on the platform. On Railway, per its guide, the image is kept 24 hours on Free/Trial, 72 on Hobby, 120 on Pro and 360 on Enterprise. After that, Redeploy is what is left.
What is the difference between a rollback and a redeploy?
A rollback re-activates an already built image, with the variables it had, and needs no build. A redeploy builds again from the original source: it takes longer and can fail if the build no longer works.
Is that the same as git revert?
No. A git revert creates a new commit that has to go through the build and the deploy again. Go back with the rollback first, then revert the commit so the branch does not redeploy the bad change.
Checklist
- Every deploy is identifiable:
/healthzreturns the release. - The plan names the version you return to, and the steps are written down.
- You know how long your platform keeps the previous image.
- This deploy's migrations only expand; contract goes in a later one.
- The verification script covers the paths that make money and checks the release.
- The rollback criterion and who decides are written down.
If Black Friday is close, every urgent fix in the code freeze should carry its plan. And if the change is a new image, note the old one before you touch anything, as in updating Node in Docker.
Saw this on Instagram? Comment ROLLBACK on the Reel and I'll send you the guide.
Written by

Published November 12, 2026 · updated November 18, 2026