This Claude skill streamlines the database management process by automating migrations with Drizzle Kit. It enables developers to seamlessly synchronize TypeScript schema definitions with SQL migration files, ensuring data integrity and reducing the risk of manual errors during schema updates, table modifications, or index creation.

When should I use db-migrate?

db-migrate is useful in the following scenarios: • Automating the generation of SQL migration files after modifying TypeScript schema definitions in Drizzle ORM. • Ensuring consistency between the application's data models and the physical database structure during collaborative development. • Safely adding, renaming, or deleting database columns and tables with a structured, reviewable migration workflow. • Optimizing database performance by programmatically adding or modifying indexes and verifying them through generated SQL scripts.

name	db-migrate
description	Create database migrations using Drizzle Kit. Use when adding/modifying tables, columns, or indexes. Ensures schema.ts and migrations stay in sync.
allowed-tools	Read, Grep, Glob, Edit, Write, Bash

Database Migration Skill

Create schema changes with proper migrations.

Before Starting

Read current schema: src/lib/schema.ts
Read recent migrations: drizzle/*.sql (last 2-3)
Understand current state before making changes

Workflow

Step 1: Modify Schema First

Edit src/lib/schema.ts with your changes:

Add new tables with pgTable()
Add columns to existing tables
Add/modify indexes

Step 2: Generate Migration

Run Drizzle Kit to generate migration SQL:

pnpm drizzle-kit generate

This creates a new file in drizzle/ like 0011_descriptive_name.sql.

Step 3: Review Generated Migration

Read the generated migration and verify:

SQL looks correct
No destructive changes (DROP without intent)
Index names follow convention
Column types match schema.ts

Step 4: Test Locally (Optional - Be Careful!)

WARNING: Only test migrations locally if POSTGRES_URL points to a LOCAL database. If it points to production, skip this step - migrations will run automatically on Vercel deploy.

To check your database URL:

echo $POSTGRES_URL  # Should be localhost or local container

If local database is configured:

pnpm build  # Runs migrations automatically
pnpm cli stats  # Verify queries work

Step 5: Verify in PR

Migration SQL looks correct (review diff)
schema.ts and migration are in same commit
No IF NOT EXISTS clauses (signals potential drift)

Common Patterns

Adding a Column

// schema.ts
export const myTable = pgTable('my_table', {
  // existing columns...
  newColumn: varchar('new_column', { length: 255 }),
});

Adding an Index

export const myTable = pgTable('my_table', {
  // columns...
}, (table) => [
  index('idx_my_table_column').on(table.column),
]);

Adding a Table

export const newTable = pgTable('new_table', {
  id: serial('id').primaryKey(),
  // columns...
}, (table) => [
  // indexes...
]);

Anti-Patterns (Don't Do This)

Editing schema.ts without running drizzle-kit generate
Writing migration SQL by hand (use generate)
Modifying existing migrations after they've been applied to prod
Using IF NOT EXISTS in new migrations (signals drift)

Checklist

Before committing:

schema.ts changes match generated migration
Migration tested locally with pnpm build (only if local DB configured)
No IF NOT EXISTS clauses (clean migration)
Both schema.ts and migration in same commit

db-migrate

When & Why to Use This Skill

Use Cases