mcpField
D
drizzle-safe-migrations

drizzle-safe-migrations

github.com/pedronauckData & databases644323 installsUpdated 1w ago
Repository

About drizzle-safe-migrations

drizzle-safe-migrations is a skill for teams running Drizzle database migrations with attention to auditability and deployment safety. It guides schema and data changes through ordered generation, validation, and rollout planning.

Key features

  1. 01Classifies schema-only and data-plus-schema changes
  2. 02Creates custom migrations for data backfills
  3. 03Keeps generated schema migrations unedited
  4. 04Checks migration order in the Drizzle journal
  5. 05Validates existing-data and fresh-install cases
  6. 06Records rollout risks and recovery steps

Use cases

  1. 01Backfilling rows before tightening constraints
  2. 02Reviewing migration order and generated SQL
  3. 03Planning safe deployment of schema changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/pedronauck/skills --skill drizzle-safe-migrations

After installing, type/drizzle-safe-migrationsin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlreferences/production-playbook.md

Details

From the project README

Drizzle Safe Migrations

Overview

Use this skill to run database migrations in a way that is auditable, deployment-safe, and consistent with Drizzle's migration model.

Core Rules

  • Generate schema migrations with the existing project script and package manager; bun run db:generate below is an example, not a required script name.
  • Never hand-edit generated schema migration files.
  • Generate data backfills as custom migrations (bun run db:generate -- --custom --name <name>) and edit only that custom SQL file.
  • Apply data normalization before tightening constraints.
  • Keep one-off data fixes in migration history, not as hidden runtime logic, unless an emergency hotfix requires temporary mitigation.

Workflow

  1. Classify the change:
    • schema-only: only column/table/index/default changes.
    • data+schema: old rows must be transformed before new constraints/defaults.
  2. For data+schema, create custom migration first:
    • bun run db:generate -- --custom --name <descriptive_name>
    • Add idempotent backfill SQL.
  3. Generate schema migration second:
    • bun run db:generate
  4. Verify migration ordering in drizzle/meta/_journal.json:
    • backfill migration index must be lower than constraint-tightening migration index.
  5. Verify generated SQL and snapshots:
    • backfill migration contains only intended data change.
    • schema migration contains constraint/default/type changes.
  6. Run the owning migration suite against existing-data and fresh-install cases, plus required project gates. Reuse current evidence; unrelated backend suites are not an additional skill gate.
  7. Record material rollout risks and recovery steps when applicable:
    • expected data transformations,
    • lock-risk areas,
    • rollback strategy.

Backfill Requirements

  • Use restrictive WHERE clauses.
  • Prefer idempotent updates (UPDATE ... WHERE status = 'legacy_value').
  • Do not mix unrelated DDL/DML in the same migration.
  • Keep SQL explicit and minimal.

Constraint Tightening Pattern

When removing allowed values (enum/check):

  1. Backfill existing rows to valid target value.
  2. Update default to new value.
  3. Tighten check/enum constraint.

For large tables or strict uptime targets, evaluate staged constraint validation supported by the actual database and driver. PostgreSQL NOT VALID / VALIDATE CONSTRAINT applies only to supported constraint kinds.

Anti-Patterns

  • Hand-editing generated schema migration files.
  • Tightening constraints before backfilling existing data.
  • Hiding one-time migration logic in app startup code without migration artifacts.
  • Running migrations without validating order in the Drizzle journal.

Reference

  • See references/production-playbook.md for command templates and review checklists.

Comments

Markdown supported