void-migrations

Enforces zero-downtime Postgres migration patterns with two-phase changes and batched backfills.

Updated May 29, 2026
One-click install
npx skills add https://github.com/voidcorp-core/void-harness --skill void-migrations-voidcorp-core
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: void-migrations
Source: https://github.com/voidcorp-core/void-harness/tree/main/packages/core/skills/void-migrations
Command: npx skills add https://github.com/voidcorp-core/void-harness --skill void-migrations-voidcorp-core

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Database schema changes like adding a NOT NULL column or renaming a column can lock large Postgres tables for minutes and break running code. This Skill encodes safe migration discipline so every schema change avoids downtime-inducing DDL patterns. ## Core Features & Use Cases - Two-Phase Migration Pattern: Splits risky DDL into a backwards-compatible migration, a code deploy, a batched backfill, and a constraint-tightening migration. - Banned DDL Detection: Blocks direct NOT NULL adds, RENAME COLUMN, blocking CREATE INDEX, and edits to already-merged migrations, with CONCURRENTLY indexes as the safe alternative. - Mandatory PR Template: Requires locking impact, row counts, backfill strategy, rollback plan, and dev-branch test evidence in every migration PR. - Use Case: When adding a required status column to a 10M-row orders table, the Skill guides you through a nullable column add, a 10k-row batched backfill with progress logging, and a separate migration that sets NOT NULL. ## Quick Start Ask the agent to add a new required column to an existing Postgres table and it will produce a two-phase Drizzle migration with a batched backfill and a complete safety PR template.

Frequently Asked Questions about void-migrations

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

FAQPage Schema
How do I add a NOT NULL column to a large Postgres table without downtime?

Add the column as nullable in one migration, deploy code that handles both shapes, backfill in batches of about 10k rows per transaction, then set NOT NULL in a second migration. A direct ADD COLUMN NOT NULL DEFAULT rewrites the table and holds an AccessExclusiveLock.

How to rename a Postgres column without breaking running code?

Use a two-phase approach: add the new column, deploy code that dual-writes both columns, backfill the new column in batches, switch reads to it, then drop the old column in a later migration. A direct RENAME COLUMN breaks active requests immediately.

Does CREATE INDEX lock a Postgres table?

A plain CREATE INDEX blocks writes on the table while it builds. Use CREATE INDEX CONCURRENTLY instead, which does not block reads or writes; it is slower but safe for large production tables.

Can I edit a migration file after it has been merged?

No. Merged migrations are immutable because other environments have already applied them, so mutating one diverges state. Fix forward by writing a new migration that corrects the problem.

When should I use pgroll instead of two-phase migrations?

Consider pgroll for tables over 100M rows or critical 24/7 surfaces where even a two-phase window is a concern. It provides multi-version schemas so old and new shapes coexist; the default two-phase discipline covers most other cases.