Drizzle ORM Migrations: A Practical drizzle-kit Guide

push vs migrate: The Most Important Distinction

# Development — fast, no files
npx drizzle-kit push

# Production — generate first, review SQL, then apply
npx drizzle-kit generate
npx drizzle-kit migrate

Setting Up drizzle-kit

1. 1

   Install and configure drizzle-kit

   Create drizzle.config.ts in your project root. This example uses PostgreSQL. Turso config is in Step 3:

   typescript — drizzle.config.tsCopy

   import { defineConfig } from 'drizzle-kit';
   
   export default defineConfig({
     schema: './src/db/schema.ts',
     out: './migrations',
     dialect: 'postgresql',
     dbCredentials: {
       url: process.env.DATABASE_URL!,
     },
   });

2. 2

   Define your schema and generate the first migration

   typescript — src/db/schema.tsCopy

   import { pgTable, serial, text, integer, timestamp } from 'drizzle-orm/pg-core';
   
   export const users = pgTable('users', {
     id: serial('id').primaryKey(),
     name: text('name').notNull(),
     email: text('email').notNull().unique(),
     createdAt: timestamp('created_at').defaultNow(),
   });
   
   export const posts = pgTable('posts', {
     id: serial('id').primaryKey(),
     title: text('title').notNull(),
     authorId: integer('author_id').references(() => users.id),
     publishedAt: timestamp('published_at'),
   });

   bashCopy

   npm run db:generate
   # Creates ./migrations/0001_initial.sql

3. 3

   Turso/libSQL-specific setup

   If you're using Turso, the dialect, credentials, and column types all change from PostgreSQL:

   typescript — drizzle.config.ts — TursoCopy

   import { config } from 'dotenv';
   import { defineConfig } from 'drizzle-kit';
   
   config({ path: '.env.local' }); // drizzle-kit does not auto-load .env.local
   
   export default defineConfig({
     schema: './src/db/schema.ts',
     out: './migrations',
     dialect: 'turso',
     dbCredentials: {
       url: process.env.TURSO_DATABASE_URL!,
       authToken: process.env.TURSO_AUTH_TOKEN!,
     },
   });

   • Install the Turso driver: npm install @libsql/client
   • Use sqliteTable from drizzle-orm/sqlite-core instead of pgTable
   • Use integer('id').primaryKey({ autoIncrement: true }) instead of serial for auto-increment IDs
4. 4

   Run migrations in production

   Run migrations as part of your deployment process, not on application startup:

   bash — Vercel — add to Build CommandCopy

   npm run db:migrate && next build

   bash — Cloudflare — run before wrangler deployCopy

   npm run db:migrate
   npx wrangler deploy

Troubleshooting

1. 1

   Handling team migration conflicts

   When two branches both add schema changes and merge, you can end up with two files both numbered 0002_something.sql. Fix by regenerating from the resolved schema:

   bashCopy

   # 1. Resolve merge conflicts in schema.ts
   # 2. Delete the conflicting migration files
   # 3. Regenerate from the resolved schema
   npm run db:generate
   # Creates one clean migration covering all merged changes

2. 2

   Reverting a migration

   Drizzle does not generate automatic rollback files. To reverse a migration, write the reverse SQL by hand as a new forward migration:

   • Additive changes (adding a table, adding a nullable column) are safe and rarely need reverting
   • Destructive changes (dropping a column, changing a type) require a hand-written reverse migration and should always be tested on staging first
   • Always export a database backup before any destructive production migration

drizzle-kit Commands Reference

import { config } from 'dotenv';
config({ path: '.env.local' });