Skip to content

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)
  1. Why the rollback plan is decided before you deploy
  2. Rule 1: an identifiable version and a way back
  3. Rule 2: migrations the old code survives (expand and contract)
  4. Rule 3: verify after the deploy
  5. Roll back first, investigate second
  6. Common mistakes
  7. Frequently asked questions
  8. Checklist

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.

WhatDoes a rollback bring it back?Note
The app imageYesRe-activates an earlier deployment's Docker image as a new deployment, with no rebuild
Custom variablesYesThey return as they were, so a bad variable change is reverted too
Database schema and dataThe guide does not describe itIt never mentions databases or migrations: it is your job (rule 2)
Deployments older than the retention windowNoThe 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.

a rollback is a new deployment running the previous imageweb servicedeploy 1image v1worksdeploy 2image v2verify failsrollbackimage v1+ v1 variablesdeploy 3v2, fixedafter the fixreuses the stored image, no builddatabasethe rollback leaves itschema v1migrated to v2still v2v2the image and variables go back, the data does notRailway retention: 24 h Free/Trial · 72 h Hobby · 120 h Pro · 360 h Enterprise

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;
  1. ADD COLUMN full_name text adds the column with no default; per the PostgreSQL documentation, that does not rewrite the table.
  2. customers_sync_name keeps the two columns equal: on an INSERT it fills the one the code left empty, and on an UPDATE it copies whichever changed to the other.
  3. CREATE TRIGGER runs it before every INSERT or UPDATE, row by row.
  4. The final UPDATE copies the existing rows. On a large table, do it in batches.
renaming name to full_name without breaking the rollback1 · expandADD COLUMN full_namesync triggername y full_nameUPDATE: backfillv1 ok · v2 okbefore the deploy2 · migratedeploy v2:reads and writesfull_namev1 never noticesv1 ok · v2 okrollback is safe3 · contractSET NOT NULLDROP TRIGGERDROP FUNCTIONDROP COLUMN namev1 breaks · v2 okno way back to v1contract only once you will not go back to v1: after the rollback windowevery step works with the code before ittested on PGlite 0.5.10 (PostgreSQL 18.6): a plain RENAME breaks v1

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;
  1. SET NOT NULL makes full_name the required column.
  2. DROP TRIGGER and DROP FUNCTION remove the sync, which is no longer needed.
  3. DROP COLUMN name removes 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);
  1. It takes the base URL and the release you expect; swap the paths for your project's.
  2. Each check has a path, an expected status and, if needed, a test on the body. /healthz must 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).
  3. The fetch times out after five seconds; a failed request counts as a failure.
  4. It exits 1 if anything failed and 0 if 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.

verify.mjs after the deploy: four paths, one exit codepathexpectsv2 okv2 · 500still v1/healthz200 + releaseokokFAIL/200 + <h1okokok/products/blue-shirt200 + buttonokFAILok/this-page-does-not-exist404okokokexit code0 = keep011one failure means exit 1: go back to the previous versionmeasured locally with Node 22.22.3 against a test server on 127.0.0.1

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: /healthz returns 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 12, 2026 · updated November 18, 2026

← Blog