db-migrations

Generates and hardens Drizzle ORM PostgreSQL migrations with idempotent SQL and rollout strategies.

74|11|Updated Jul 4, 2024
One-click install
npx skills add https://github.com/OpenSourceAGI/qwksearch-research-agent --skill db-migrations-opensourceagi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: db-migrations
Source: https://github.com/OpenSourceAGI/qwksearch-research-agent/tree/main/apps/qwk-in-lobe/.agents/skills/db-migrations
Command: npx skills add https://github.com/OpenSourceAGI/qwksearch-research-agent --skill db-migrations-opensourceagi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Database schema changes in production are risky: blocking index creation, non-idempotent SQL, rebase conflicts in migration files, and backfills that stall deployments. This Skill provides a structured workflow for planning, generating, and hardening Drizzle ORM migrations so schema changes ship 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 the actual Dev database. - Migration Generation & Hardening: Runs bun run db:generate, renames files meaningfully, updates journal tags, and rewrites SQL with defensive clauses like IF NOT EXISTS and DROP IF EXISTS + ADD for foreign keys. - Development-Stage Cleanup: Handles draft migration regeneration, consolidation of multiple branch migrations, and rebase conflict resolution by regenerating from the rebased schema. - Use Case: When adding a column and index to a large users table, the Skill guides you to create the index manually with CONCURRENTLY before deployment, keep an idempotent non-concurrent version in the migration, and validate timing assumptions on the Dev database first. ## Quick Start Ask the agent to plan and generate a safe Drizzle migration for adding a new column and index to an existing PostgreSQL table.

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 ORM migration?

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

How to create a PostgreSQL index without blocking production writes?

Run CREATE INDEX CONCURRENTLY manually in the database SQL editor before deployment, and keep an idempotent non-concurrent 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 should run as dedicated, idempotent, resumable scripts processed in bounded batches, separate from the schema migration. Run them before deployment if new constraints require populated rows, or after if the app handles both row shapes.

How do I resolve migration conflicts after a git rebase?

Keep the upstream branch migrations and delete all migrations introduced by your feature branch, including SQL files, snapshots, and journal entries. Complete the rebase, then regenerate your branch's migration from the rebased schema.

Why avoid pgEnum for columns with growing value sets?

pgEnum requires an ALTER TYPE ADD VALUE migration for every new literal. Use a plain text column typed with .$type<UnionType>() instead, so adding a value becomes a type-only change with no migration needed.

Can I edit a migration after it reaches production?

No. Once a migration has shipped to production or the default branch, treat it as immutable and add a follow-up migration instead. Hand-editing is only acceptable for unshipped draft migrations, which should be deleted and regenerated.