Drizzle Kit - SQL Migration CLI That Actually Works

Been using Drizzle Kit since early 2024, upgraded through several major versions, and it consistently handles the migration bullshit better than anything else. Here's why it actually works.

The Migration Generation That Doesn't Break

Most migration tools either generate garbage SQL or require you to write everything by hand. Drizzle Kit reads your TypeScript schema files, compares them to your actual database, and generates the SQL diff automatically. When it can't figure out if you renamed a column or deleted one, it asks instead of guessing wrong and destroying your data.

## This actually works without mysterious failures
npx drizzle-kit generate
npx drizzle-kit migrate

The generated migrations are readable SQL that you can edit if needed. Try doing that with Prisma without breaking the entire migration system.

Two Migration Workflows That Make Sense

Development Flow (push): Skip migration files entirely for rapid iteration

## Perfect for development - applies schema changes directly
npx drizzle-kit push

Production Flow (generate + migrate): Create reviewable SQL migration files

## Generate migration file for review
npx drizzle-kit generate --name add_user_preferences

## Apply to database after review
npx drizzle-kit migrate

The push command handles schema drift by introspecting your current database and applying only the necessary changes. No migration history conflicts, no mysterious state issues. Works better than expected, especially after version 0.30.x where it kept corrupting enum migrations.

Database Introspection That Actually Helps

Need to start with an existing database? The pull command generates TypeScript schema files from your current database structure:

## Creates schema.ts from existing database
npx drizzle-kit pull

This is invaluable for migrating from other ORMs or working with legacy databases. TypeORM and Sequelize make this process painful - Drizzle Kit handles it in seconds.

Drizzle Studio - Database Browser That Doesn't Suck

The studio command spins up a web interface for browsing your database. Unlike phpMyAdmin or pgAdmin, it understands your Drizzle schema and relationships:

## Starts local database browser
npx drizzle-kit studio

Runs on localhost:4983 by default. You can edit records, explore relations, export data - all with proper type safety based on your schema definitions. Teams are using the embeddable version in their admin panels.

Configuration That Makes Sense

One config file handles everything. No separate migration configs, no environment-specific settings scattered everywhere:

// drizzle.config.ts
import { defineConfig } from \"drizzle-kit\";

