Web Development

The Rename Shipped as a Drop and an Add: A Schema Differ Sees What Changed, Not What You Meant

Catalog comparison cannot tell a rename from a delete, so generated migrations express one as the other. Four schema-change workflows, where each puts the decision, and the gate we run in front of all of them.

KAKabir AnandLead Developer
9 min read
Isometric illustration of a conveyor line where one labelled block is lifted away and a fresh empty block is set down in its place, while a second line simply re-labels the block in transit

A pull request arrives with one changed line in a schema file — a column called summary is now called excerpt — and a generated migration sitting beside it. The migration is two statements long. Both are valid SQL. Together they delete a column of production text and replace it with an empty one.

db/migrations/20261103120000_posts.sql
1-- generated from the schema file. both statements are correct.
2-- together they are not what anyone asked for.
3ALTER TABLE "public"."posts" DROP COLUMN "summary";
4ALTER TABLE "public"."posts" ADD COLUMN "excerpt" text;
5 
6-- what the developer meant, and what no catalog comparison can infer:
7-- ALTER TABLE "public"."posts" RENAME COLUMN "summary" TO "excerpt";

Nothing in that file is a bug. A differ loads two schemas, compares their system catalogs, and emits the statements that turn one into the other. Catalogs do not store intent. From the outside, a rename and a drop-plus-add are the same observation: a column named summary stopped existing, a column named excerpt started, and the engine has no basis for claiming they are the same data.

That has always been true of schema diffing. What changed through 2026 is how much of it now runs with nobody watching. Supabase shipped Declarative Schemas 2.0 on the open-source pg-delta engine in October, and its own guidance is blunt about this case: a renamed column comes out as a drop followed by an add, and running that unchanged wipes the column’s data. pgschema does not model renames at all — a renamed object is a drop and a create. Atlas attacked the other half of the problem and shipped atlas migrate drift in v1.4 on 17 November, for the schemas that quietly stopped matching the repo. Four tools, four different places to put the same unanswerable question.

What a Differ Knows, and What It Cannot

It is worth being exact about this boundary, because teams keep spending their review effort on the wrong side of it — reading the schema file closely and skimming the SQL, when it is the SQL that runs.

  • Structure, precisely— columns, types, constraints, indexes, and in the newer engines the things older diffs skipped: RLS policies, grants, views, partitions, domains. Coverage here is genuinely better than it was two years ago.
  • Dependency order, usually— drop the view before the column it reads, create the type before the table that uses it. This is the part a differ does better than most humans.
  • Intent, never— rename, split, merge, widen-then-backfill. Every one of these is a story about the data, and the catalog records none of it. An engine that guessed would be worse, not better.
  • Rollout, not at all— the generated file describes an end state. It says nothing about the ten minutes when both the old and new application versions are live and only one of them knows the new column name.

That last one catches people out. A migration can be entirely correct and still take the site down, because correctness is a statement about the end state and a deploy is a statement about the middle.

Flat vector illustration of two vertical stacks of coloured bars, one bar missing from the left stack and an identically shaped empty outline appearing in the right stack, with a plain equals sign between them
A column disappeared and a column appeared. The catalog records both facts and no relationship between them.

Four Workflows, and Where Each Puts the Decision

The useful way to compare these is not by feature list. It is by asking one question: when nobody makes the call, what happens? Every tool here has a default, and the default is the behaviour you will actually get on a busy Thursday.

WorkflowWho decides a rename is a renameWhat happens when nobody decidesWhat it still does not own
Declarative diff engine — pg-delta, pgschemaThe reviewer, by rewriting the generated SQL before it is appliedDrop the old column, add the new oneBackfill, rollout order, and the window where two app versions are live
ORM generator — Prisma Migrate, Drizzle KitA prompt at generate time, or a hand edit after generating without applyingPrisma warns about data loss and still emits drop plus add; Drizzle Kit asks, and create is the default answerWhether the answer came from a person or from whatever was running the command
Versioned migrations behind a lint gate — AtlasStill the author; lint reports which statements are dangerous, not which are wrongThe migration fails the gate instead of shipping quietlyIntent. DS103 and BC102 describe the shape of the change, not your reason for it
Hand-written SQL, expand and contractThe author, in the file, before anyone reviews itNothing is generated, so nothing is defaultedDrift. With no differ you learn at deploy time that production never matched the repo

