Drizzle ORM Schema Migrations Skill

Knowledge Freshness

This skill is based on Drizzle ORM's migration docs, get-started docs, official website, and drizzle-team/drizzle-orm repository reviewed on 2026-06-04. The current migration docs describe database-first and codebase-first flows with drizzle-kit pull, push, generate, migrate, and export, while the repository describes Drizzle as a headless TypeScript ORM with Drizzle Kit for SQL migration generation and direct schema changes.

Retrieval Sources

• https://orm.drizzle.team/docs/migrations
• https://orm.drizzle.team/docs/get-started
• https://orm.drizzle.team/
• https://github.com/drizzle-team/drizzle-orm

Prefer the live Drizzle docs and official repository over model memory for driver imports, migration commands, drizzle.config.ts options, supported database targets, query APIs, schema APIs, and Drizzle Kit behavior.

Scope Note

Use this skill for Drizzle ORM schema, query, and migration work in TypeScript or JavaScript projects. It is not a generic SQL tutorial, not a replacement for database administration review, and not a license to run production migrations from an AI session without explicit environment confirmation.

Core Workflow

1. Inventory the current runtime, package manager, database provider, driver, existing schema files, migration folder, drizzle.config.ts, CI migration steps, and production deployment process.
2. Decide the schema source of truth: database-first pull, codebase-first direct push, generated SQL migrations, runtime migration, external migration tool, or SQL export.
3. Add drizzle-orm and drizzle-kit with the project package manager, then choose the correct Drizzle driver package and imports for the database target.
4. Create or review drizzle.config.ts with explicit schema path, output path, dialect, credentials strategy, casing, and environment loading behavior.
5. Model tables, columns, constraints, indexes, relations, enums, views, and custom types from product requirements rather than from guessed field names.
6. Review generated SQL from drizzle-kit generate before applying it. Treat destructive diffs, renames, type changes, and constraint additions as production migration risks.
7. Use drizzle-kit push only when direct schema application is appropriate for the environment and the team accepts its review model.
8. Use drizzle-kit pull when the database is the source of truth and the task is to generate TypeScript schema from an existing database.
9. Add typed query helpers, transactions, and shared filters close to data access code, keeping authorization checks near the database boundary.
10. If using Drizzle Studio, document access controls, local-only assumptions, credentials, and whether real production data is visible.
11. Add validation for generated migrations in CI without exposing database credentials or running destructive operations against production by default.
12. Produce a rollout plan with backup, lock-risk review, migration apply step, application deploy order, smoke tests, monitoring, and rollback.

Required Inputs

• Runtime, framework, package manager, deployment platform, and database target.
• Existing ORM or query layer, migration tool, schema files, generated files, and CI/deploy migration behavior.
• Drizzle source-of-truth decision: pull, push, generate/migrate, runtime migrate, external migration tool, or SQL export.
• Database URL management path for local, preview, staging, and production.
• Tables, columns, relations, indexes, constraints, tenants, user ownership, soft-delete policy, audit fields, and data retention needs.
• Production data size, lock tolerance, backup path, rollback path, and maintenance-window expectations for risky migrations.
• Whether Drizzle Studio, seed scripts, generated migrations, and schema snapshots are allowed in local, CI, preview, or production contexts.

Production Rules

• Never run schema-mutating commands until the target database environment is explicit. Local, preview, staging, and production URLs must be visually distinct in commands and logs.
• Review generated SQL before apply. Do not blindly trust a migration that drops columns, renames objects, rewrites large tables, adds non-null constraints, or changes enum semantics.
• Keep migration credentials separate from application runtime credentials when possible. App runtime usually should not have schema-owner permissions.
• Commit migration files only when the team has chosen generated SQL migrations as the source of truth. Avoid hand-editing generated snapshots without a clear reason and review path.
• Prefer expand-contract migrations for production column renames, type changes, and data backfills. Separate data backfills from schema changes when blast radius is high.
• Treat Drizzle Studio as a privileged database browser. Keep it local or protected, and avoid exposing production data through screenshots or tunnels.
• Use synthetic schemas and data in examples. Do not paste real table exports, connection strings, migration logs, or customer rows into AI prompts.
• Include rollback limits honestly. Some schema changes can be rolled back only from backup or a forward-fix migration.

Compatibility

Native

• Claude Code / Claude: use as a reusable Agent Skill for Drizzle schema design, query implementation, migration review, and rollout planning.
• Codex/OpenAI workflows: use as SKILL.md-style instructions when editing TypeScript projects that use Drizzle ORM.

Manual Adaptation

• Cursor, Windsurf, Gemini, and Generic AGENTS files: adapt the trigger, workflow, safety notes, privacy notes, and output contract into repository rules for Drizzle database work.

Output Contract

1. Source evidence: Drizzle docs, website, and repository URLs reviewed, with date.
2. Inventory: database target, schema source of truth, existing ORM/query layer, migration folder, Drizzle config, generated files, and deployment flow.
3. Implementation plan: packages, driver, config, schema files, queries, relations, indexes, migrations, Studio usage, and CI validation.
4. Safety and privacy review: target environment, secrets, generated SQL, destructive changes, database locks, Studio exposure, logs, prompts, and production data handling.
5. Validation checklist: typecheck, generated migration review, dry-run or staging apply, rollback review, app smoke test, query authorization test, performance check, and production deploy notes.

Duplicate And Source Review

Current HeyClaude content mentions Drizzle inside generic agent and command examples, but there is no dedicated Drizzle, Drizzle Kit, drizzle-orm, or orm.drizzle.team content entry. This skill is specifically scoped to Drizzle ORM schema and migration workflows and is source-backed by the current Drizzle docs, website, and official repository.

Troubleshooting

Issue: drizzle-kit generate creates an unexpected migration

Fix: Check the schema source of truth, prior migration folder, snapshots, renames, casing, dialect, and config path before applying anything to a shared database.

Issue: A migration targets the wrong database

Fix: Stop before apply, print the sanitized environment name, inspect the loaded config, and verify the connection source. Do not rely on shell history or default .env behavior for production migrations.

Issue: drizzle-kit push wants to drop or rewrite objects

Fix: Switch to generated SQL review or an external migration process, confirm whether the diff represents a rename or destructive change, and plan an expand-contract rollout if production data is involved.

Issue: App queries are typed but still leak tenant data

Fix: Add server-side authorization filters near the query boundary. Type safety does not replace ownership, tenant, role, or row-level access checks.

Issue: Drizzle Studio exposes sensitive data

Fix: Disable public access, avoid tunnels to real production data, rotate any credentials that were exposed, and use synthetic or scrubbed datasets for demos.