Introduction

onwardpg is a PostgreSQL schema-diff planner. It turns an accepted schema and a desired schema into one reviewable, forward-only bundle around one application deployment:

compare -> expand -> deploy -> drain -> contract -> prove convergence

It is built for the awkward truth behind “simple” schema changes: old and new application processes overlap. A column rename can break an old reader. A new NOT NULL column can break an old writer. A cast from text to integer needs a product rule for malformed values.

The operating model

Expand changes the database while old code is still running. It adds compatible shape, synchronization, indexes, and explicitly reviewed data work.

Deploy rolls out code that understands both the expanded and contracted schemas.

Drain is an operational fact, not a timer: old instances, workers, queues, connection pools, and stale write paths are gone.

Contract validates assumptions, tightens constraints, and removes compatibility scaffolding.

Verify replays the exact bundle in disposable PostgreSQL and proves that the final catalog converges on the declared schema.

Planner, not deployer

onwardpg never applies SQL to production or to another caller-owned database. Your deployment system runs the reviewed phase files because it is the system that can observe rollout and drain state.

What makes it different

onwardpg materializes desired DDL in real PostgreSQL, inspects typed catalog objects and dependencies, and plans from those facts. When schema state cannot prove intent—a rename, destructive change, backfill, or cast—it asks for a fingerprint-bound decision instead of guessing.

The proof is deliberately narrow. Catalog convergence does not prove safe lock duration, application compatibility, valid production data, WAL budget, replica health, or rollback readiness. Those remain operational review inputs.

Where to begin

1. Install and configure onwardpg.
2. Create your first plan.
3. Read the expand/contract contract before wiring deployment automation.