Declarative diff engines: pg-delta, pgschema

These are the Terraform model applied to Postgres: you keep the desired schema in files, the tool computes a plan against the live catalog, you apply it. The appeal is real. Review happens against a readable schema rather than an archaeology of forty migration files, and coverage of the awkward objects has improved sharply — pg-delta is open source under the PostgreSQL License, ships as @supabase/pg-delta, and can be pointed at any two databases from Postgres 14 through 18.

The trade-off is stated plainly in the documentation and ignored just as plainly in practice: these engines optimise for coverage and correctness, not for the least destructive path. The plan is an input to review. Treating it as a deployable artifact is where the data goes.

ORM generators: Prisma Migrate and Drizzle Kit

Both of these do try to protect you, in different ways. Prisma Migrate warns that a column is about to be dropped, tells you how many non-null values it holds, and refuses to proceed unattended; the documented fix is to generate without applying, open the SQL, and replace the drop and add with an explicit ALTER TABLE … RENAME COLUMN. Drizzle Kit asks directly — is this column created, or renamed from another one? — which is the right question, asked at the right moment.

The weakness is that the protection lives in an interaction. A warning works on someone who reads it. A prompt works on someone who is there. Neither condition is guaranteed by the pipeline, and on Drizzle Kit the default answer to that prompt is create — which is the destructive one.

Versioned migrations behind a lint gate: Atlas

Atlas keeps the versioned-migration model and puts a static analyser in front of it. The analyser codes are worth knowing by name, because they are the vocabulary a review can actually use: DS103 for a non-virtual column being dropped, and BC102 for a column rename, which is flagged not because data is lost but because the old application version is still referring to the old name during a rolling deploy.

This is the closest thing to a real gate, with one caveat we would rather say out loud: every gate has an override. Silencing a check is a single comment — -- atlas:nolint BC102 above the statement — and overrides have a way of becoming permanent. If your review culture treats a suppression as a thing that needs a reason in the pull request, this model holds. If it does not, you have bought a slower pipeline and the same outcome.

Hand-written SQL, expand and contract

Still the most defensible option for the small number of changes that are genuinely dangerous. Add the new column. Ship code that writes both and reads the old one. Backfill in batches. Flip reads. Then, in a separate release that can be reverted on its own, drop the old column. Nothing here is clever, and nothing here can be inferred by a tool, because each phase is a deliberate decision about which of two states your running application is allowed to be in.

What it does not give you is drift detection. A column somebody added by hand during an incident, a grant changed in a console, an index created manually and never committed — none of that shows up until the next generated plan tries to remove it. That is exactly why Atlas shipped a drift command this month, and it is why we do not treat these four workflows as mutually exclusive. Most teams we work with end up generating the plan and hand-writing the dangerous third of it.

The Prompt Was Answered by Something With No Terminal

Here is the part that has changed fastest, and the reason this is worth writing about now rather than in 2023.

The safety in most of these tools is an interactive prompt. Increasingly, the thing editing the schema file and running the generator is an agent in CI with no TTY attached. The Drizzle Kit issue tracker has the failure written out in full — Interactive prompts require a TTY terminal — filed by someone whose agent edits the schema, commits, and generates, all non-interactively. Recent releases added a non-interactive mode and a way to supply rename and data-loss decisions as hints, which is the right fix. The dangerous interval is the one before a team adopts it.

