---

name: neon-drizzle-migrations description: Use when defining or changing a database schema with Drizzle ORM on Neon Postgres, generating migrations, or debugging a drift between the schema file and the live database.

Neon + Drizzle Migrations

When to trigger

Adding or altering a table, wiring the first DB connection, or resolving a migration that will not apply.

Steps

1. Define the schema in db/schema.ts:

   import { pgTable, text, timestamp, boolean } from "drizzle-orm/pg-core";
   export const users = pgTable("users", {
     id: text("id").primaryKey(),
     email: text("email").notNull().unique(),
     isOwner: boolean("is_owner").default(false).notNull(),
     createdAt: timestamp("created_at").defaultNow().notNull(),
   });
   

2. Point drizzle.config.ts at the schema and set DATABASE_URL to the Neon pooled connection string.

3. Generate SQL from the schema diff: pnpm drizzle-kit generate. Read the generated file in drizzle/ before applying it.

4. Apply it: pnpm drizzle-kit migrate.

5. Inspect data with pnpm drizzle-kit studio.

Local vs production

• Keep DATABASE_URL in .env.local for dev and in the host env for production. Never hardcode it.
• Run generate locally and commit the SQL. Run migrate in a deploy step or manually against production. Do not push to production - push skips the migration history and can drop columns.

Pitfalls

• drizzle-kit push is for fast local iteration only. It diffs and applies directly, which can silently drop a column when you rename one. Use generate + migrate anywhere that holds real data.
• Neon has a pooled and a direct connection string. Migrations that use advisory locks want the direct (non-pooled) URL. App queries use the pooled URL.
• The app should build even without DATABASE_URL. Guard the client creation so a missing env var does not fail the whole build.