export default defineConfig({
  dialect: \"postgresql\", // or \"mysql\" or \"sqlite\"
  schema: \"./src/schema.ts\",
  out: \"./migrations\",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Multiple databases? Multiple config files:

npx drizzle-kit push --config=drizzle-dev.config.ts
npx drizzle-kit push --config=drizzle-prod.config.ts

Platform Support Without Gotchas

Works with every major database and hosting platform:

• Databases: PostgreSQL, MySQL, SQLite, plus the serverless variants you actually use
• Serverless: Neon, Turso, PlanetScale, Cloudflare D1
• Platforms: Vercel, Netlify, Railway, Fly.io, traditional servers

The driver configuration automatically detects your setup. For edge cases like AWS Data API or D1 HTTP, you specify the driver explicitly.

Error Handling That Tells You What's Wrong

Version 0.31.4 finally fixed the error messages. Instead of "migration failed" or some P2025 bullshit you have to Google, you get:

• The actual SQL statement that failed
• The specific schema differences causing conflicts
• Clear guidance on manual intervention steps
• Warnings about potential data loss before execution

CLI Commands That Cover Everything

Each command has safety options:

• --strict: Prompts for approval before destructive operations
• --verbose: Shows all SQL before execution
• --force: Auto-approves data loss operations (use carefully)

When Drizzle Kit Works Best

Perfect for teams that want:

• Type-safe migrations generated from TypeScript schemas
• Readable SQL files that can be reviewed and modified
• Fast development iteration with push-based workflow
• Production safety with proper migration files
• Database introspection for existing projects
• Visual database browsing without separate tools

The Gotchas (Because There Are Always Some)

Schema renames can be tricky - Drizzle Kit will ask if you renamed a column or deleted it, but if you rename a table and add a column in the same migration, it gets confused and generates a DROP TABLE. Ask me how I know.

Connection pooling will bite you in serverless - learned this the hard way when migrations started timing out randomly on Vercel. The error messages actually help you debug them though.

For embedded databases (Expo SQLite, OP SQLite), migrations work differently since there's no central database to push to.

Production teams using Drizzle Kit consistently report fewer migration-related incidents than with other tools. The generated SQL is readable, the errors make sense, and when things break, you can actually fix them.

Had a migration fail on Black Friday deploy once - with Drizzle Kit, I could see exactly which ALTER TABLE statement died and why. Fixed it in 10 minutes instead of rolling back the entire release.

OK, personal war story aside - here's how it stacks up against the competition when your production deployment is on the line. Let's see how Drizzle Kit measures up against the alternatives that developers actually use.

Generate - Creating Migration Files

The generate command creates SQL migration files from your schema changes. This is your production workflow command:

## Basic generation from schema changes
npx drizzle-kit generate

## Named migration for better organization
npx drizzle-kit generate --name add_user_preferences

## Custom output directory
npx drizzle-kit generate --out ./custom-migrations

## Custom config file
npx drizzle-kit generate --config=production.config.ts

When to use: Before deploying to production, when you need reviewable migration files, for team collaboration on schema changes.

Generated files look like:

-- 0001_add_user_preferences.sql
ALTER TABLE "users" ADD COLUMN "theme" text DEFAULT 'light';
CREATE INDEX "user_email_idx" ON "users" ("email"); -- this will take forever on large tables

These are readable SQL files you can actually edit. Unlike Prisma's generated magic where touching anything breaks the entire migration system.

Push - Direct Schema Application

The push command skips migration files and applies schema changes directly to the database:

## Development workflow - fast iteration
npx drizzle-kit push

## Safety mode - prompts before destructive changes
npx drizzle-kit push --strict

## See all SQL before execution
npx drizzle-kit push --verbose

## Auto-approve data loss operations (dangerous)
npx drizzle-kit push --force

When to use: Development iteration, handling schema drift, prototyping new features, when migration files aren't needed.

How it works: Introspects your database, compares it to your TypeScript schema, generates and applies the diff.

Migrate - Applying Generated Migrations

The migrate command applies previously generated migration files to your database. Unlike Prisma's migration system, Drizzle's approach focuses on readable SQL files that you can review and modify:

## Apply all pending migrations
npx drizzle-kit migrate

## Use custom migration directory
npx drizzle-kit migrate --out ./custom-migrations

## Production configuration
npx drizzle-kit migrate --config=production.config.ts

When to use: Production deployments, CI/CD pipelines, when you need migration history tracking.

Migration tracking: Drizzle Kit maintains a migrations table to track which migrations have been applied.

Pull - Database Introspection

The pull command generates TypeScript schema files from your existing database. Essential for migrating from other ORMs, though it generates unknown types for weird column types and you have to fix them by hand:

## Generate schema from current database
npx drizzle-kit pull

## Custom output file
npx drizzle-kit pull --out ./src/generated-schema.ts

## Introspect specific schemas only
npx drizzle-kit pull --schema=public,auth

When to use: Migrating from other ORMs, working with legacy databases, creating Drizzle schemas from existing tables.

Output: Complete TypeScript schema definitions matching your database structure, including indexes, constraints, and relationships.

Studio - Database Browser

The studio command launches a web interface for browsing your database. Unlike phpMyAdmin, it actually understands your schema relationships. Sometimes it randomly stops working and I still don't know why, but restarting it fixes it:

## Start studio on default port (4983)
npx drizzle-kit studio

## Custom port and host
npx drizzle-kit studio --port=3000 --host=0.0.0.0

## Enable SQL logging
npx drizzle-kit studio --verbose

When to use: Debugging data issues, exploring database contents, making quick data edits, demonstrating database structure to team members.

Features: Browse tables, edit records, view relationships, export data, explore schema visually.

Check - Migration Validation

The check command validates your migration files for consistency issues:

## Validate all migrations
npx drizzle-kit check

## Check specific migration directory
npx drizzle-kit check --out ./migrations

When to use: Before production deployments, in CI/CD pipelines, when migration files seem corrupted, troubleshooting migration conflicts.

What it checks: Migration file integrity, naming conflicts, dependency issues, snapshot consistency.

Up - Update Migration Snapshots

The up command updates migration snapshots when upgrading Drizzle Kit versions:

## Update snapshots for current version
npx drizzle-kit up

## Update specific directory
npx drizzle-kit up --out ./migrations

When to use: After upgrading Drizzle Kit versions, when snapshot format changes, resolving snapshot compatibility issues.

What it does: Updates internal snapshot files to match current Drizzle Kit format without changing your database schema.

Configuration Patterns That Work

Multiple Environment Setup

For production deployment and CI/CD integration, use separate config files:

// drizzle-dev.config.ts
export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  out: "./migrations",
  dbCredentials: { url: process.env.DEV_DATABASE_URL! },
});