Because the other way to resolve a blocking prompt is to pass the flag that removes it. Force flags, accept-data-loss flags and push-style commands all exist, all are documented, and all answer precisely the question that was worth stopping for. An agent that hits a blocked command and retries it with the override is not malfunctioning; it is doing the obvious thing. The protection was never in the tool. It was in the fact that a human happened to be sitting there.

scripts/db-plan.sh
1# migrations are generated in CI, with no TTY and no flag that
2# answers the data-loss question on our behalf.
3set -euo pipefail
4 
5# 1. generate non-interactively against the recorded history
6drizzle-kit generate --output json > plan.json
7 
8# 2. an unresolved rename or drop is a failure, never a default
9node scripts/assert-reviewed-drops.mjs plan.json
10 
11# 3. same static gate for every tool that emits SQL here
12atlas migrate lint --dir "file://db/migrations" --latest 1
13 
14# blocked in automation, not merely discouraged:
15# --force --accept-data-loss *-kit push db push
Editorial photograph of an empty office chair pushed back from a desk at night, a monitor glowing with soft abstract colour and no readable content, keyboard untouched
Every confirmation prompt in this toolchain assumes somebody is in the chair.

What We Require Before a Generated Migration Ships

None of this is an argument against schema diffing. We use it, the coverage improvements this year are worth having, and hand-writing every migration is how teams end up with schemas that silently disagree with production. The argument is narrower: the generated plan is a draft, and it needs a gate that does not depend on anyone being awake.

The gate

  • No generated SQL reaches an environment with real rows until a person has read the SQL itself. The schema file is the input to review; the statements are what actually run.
  • Every DROP, every type narrowing, and every ADD COLUMN ... NOT NULL without a default gets an explicit approval in the pull request that names the table and the column.
  • Renames are written by hand as ALTER TABLE ... RENAME COLUMN, or split into expand and contract. The differ is never allowed to express one.
  • CI generates non-interactively and fails on an unresolved prompt. Force and accept-data-loss flags are blocked in automation, not left to discipline.
  • Dangerous migrations are rehearsed against a restored snapshot at production row counts, with a row count or checksum assertion on both sides of the change.
  • Drift is checked on a schedule rather than at deploy time, so an object someone added by hand is a finding on a Tuesday instead of a surprise in a release plan.

Four of those six are things a pipeline enforces rather than things a person remembers, which is the only property that matters. A review step that depends on attention degrades exactly when the team is busiest, and the team is busiest during the releases that carry the dangerous changes.

If you only change one thing

Grep your CI configuration and your package scripts for force and accept-data-loss flags and for push-style schema commands. They were almost certainly added once to unblock a deploy, by someone who looked at that specific plan and knew it was safe. They are now standing instructions to approve every future plan, including the one that arrives after an agent renames a column at two in the morning.

Then ask a smaller question about the last schema change you shipped: did anyone read the SQL, or did they read the schema file and trust the generator? Those feel like the same review. Only one of them would have caught a drop and an add where a rename was meant.

Keep Reading

More from the blog

Track Record

The Engineering Partner You Can Build On

Reliable software takes an experienced team that owns delivery end to end. Here’s the track record behind ours.

Book a Free Consultation
01

11+

Years Building Custom Software

02

320+

Projects Delivered Across Web, Mobile & AI

03

85%

Repeat Client Rate

04

12+

Countries Served Worldwide

Trusted by startups and enterprises worldwide

Work With Us

Let’s create
with purpose

Share your goals, timeline, and challenges — we’ll respond with clarity and next steps.

Ambitious ideas deserve thoughtful execution. Start the conversation and let’s define what success looks like.

Team

Acetrum

Est. 2015

4.9/5

Trusted by
top brands

Services interested in:

By submitting, I confirm I’ve read and agree with Privacy and Cookie Policies.

Newsletter

Signals worth
paying attention

No recycled headlines — just the patterns we’re seeing across real client work, distilled into one read a month.

A curated digest of practical thinking and real-world brand perspectives monthly.

No spam. Unsubscribe anytime.