Drizzle Migrations
Keep Postgres (or SQL) schema changes honest in TypeScript apps by generating Drizzle migrations before touching application code.
Overview
Drizzle Migrations is an agent skill for the Build phase that enforces a migration-first Drizzle ORM workflow so schema changes start in SQL migrations, not ad-hoc TypeScript schema edits.
Install
npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill drizzle-migrationsWhat is this skill?
- Migration-first rule: SQL migrations are the single source of truth, not code-first drift
- Explicit anti-pattern callout against writing TypeScript schema files before migrations
- Environment consistency and rollback/versioning rationale
- TypeScript types generated from migrations after SQL is canonical
- CI/CD can validate schema changes when migrations lead
- Migration-first as the critical rule with six documented benefits in the skill
Adoption & trust: 659 installs on skills.sh; 53 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent keeps changing Drizzle schema files first and you end up with drift between environments and no reversible migration history.
Who is it for?
Indie SaaS and API builders on Drizzle who want one authoritative migration trail across local, staging, and production.
Skip if: Greenfield experiments where you deliberately skip migrations, or teams on unrelated ORMs (Prisma-only, raw SQL without Drizzle tooling).
When should I use this skill?
Working with Drizzle ORM in TypeScript/JavaScript when creating or modifying database schema and you want migration-first development.
What do I get? / Deliverables
Schema changes flow migration → generated types → application code, giving you versioned SQL, rollback options, and CI-friendly validation.
- Versioned SQL migration files
- Generated types aligned to migrations
- Documented rollback/version path
Recommended Skills
Journey fit
Schema design and migration files are core Build work on the backend data layer before Ship can validate schema in CI. Backend is the primary shelf because the workflow is ORM migration authoring tied to application services, not frontend or docs.
How it compares
Principles for ordered SQL migrations with Drizzle—not a generic SQL tutorial or a one-off schema generator with no versioning story.
Common Questions / FAQ
Who is drizzle-migrations for?
Solo and small-team developers building TypeScript backends with Drizzle ORM who need disciplined schema change habits for Postgres-compatible databases.
When should I use drizzle-migrations?
Use it during Build whenever you add tables, alter columns, or onboard a database—especially before merging schema-related PRs or enabling CI schema checks.
Is drizzle-migrations safe to install?
It is procedural documentation without bundled network calls in the excerpt; still review the Security Audits panel on this page before granting filesystem and shell access for drizzle-kit runs.
SKILL.md
READMESKILL.md - Drizzle Migrations
# Drizzle ORM Database Migrations (TypeScript) Migration-first database development workflow using Drizzle ORM for TypeScript/JavaScript projects. ## When to Use This Skill Use this skill when: - Working with Drizzle ORM in TypeScript/JavaScript projects - Need to create or modify database schema - Want migration-first development workflow - Setting up new database tables or columns - Need to ensure schema consistency across environments ## Core Principle: Migration-First Development **Critical Rule**: Schema changes ALWAYS start with migrations, never code-first. ### Why Migration-First? - ✅ SQL migrations are the single source of truth - ✅ Prevents schema drift between environments - ✅ Enables rollback and versioning - ✅ Forces explicit schema design decisions - ✅ TypeScript types generated from migrations - ✅ CI/CD can validate schema changes ### Anti-Pattern (Code-First) ❌ **WRONG**: Writing TypeScript schema first ```typescript // DON'T DO THIS FIRST export const users = pgTable('users', { id: uuid('id').primaryKey(), email: text('email').notNull(), }); ``` ### Correct Pattern (Migration-First) ✅ **CORRECT**: Write SQL migration first ```sql -- drizzle/0001_add_users_table.sql CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email TEXT NOT NULL UNIQUE, created_at TIMESTAMP DEFAULT NOW() ); ``` ## Complete Migration Workflow ### Step 1: Design Schema in SQL Migration Create descriptive SQL migration file: ```sql -- drizzle/0001_create_school_calendars.sql CREATE TABLE school_calendars ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE, start_date DATE NOT NULL, end_date DATE NOT NULL, academic_year TEXT NOT NULL, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW() ); -- Add indexes for query performance CREATE INDEX idx_school_calendars_school_id ON school_calendars(school_id); CREATE INDEX idx_school_calendars_academic_year ON school_calendars(academic_year); -- Add constraints ALTER TABLE school_calendars ADD CONSTRAINT check_date_range CHECK (end_date > start_date); ``` **Naming Convention**: - Use sequential numbers: `0001_`, `0002_`, etc. - Descriptive names: `create_school_calendars`, `add_user_roles` - Format: `XXXX_descriptive_name.sql` ### Step 2: Generate TypeScript Definitions Drizzle Kit generates TypeScript types from SQL: ```bash # Generate TypeScript schema and snapshots pnpm drizzle-kit generate # Or using npm npm run db:generate ``` **What This Creates**: 1. TypeScript schema files (if using `drizzle-kit push`) 2. Snapshot files in `drizzle/meta/XXXX_snapshot.json` 3. Migration metadata ### Step 3: Create Schema Snapshot Snapshots enable schema drift detection: ```json // drizzle/meta/0001_snapshot.json (auto-generated) { "version": "5", "dialect": "postgresql", "tables": { "school_calendars": { "name": "school_calendars", "columns": { "id": { "name": "id", "type": "uuid", "primaryKey": true, "notNull": true, "default": "gen_random_uuid()" }, "school_id": { "name": "school_id", "type": "uuid", "notNull": true } } } } } ``` **Snapshots in Version Control**: - ✅ Commit snapshots to git - ✅ Enables drift detection in CI - ✅ Documents schema history ### Step 4: I