// drizzle-prod.config.ts  
export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts", 
  out: "./migrations",
  dbCredentials: { url: process.env.PROD_DATABASE_URL! },
  strict: true, // Extra safety for production
});

Advanced Filtering Options

For large databases or complex multi-tenant setups, filtering becomes crucial:

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: { url: process.env.DATABASE_URL! },
  
  // Only manage specific tables - useful for gradual migrations
  tablesFilter: ["users", "posts", "comments"],
  
  // Skip system schemas - prevents accidental changes to pg_catalog
  schemaFilter: ["public", "auth"], // Supabase users need "auth" schema
  
  // Ignore PostGIS extension tables - they manage their own schema
  extensionsFilters: ["postgis", "vector"], // Also skip pgvector tables
  
  // Introspection settings for existing databases
  introspect: {
    casing: "camel", // Convert snake_case to camelCase
  },
});

Real-world filtering scenarios:

• Legacy database migration: Start with critical tables only, expand gradually
• Multi-tenant SaaS: Filter by tenant schemas to avoid cross-contamination
• Microservice boundaries: Each service manages its own table subset
• Extension management: Let PostGIS, TimescaleDB handle their own tables

Platform-Specific Drivers

// AWS Data API
export default defineConfig({
  dialect: "postgresql",
  driver: "aws-data-api",
  dbCredentials: {
    database: "mydb",
    resourceArn: "arn:aws:rds:...",
    secretArn: "arn:aws:secretsmanager:...",
  },
});

// Cloudflare D1
export default defineConfig({
  dialect: "sqlite", 
  driver: "d1-http",
  dbCredentials: {
    accountId: "your-account-id",
    databaseId: "your-database-id", 
    token: "your-api-token",
  },
});

Package.json Scripts That Make Sense

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate", 
    "db:push": "drizzle-kit push",
    "db:pull": "drizzle-kit pull",
    "db:studio": "drizzle-kit studio",
    "db:check": "drizzle-kit check",
    
    // Environment-specific
    "db:push:dev": "drizzle-kit push --config=drizzle-dev.config.ts",
    "db:migrate:prod": "drizzle-kit migrate --config=drizzle-prod.config.ts --strict"
  }
}

Troubleshooting Common Issues

Understanding common migration patterns and avoiding schema drift issues is crucial for production success.

Migration Conflicts and Schema Drift

Problem: "Relation already exists" - this error will haunt your dreams.

Solution: Stop trying to be clever with migrations and just use push:

## This actually fixes drift without making you want to quit
npx drizzle-kit push --strict

Prevention: Pick one workflow and stick with it. Mixing push and migrate is a recipe for pain.

Connection Issues in Serverless

Problem: Database connections failing in Vercel Edge Functions, Netlify Functions, or Cloudflare Workers.

Solution: Use HTTP-based database drivers:

// For Vercel Edge Functions
driver: "neon-http" // instead of "node-postgres"

// For Cloudflare Workers  
driver: "d1-http" // instead of "d1"

Permission Denied Errors

Problem: Migration commands fail with permission errors despite database access working.

Solution: Check database user permissions for schema modifications:

-- Grant schema modification permissions
GRANT CREATE, ALTER, DROP ON SCHEMA public TO your_user;
GRANT CREATE ON DATABASE your_db TO your_user;

TypeScript Import Errors

Problem: Drizzle Kit crashes when trying to parse your schema - usually with some cryptic TS error.

Solution: Your TypeScript is probably broken somewhere:

## Fix your TypeScript first, obviously
npx tsc --noEmit

## If that doesn't work, be more explicit
npx drizzle-kit generate --schema=./src/schema.ts

Common causes:

• Barrel exports: Stop using export * from './schema' - just import what you need
• Circular imports: Your schema file is importing business logic that imports the schema. Don't.
• Path aliases: TypeScript paths don't work here, use relative paths
• Module system chaos: Pick ESM or CommonJS and stick with it

This command reference covers everything you need for day-to-day database management with Drizzle Kit. The key is understanding when to use each command and how they fit into your development workflow.

Commands are powerful, but they're useless if you're stuck troubleshooting at 3am. Even with the best documentation, production environments have a way of surfacing the exact edge case that wasn't covered. Here are the questions that actually get asked in Discord, Stack Overflow, and GitHub issues—along with the answers that work.