Drizzle Migrations

Manage Drizzle schema evolution with drizzle-kit generate/push/migrate and introspect

When to Use

• Generating SQL migration files from schema changes
• Applying migrations to development or production databases
• Prototyping schema changes rapidly with

  push

• Introspecting an existing database to generate a Drizzle schema

Instructions

1. Configure drizzle-kit in

   drizzle.config.ts

   :

import { defineConfig } from 'drizzle-kit';

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

2. Generate a migration after editing the schema:

npx drizzle-kit generate

This creates a SQL migration file in the

out

drizzle/0001_add_posts_table.sql

3. Apply migrations programmatically at startup:

import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { db } from './db';

await migrate(db, { migrationsFolder: './drizzle' });

4. Push for rapid prototyping — applies schema changes directly without generating migration files:

npx drizzle-kit push

Use

push

5. Introspect an existing database to generate a Drizzle schema:

npx drizzle-kit introspect

This creates a TypeScript schema file matching the current database structure.

6. Review generated SQL before applying. Open the migration file and verify:

   • Column types match your intent
   • Destructive operations (DROP, ALTER TYPE) are safe
   • Data migration steps are included where needed

7. Custom migration SQL — edit generated files to add data migrations:

-- Generated: add status column
ALTER TABLE "posts" ADD COLUMN "status" text DEFAULT 'draft' NOT NULL;

-- Custom: backfill existing records
UPDATE "posts" SET "status" = 'published' WHERE "published" = true;

8. Check for migration issues before generating:

npx drizzle-kit check

9. Drop migrations that have not been applied (development only):

npx drizzle-kit drop

Details

Drizzle Kit is the CLI companion to Drizzle ORM. It reads your TypeScript schema and generates SQL migration files by diffing the schema against the migration history.

Migration tracking: Drizzle creates a

__drizzle_migrations

generate

push

generate

push

push

Migration file structure:

drizzle/
  0000_initial.sql
  0001_add_posts.sql
  0002_add_comments.sql
  meta/
    0000_snapshot.json
    0001_snapshot.json
    _journal.json

The

meta/

Programmatic migration: Unlike Prisma's

migrate deploy

Trade-offs:

• No shadow database needed — Drizzle diffs against snapshots, not a separate database
• Migration files are plain SQL — easy to review but no built-in rollback mechanism

• push

  is fast but dangerous — it can drop columns without warning in development
• No built-in

  reset

  command — drop the database manually and re-run migrations for a clean slate

Source

https://orm.drizzle.team/docs/migrations

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.