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.