---

name: drizzle-additive-migrations description: Use when changing a Drizzle schema that already holds real data, especially on Neon. Covers why db:push is unsafe on production, the additive-change discipline, writing a surgical ALTER by hand, and keeping the drizzle journal authoritative.

Additive-Only Drizzle Migrations

When to trigger

Adding a column, table, or index to a schema that a live app already writes to, or resolving drift between db/schema.ts and the deployed database.

push is for empty dev; migrate is for real data

drizzle-kit push diffs the schema and applies the change directly, skipping the migration history. When it sees a rename it can read the diff as a drop-plus-add and silently destroy a column. Use push only against a throwaway local database. Anywhere that holds data you cannot lose, use generate (writes a numbered SQL file plus a journal entry) then migrate.

Prefer additive changes

The safe change is one that only adds:

• A new nullable column, or a column with a default, so existing rows stay valid.
• A new table or index, which touches no existing row. Avoid destructive edits in the same step as a deploy. Renames and drops are two-phase: add the new shape, backfill and cut the app over, then remove the old shape in a later migration once nothing reads it.

When the generated diff is wrong, hand-write the ALTER

generate sometimes proposes a drop-and-recreate for what is really a rename or a type widen. Do not apply that. Replace it with a surgical statement that preserves data:

-- instead of DROP COLUMN old / ADD COLUMN new:
ALTER TABLE "credit_balances" RENAME COLUMN "is_admin" TO "is_owner";
-- add a column without rewriting the table:
ALTER TABLE "request_traces" ADD COLUMN "kind" text DEFAULT 'other' NOT NULL;

Keep the hand-written file in the migrations folder and its entry in the journal so history stays linear.

The journal is the source of truth

The _journal.json and the numbered SQL files ARE the migration history. Read the generated SQL before applying it, commit it, and run migrate in the deploy step. Never edit an already-applied migration; add a new one. Migrations that take advisory locks want Neon's direct (non-pooled) connection string.

Pitfalls

• db:push against production can drop a column on any change it reads as a rename. Reserve it for disposable local databases.
• A generated migration that drops and recreates a column deletes its data. Rewrite it as an ALTER ... RENAME or additive ADD COLUMN.
• A new NOT NULL column with no default fails against a table that already has rows. Add a default or backfill first, then tighten.
• Editing a migration that already ran splits history between environments. Always append a new migration instead.