Backend
August 27, 2026•5 min readPostgres 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

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: falsein 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