Backend
    August 27, 2026•5 min read

    Postgres schema changes without surprises

    Push mode is great until it touches a shared database. A short checklist for migrations that behave the same on your laptop and in production.

    Anonymous
    Postgres schema changes without surprises

    ORMs that sync the schema on startup feel productive, right up until a half-finished field change lands in a database someone else depends on. Migrations are slower to write but far easier to reason about.

    The checklist

    • Turn off schema push (push: false in Payload’s Postgres adapter) so dev and production change the same way.
    • Generate one migration per change and commit it alongside the code.
    • Make changes additive first: add, backfill, then constrain.
    • Run migrations as part of the deploy, not by hand afterwards.

    Add, backfill, constrain

    SQL
    1-- 1. add the column as nullable
    2ALTER TABLE "projects" ADD COLUMN "year" integer;
    3
    4-- 2. backfill existing rows
    5UPDATE "projects" SET "year" = EXTRACT(YEAR FROM "created_at");
    6
    7-- 3. enforce it once every row has a value
    8ALTER TABLE "projects" ALTER COLUMN "year" SET NOT NULL;

    Migrating on deploy

    A build script that migrates first means a deploy can never run ahead of its schema:

    JSON
    1{
    2  "scripts": {
    3    "ci": "payload migrate && pnpm build"
    4  }
    5}
    #PostgreSQL
    #Payload CMS
    Share: