If you are tired of digging through dozens of migration files to understand what your database actually looks like, pgdeclare might be your new best friend. Released on October 19, 2026, by the team behind Powertime, this Postgres schema differ flips the script on traditional migrations. Instead of reading deltas, you maintain a single source of truth: plain SQL files that declare the desired state of your database. The tool builds this declared schema in a scratch database, diffs it against your live instance via pg_catalog, and applies only the necessary changes.

The Shift From Deltas to Declarations

The core philosophy here is that your schema should be code you can read. Traditional migration files force reviewers and LLMs to reconstruct the current state from a series of changes, often leading to errors. pgdeclare eliminates this cognitive load. You edit the definition of a table directly, just like you would with infrastructure-as-code tools. The tool handles the complexity of figuring out what changed. For operations that cannot be inferred by a simple diff, such as column renames or data backfills, the tool supports imperative @migrate-before and @migrate-after blocks. These blocks run exactly once and are recorded in a hash ledger, ensuring that edits after execution are refused rather than silently ignored.

Built for Real-World Production

This isn't just a theoretical toy. The engine has been running the production schema for Powertime since December 10, 2025. Currently at version 0.1.2, the project warns that backwards compatibility may not be preserved until the 1.0 release, so tread carefully in production environments. The tool relies on Postgres itself to parse and order the work. It executes your SQL in a scratch 'plan' database, introspects the result, and uses a retry-until-stable mechanism to handle dependencies. This means you do not need to manually maintain a dependency order for your DDL statements.

Practical Implementation and Safety

Installation is straightforward via pip or uv, requiring Python 3.12+ and a PostgreSQL server between versions 14 and 18. The CLI provides essential safety rails, including pgdeclare diff to preview changes, pgdeclare apply --dry-run to plan without writing, and a --prove flag to rehearse the run on a throwaway clone. Destructive changes on tables with data require an explicit @drop directive, preventing accidental data loss. Migrations that have already run can be pruned from the history, keeping your repository clean while preserving the audit trail in git.

Key Takeaways

  • pgdeclare uses declarative SQL files instead of sequential migration scripts to manage schema state.
  • The tool leverages Postgres to parse SQL and resolve dependencies automatically via a scratch database.
  • Imperative blocks handle complex changes like renames, with a hash ledger preventing accidental re-runs.
  • Currently at v0.1.2, it is production-tested but not yet stable for backwards compatibility.

The Bottom Line

pgdeclare is a breath of fresh air for developers who hate the archaeology of migration files. If you value readable, declarative infrastructure, this tool is worth watching closely before it hits 1.0.