db-migrations

Generates and hardens Drizzle migrations with idempotent SQL, online indexes, and backfill strategies.

Updated Jan 27, 2026
One-click install
npx skills add https://github.com/SmallAi-API/smaihub --skill db-migrations-smallai-api
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: db-migrations
Source: https://github.com/SmallAi-API/smaihub/tree/main/.agents/skills/db-migrations
Command: npx skills add https://github.com/SmallAi-API/smaihub --skill db-migrations-smallai-api

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Database schema changes in a Drizzle/PostgreSQL project often ship with risky migrations: non-idempotent SQL that fails on re-run, blocking index creation on large tables, backfills crammed into deploy-time migrations, and rebase conflicts that corrupt migration journals. This Skill provides the conventions and rollout strategies to generate, review, and ship migrations safely. ## Core Features & Use Cases - Rollout strategy classification: Routes every schema change into one of three paths — regular Drizzle migration, online index creation with CONCURRENTLY, or a dedicated idempotent backfill script — validated against real Dev database measurements. - Migration hardening: Renames generated files meaningfully, adds idempotent clauses (IF NOT EXISTS, drop-then-add constraints), and keeps _journal.json tags in sync. - Development-stage cleanup: Regenerates draft migrations after schema churn, consolidates stacked branch migrations, and resolves rebase conflicts by regenerating from the rebased schema. - Use Case: When adding an index to a large production table, run CREATE INDEX CONCURRENTLY manually before deployment while keeping an idempotent non-concurrent version in the migration so deploys never block. ## Quick Start Ask the AI to generate a Drizzle migration for your schema change and review it for idempotency, rollout safety, and correct journal entries.

Frequently Asked Questions about db-migrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a Drizzle migration after changing the schema?

Run bun run db:generate after updating the Drizzle schema. This creates the SQL migration file and updates the journal, snapshot, and migrations.json. Then rename the file meaningfully and add idempotent clauses before shipping.

How do I create an index on a large PostgreSQL table without blocking deployment?

Run CREATE INDEX CONCURRENTLY manually in the database SQL editor before deploying, and keep an idempotent CREATE INDEX IF NOT EXISTS version in the Drizzle migration. Never place CONCURRENTLY inside a transaction.

Should data backfills run inside a Drizzle migration?

No. Backfills must run as dedicated, idempotent scripts separate from the migration so they do not block deployment. Make them resumable, batch-processed, and safe to retry, running before or after deployment based on compatibility.

How do I resolve rebase conflicts in Drizzle migration files?

Keep the upstream branch's migrations, delete all migrations introduced by your feature branch, finish the rebase, then regenerate your branch's migration from the rebased schema. Never hand-merge snapshots or journal entries.

When should I use text with $type instead of pgEnum in Drizzle?

Use a plain text column with .$type<UnionType>() for value sets that will keep growing, such as resource types or statuses. pgEnum requires an ALTER TYPE migration for every new value, while $type makes additions a type-only change.

Can I edit an existing draft migration when the schema changes during development?

Do not hand-edit draft migration SQL. Delete the branch's draft SQL file, snapshot, and journal entry, then regenerate with bun run db:generate so artifacts stay aligned with the current schema.