pgdeclare 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. pgdeclare-0.1.2/CHANGELOG.md +211 -0
  2. pgdeclare-0.1.2/PKG-INFO +150 -0
  3. pgdeclare-0.1.2/README.md +117 -0
  4. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/pyproject.toml +1 -1
  5. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/__init__.py +42 -1
  6. pgdeclare-0.1.2/src/pgdeclare/changes.py +3818 -0
  7. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/cli.py +112 -11
  8. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/config.py +9 -0
  9. pgdeclare-0.1.2/src/pgdeclare/differ.py +2604 -0
  10. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/executor.py +118 -13
  11. pgdeclare-0.1.2/src/pgdeclare/introspection.py +2380 -0
  12. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/migrate.py +132 -10
  13. pgdeclare-0.1.2/src/pgdeclare/models.py +1379 -0
  14. pgdeclare-0.1.2/src/pgdeclare/prove.py +413 -0
  15. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/retry_executor.py +3 -0
  16. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/schema_parser.py +286 -3
  17. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/statement_parser.py +228 -11
  18. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_boundary.py +1 -1
  19. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_cli.py +224 -0
  20. pgdeclare-0.1.2/tests/test_comments.py +428 -0
  21. pgdeclare-0.1.2/tests/test_default_privileges.py +436 -0
  22. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_diff.py +29 -2
  23. pgdeclare-0.1.2/tests/test_domains.py +493 -0
  24. pgdeclare-0.1.2/tests/test_foreign_data.py +945 -0
  25. pgdeclare-0.1.2/tests/test_materialized_views.py +569 -0
  26. pgdeclare-0.1.2/tests/test_partitions.py +745 -0
  27. pgdeclare-0.1.2/tests/test_prove.py +410 -0
  28. pgdeclare-0.1.2/tests/test_publications_rules.py +895 -0
  29. pgdeclare-0.1.2/tests/test_ranges_collations.py +729 -0
  30. pgdeclare-0.1.2/tests/test_routines.py +541 -0
  31. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_security.py +13 -1
  32. pgdeclare-0.1.2/tests/test_sequences.py +486 -0
  33. pgdeclare-0.1.2/tests/test_views.py +244 -0
  34. pgdeclare-0.1.0/CHANGELOG.md +0 -68
  35. pgdeclare-0.1.0/PKG-INFO +0 -403
  36. pgdeclare-0.1.0/README.md +0 -370
  37. pgdeclare-0.1.0/src/pgdeclare/changes.py +0 -1528
  38. pgdeclare-0.1.0/src/pgdeclare/differ.py +0 -999
  39. pgdeclare-0.1.0/src/pgdeclare/introspection.py +0 -979
  40. pgdeclare-0.1.0/src/pgdeclare/models.py +0 -603
  41. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/.gitignore +0 -0
  42. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/LICENSE +0 -0
  43. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/NOTICE +0 -0
  44. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/__main__.py +0 -0
  45. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/drop_directive.py +0 -0
  46. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/ledger.py +0 -0
  47. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/py.typed +0 -0
  48. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/quoting.py +0 -0
  49. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/conftest.py +0 -0
  50. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/dbutil.py +0 -0
  51. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_integration.py +0 -0
  52. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_lifecycle.py +0 -0
  53. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_pipeline.py +0 -0
  54. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_retry_executor.py +0 -0
  55. {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_statement_parser.py +0 -0
@@ -0,0 +1,211 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0 the API
6
+ may change in minor releases.
7
+
8
+ ## [0.1.2] - 2026-10-19
9
+
10
+ ### Changed
11
+
12
+ - A view whose query changes while every existing output column keeps its
13
+ name, type and collation (new columns may be appended) is now replaced in
14
+ place with `CREATE OR REPLACE VIEW`, online, instead of dropped and
15
+ re-created. The view keeps its OID, so its grants, comments and owner stay,
16
+ and the views, materialized views and SQL functions reading from it are not
17
+ dropped and rebuilt. A materialized view reading from it keeps its data
18
+ until it is refreshed. A renamed, retyped, reordered or removed column still
19
+ drops and re-creates the view with its dependents.
20
+
21
+ ## [0.1.1] - 2026-10-18
22
+
23
+ ### Added
24
+
25
+ - `--prove` (`diff --prove`, `apply --dry-run --prove`): rehearse the real
26
+ run, pending `@migrate` blocks included, on a throwaway clone of the
27
+ target; it fails if a second diff still finds work or a table lost rows
28
+ without a `@drop` directive.
29
+ - Standalone sequences (`CREATE SEQUENCE`) in the managed schemas: created
30
+ with every option spelled out, options converged with `ALTER SEQUENCE`
31
+ (never `RESTART`, so the current value is kept), `OWNED BY` a column, and
32
+ dropped when undeclared (without `CASCADE`, so a default still using one
33
+ refuses the drop). Sequences are created before tables, so a `nextval()`
34
+ column default resolves; identity-column sequences stay with their column.
35
+ - Grants to managed roles on sequences (`USAGE`, `SELECT`, `UPDATE`).
36
+ - Domains (`CREATE DOMAIN`): created; default, NOT NULL and CHECK
37
+ constraints altered in place; a base type or collation change drops and
38
+ re-creates the domain while nothing uses it, and is refused naming the
39
+ dependents otherwise; dropped when undeclared.
40
+ - Materialized views: created `WITH DATA` or `WITH NO DATA` as declared,
41
+ storage options converged in place, a changed query dropped and re-created
42
+ (offline) with its indexes and grants in the same statement; grants on
43
+ them are managed.
44
+ - Comments (`COMMENT ON`) on the managed objects: created, updated and
45
+ removed, in a phase after the DDL and index builds, and written again for
46
+ an object the run recreates.
47
+ - Procedures, aggregates and window functions are managed like functions:
48
+ created, replaced with `CREATE OR REPLACE` when the signature, return type
49
+ and kind are unchanged, otherwise dropped and re-created, and dropped when
50
+ undeclared. Aggregates are rendered from `pg_aggregate`, built after the
51
+ functions they call, and re-created when one of those is dropped. Grants to
52
+ managed roles use `ON PROCEDURE` for procedures, and `COMMENT ON PROCEDURE`
53
+ and `COMMENT ON AGGREGATE` are managed.
54
+ - Default privileges (`ALTER DEFAULT PRIVILEGES [FOR ROLE] [IN SCHEMA] GRANT
55
+ ... ON TABLES | SEQUENCES | FUNCTIONS | ROUTINES | TYPES | SCHEMAS`) granted
56
+ to managed roles, schema-less or in a managed schema: declaring grants,
57
+ removing revokes, a change converges. The plan database runs them before
58
+ the other statements, so every declared object they cover gets the grant.
59
+ - Range types (`CREATE TYPE ... AS RANGE`) in the managed schemas, with
60
+ their multirange: created with every option (subtype, operator class,
61
+ collation, canonical and subtype_diff functions, multirange name); dropped
62
+ and recreated on a change while nothing uses them, otherwise refused naming
63
+ the dependents; dropped when undeclared, after the columns using them.
64
+ Comments on them are managed.
65
+ - Collations (`CREATE COLLATION`, libc, ICU and builtin providers) in the
66
+ managed schemas: created, recreated on a change while nothing uses them
67
+ (refused naming the dependents otherwise), dropped when undeclared after
68
+ everything using them. Comments on them are managed.
69
+ - Column collations are compared and converged (`ALTER COLUMN ... TYPE ...
70
+ COLLATE`), and a new table or column is created with its declared
71
+ `COLLATE`, which used to be dropped.
72
+ - Publications: created, converged in place (`ALTER PUBLICATION ... ADD` /
73
+ `DROP` tables and `TABLES IN SCHEMA`, column lists and row filters on
74
+ PostgreSQL 15+, `SET (...)` publish options) and dropped when undeclared,
75
+ but only when every table they publish is managed. `FOR ALL TABLES` and
76
+ empty publications are never dropped unless declared. Subscriptions are not
77
+ managed.
78
+ - Rewrite rules on tables (`CREATE OR REPLACE RULE`, enabled state), never a
79
+ view's `_RETURN` rule.
80
+ - Event triggers (event, `WHEN TAG` filter, function, enabled state); an
81
+ undeclared one is dropped only when its function is in a managed schema.
82
+ Creating one needs a superuser.
83
+ - Declarative partitioning: partitioned tables (`PARTITION BY RANGE`, `LIST`,
84
+ `HASH`) and their partitions (`PARTITION OF ... FOR VALUES` or `DEFAULT`,
85
+ sub-partitioned ones included). Columns, defaults, NOT NULL, constraints,
86
+ indexes and triggers a partition inherits are not diffed on the partition.
87
+ A changed bound is a `DETACH` and `ATTACH` (offline). A partition the schema
88
+ files do not declare, such as one pg_partman created, is never dropped; the
89
+ output notes it. An index on a partitioned table is built `CONCURRENTLY` on
90
+ each partition and attached to an `ON ONLY` parent index. Converting a table
91
+ to or from partitioned, or changing its partition key, is refused with an
92
+ error pointing to `@migrate-before`.
93
+ - Foreign data: foreign tables in the managed schemas (created, altered with
94
+ one `ALTER FOREIGN TABLE`, recreated on a new server, dropped when
95
+ undeclared), foreign servers and user mappings (created and their options
96
+ converged; servers are never dropped, a managed role's undeclared mapping on
97
+ a declared server is). User-mapping option values other than `user` and
98
+ `password_required` are masked in `diff`, JSON, dry-run, prove output and
99
+ logs, and a secret option the declaration omits is left alone.
100
+ - Extensions are modelled: declared ones are created with their schema,
101
+ version and `CASCADE`, a declared version is reached with `ALTER EXTENSION
102
+ ... UPDATE TO`, and an undeclared extension is reported as a note rather
103
+ than dropped, unless a `-- @drop extension:NAME` directive consents. The CLI
104
+ no longer installs declared extensions in the target before the run; the
105
+ diff does, so `diff` shows them.
106
+ - Opt-in ownership (`manage_ownership`, `--manage-ownership`): an owner the
107
+ schema files state with `ALTER ... OWNER TO`, when it is a managed role, is
108
+ converged on tables (partitioned ones too), foreign tables, views,
109
+ materialized views, sequences, functions, procedures, aggregates, enum,
110
+ composite and range types, domains, collations and the managed schemas,
111
+ including after a recreate. The owner's implicit privileges are left out of
112
+ the grant diff on that exact object only (kind and, for a routine,
113
+ signature), so a grant to the owner on a same-named object or another
114
+ overload is still converged.
115
+
116
+ ### Changed
117
+
118
+ - README: the plan database's privilege needs, the PostgreSQL 14 `public`
119
+ ownership caveat, a corrected Python example, and a comparison with other
120
+ tools.
121
+
122
+ ### Fixed
123
+
124
+ - `CREATE TABLE` quotes inline constraint names, so a name with a quote in it
125
+ stays a name instead of breaking (or injecting into) the statement.
126
+ - A `DROP` written without `CASCADE` that fails because another object
127
+ still depends on it (`2BP01`) is retried after the rest, like a missing
128
+ dependency: views, materialized views, domains, range types, collations,
129
+ extensions and foreign tables. Dropping a stack of views no longer depends
130
+ on the order they were listed in.
131
+ - Grants on functions, procedures and aggregates name the overload, so a
132
+ grant on one of several functions sharing a name is diffed and applied on
133
+ that one instead of failing as ambiguous.
134
+ - No `REVOKE` is planned on a table, view or materialized view the same run
135
+ drops; it used to fail on the missing relation and leave the run stuck.
136
+ - `serial` and `bigserial` columns on a fresh database: the table's
137
+ `nextval()` default used to name a sequence that was never created.
138
+ - A managed role that exists nowhere is a clear error naming the role, not a
139
+ raw `UndefinedObject` traceback from introspection.
140
+ - `apply --dry-run` with pending `@migrate-before` blocks reports drops it
141
+ cannot rule out (a rename looks like drop plus add) as warnings, instead of
142
+ failing with a `@drop` error the real run would not raise.
143
+ - A role without `CREATEDB` is told to create a plan database and pass
144
+ `--plan-database`, instead of a bare permission error.
145
+ - A key=value connection string passed to the library no longer builds the
146
+ plan in the target database: the plan database name is now substituted into
147
+ it, as it already was for `postgresql://` URLs.
148
+
149
+ ## [0.1.0] - 2026-10-16
150
+
151
+ First real release: a schema engine proven in production, extracted and made generic.
152
+
153
+ ### Added
154
+
155
+ - Declarative schema files as the source of truth: the declared schema is built
156
+ in a scratch plan database, introspected through `pg_catalog`, and diffed
157
+ against the live database.
158
+ - `@migrate-before` / `@migrate-after` inline blocks for renames and
159
+ backfills, run once per database and recorded in a hash ledger
160
+ (`pgdeclare.applied_migrations` by default). An edited block is refused, not
161
+ silently skipped.
162
+ - `@drop` directives: dropping a table or column that holds data needs
163
+ explicit consent.
164
+ - Online / offline / blocked classification of every change; offline changes
165
+ need an explicit opt-in.
166
+ - Tables, columns (identity, generated, defaults), constraints, indexes (built
167
+ `CONCURRENTLY`), enums, composite types, views (including `WITH (...)`
168
+ options such as `security_invoker`), functions, triggers, row level security
169
+ and policies, and grants, roles and memberships for managed roles.
170
+ - `PgDeclareConfig`: every project-specific choice (schemas, search path,
171
+ roles, ledger table, file layout, bootstrap SQL, locking, failure
172
+ classification, output) in one frozen object with neutral defaults.
173
+ - The `pgdeclare` command line: `diff` (with `--json` and `--exit-code`) and
174
+ `apply` (with `--dry-run`, `--offline`, `--force`).
175
+ - Typed package (`py.typed`).
176
+
177
+ ### Hardening carried over from production use
178
+
179
+ - Retry-until-stable execution, both when loading the schema files and when
180
+ applying changes, instead of a hand-maintained dependency order.
181
+ - A convergence check: after applying, a second diff must find nothing.
182
+ - Revokes are ordered before grants, so narrowing a table-wide privilege to
183
+ per-column privileges cannot wipe the new column grants.
184
+ - Grants on a recreated view or function, and a SECURITY DEFINER function's
185
+ `PUBLIC` EXECUTE revoke, are applied inside the same statement as the
186
+ recreate, so no execution order can leave the object with the wrong ACL.
187
+ - UNIQUE and EXCLUDE constraints are never inlined into `CREATE TABLE`, where
188
+ PostgreSQL silently discards one that duplicates the primary key.
189
+ - Recreated CHECK and FOREIGN KEY constraints are validated, so they do not
190
+ stay `NOT VALID` and reappear in every diff.
191
+ - A server that goes away mid-run is reported as an infrastructure failure, not
192
+ as a defect in the schema files.
193
+ - Identifiers are quoted with embedded quotes doubled, literals escaped, and
194
+ `DO` blocks use a dollar tag their body cannot contain, so a hostile object
195
+ name in the live catalog cannot inject SQL.
196
+ - Declared role passwords are masked in every printed, logged or JSON output
197
+ (`Change.to_display_sql()`); only executed SQL carries them.
198
+ - Schemas the engine creates are no longer opened to `PUBLIC` unless
199
+ `grant_public_on_created_schemas` is set.
200
+ - Objects owned by extensions are left out of introspection.
201
+ - PostgreSQL 18 `NOT NULL` constraint rows are not managed twice; nullability
202
+ stays a column property on every version.
203
+
204
+ ## [0.0.1] - 2026-10-16
205
+
206
+ Placeholder release to reserve the name on PyPI. No functionality.
207
+
208
+ [0.1.2]: https://github.com/powertime-org/pgdeclare/compare/v0.1.1...v0.1.2
209
+ [0.1.1]: https://github.com/powertime-org/pgdeclare/compare/v0.1.0...v0.1.1
210
+ [0.1.0]: https://github.com/powertime-org/pgdeclare/compare/v0.0.1...v0.1.0
211
+ [0.0.1]: https://github.com/powertime-org/pgdeclare/releases/tag/v0.0.1
@@ -0,0 +1,150 @@
1
+ Metadata-Version: 2.5
2
+ Name: pgdeclare
3
+ Version: 0.1.2
4
+ Summary: Declarative Postgres schemas: diff the live database against your SQL files, with before/after migration blocks and a hash ledger.
5
+ Project-URL: Homepage, https://github.com/powertime-org/pgdeclare
6
+ Project-URL: Source, https://github.com/powertime-org/pgdeclare
7
+ Project-URL: Issues, https://github.com/powertime-org/pgdeclare/issues
8
+ Project-URL: Changelog, https://github.com/powertime-org/pgdeclare/blob/main/CHANGELOG.md
9
+ Author: Peter Brodsky
10
+ Maintainer-email: Powertime <info@powertime.org>
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ License-File: NOTICE
14
+ Keywords: database,ddl,declarative,diff,migrations,postgres,postgresql,schema
15
+ Classifier: Development Status :: 3 - Alpha
16
+ Classifier: Environment :: Console
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: License :: OSI Approved :: Apache Software License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3 :: Only
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Programming Language :: SQL
26
+ Classifier: Topic :: Database
27
+ Classifier: Topic :: Software Development :: Build Tools
28
+ Classifier: Typing :: Typed
29
+ Requires-Python: >=3.12
30
+ Requires-Dist: pglast>=8.5
31
+ Requires-Dist: psycopg2-binary>=2.9.13
32
+ Description-Content-Type: text/markdown
33
+
34
+ # pgdeclare
35
+
36
+ pgdeclare is a Postgres schema differ.
37
+
38
+ Why we built it: [Your Database Schema Should Be Code You Can Read](https://blog.powertime.org/pgdeclare).
39
+
40
+ ## Overview
41
+
42
+ **Your database schema should be code you can read.**
43
+
44
+ With migration files, reviewers read deltas, not the schema, and an LLM reading the repository has to reconstruct the state too, getting it wrong in the same places people do. pgdeclare keeps the schema as declarations: one `CREATE TABLE` per table, in plain SQL files, always describing the database as it is now. You change a table by editing its definition. pgdeclare builds the declared schema in a scratch database, diffs it against the live one through `pg_catalog`, and applies the difference.
45
+
46
+ A diff cannot infer everything, such as a rename or a backfill. For those you write small imperative `@migrate-before` / `@migrate-after` blocks next to the DDL they belong to. Each runs once per database and is recorded in a hash ledger, so an edit after it ran is refused rather than silently ignored. Destructive changes on tables that hold data need an explicit `@drop` directive. Migrations that have run can be pruned so they don't pile up. History still exists, in git, where history belongs.
47
+
48
+ ![The schema files are built into a scratch plan database and introspected. Pending @migrate-before blocks run on the live database, which is then introspected. The two are diffed, the difference is applied, @migrate-after and DO blocks run, and a second diff must come back empty.](https://raw.githubusercontent.com/powertime-org/pgdeclare/main/docs/images/pipeline.svg)
49
+
50
+ Status: **0.1.2.** The engine has run the production schema of [Powertime](https://powertime.org) since it went into service on 10 December 2025. Backwards compatibility may not be preserved until 1.0.
51
+
52
+ ## Design choices
53
+
54
+ - **Postgres parses your SQL.** The desired schema is not reconstructed from a parser's model of your files. pgdeclare executes them in a scratch "plan" database and introspects the result, so defaults, implicit constraints and type normalisation come out exactly as Postgres would produce them.
55
+ - **Postgres orders the work.** Statements, and the changes themselves, run retry-until-stable: anything that fails on a missing dependency is retried after the rest, until everything succeeds or no progress is made. You do not maintain a dependency order.
56
+
57
+ ## Install
58
+
59
+ ```bash
60
+ pip install pgdeclare
61
+ # or, inside a uv project
62
+ uv add pgdeclare
63
+ ```
64
+
65
+ Requires Python 3.12+ and a PostgreSQL 14 to 18 server.
66
+
67
+ Connect as a role that owns the target database's schemas. Each run builds your schema in a scratch plan database on the same server, which by default is created and dropped per run, so the role needs `CREATEDB`. Without it, create a plan database you own (`createdb -O app app_plan`) and pass `--plan-database app_plan`.
68
+
69
+ ## Quickstart
70
+
71
+ A schema tree:
72
+
73
+ ```text
74
+ sql/
75
+ └── schemas/
76
+ ├── 01_types.sql
77
+ └── 02_note.sql
78
+ ```
79
+
80
+ ```sql
81
+ -- sql/schemas/01_types.sql
82
+ CREATE TYPE mood AS ENUM ('calm', 'loud');
83
+ ```
84
+
85
+ ```sql
86
+ -- sql/schemas/02_note.sql
87
+ CREATE TABLE IF NOT EXISTS note (
88
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
89
+ author text NOT NULL,
90
+ body text NOT NULL,
91
+ mood mood NOT NULL DEFAULT 'calm'
92
+ );
93
+
94
+ CREATE INDEX IF NOT EXISTS note_author_idx ON note (author);
95
+ ```
96
+
97
+ ### Command line
98
+
99
+ ```bash
100
+ export DATABASE_URL=postgresql://app:secret@localhost:5432/app
101
+
102
+ pgdeclare diff # what would change, as a summary plus SQL
103
+ pgdeclare diff --json # the same, machine-readable
104
+ pgdeclare diff --exit-code # exit 2 when anything is pending (for CI)
105
+ pgdeclare apply --dry-run # plan only, nothing written
106
+ pgdeclare apply --dry-run --prove # rehearse the real run on a throwaway clone
107
+ pgdeclare apply # converge the database
108
+ ```
109
+
110
+ Now add a column and a backfill:
111
+
112
+ ```sql
113
+ -- sql/schemas/02_note.sql
114
+ CREATE TABLE IF NOT EXISTS note (
115
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
116
+ author text NOT NULL,
117
+ body text NOT NULL,
118
+ mood mood NOT NULL DEFAULT 'calm',
119
+ title text
120
+ );
121
+
122
+ CREATE INDEX IF NOT EXISTS note_author_idx ON note (author);
123
+
124
+ -- @migrate-after:2026-01-15_note_titles
125
+ UPDATE note SET title = left(body, 40) WHERE title IS NULL;
126
+ -- @end-migrate
127
+ ```
128
+
129
+ `pgdeclare apply` adds the column, then runs the block once and records it.
130
+
131
+ Every command, flag and exit code is in [docs/cli.md](https://github.com/powertime-org/pgdeclare/blob/main/docs/cli.md); the library API is in [docs/python.md](https://github.com/powertime-org/pgdeclare/blob/main/docs/python.md).
132
+
133
+ ## Documentation
134
+
135
+ - [Command line](https://github.com/powertime-org/pgdeclare/blob/main/docs/cli.md): flags, exit codes, `--prove`.
136
+ - [Python API](https://github.com/powertime-org/pgdeclare/blob/main/docs/python.md): the library entry points and their errors.
137
+ - [Schema files](https://github.com/powertime-org/pgdeclare/blob/main/docs/schema-files.md): directory layout, `@migrate-before` / `@migrate-after`, `@drop`, `DO` blocks.
138
+ - [Coverage](https://github.com/powertime-org/pgdeclare/blob/main/docs/coverage.md): every object kind pgdeclare manages, how, and what it leaves alone.
139
+ - [Configuration](https://github.com/powertime-org/pgdeclare/blob/main/docs/configuration.md): every `PgDeclareConfig` field.
140
+ - [Safety](https://github.com/powertime-org/pgdeclare/blob/main/docs/safety.md): previews, `--prove`, online/offline/blocked changes, quoting, masking, and the supported PostgreSQL versions (14 to 18).
141
+
142
+ ## Contributing
143
+
144
+ Issues and pull requests are welcome on [GitHub](https://github.com/powertime-org/pgdeclare). See [CONTRIBUTING.md](https://github.com/powertime-org/pgdeclare/blob/main/CONTRIBUTING.md) for running the tests, and [SECURITY.md](https://github.com/powertime-org/pgdeclare/blob/main/SECURITY.md) for reporting vulnerabilities.
145
+
146
+ ## License
147
+
148
+ Apache License 2.0. See [LICENSE](https://github.com/powertime-org/pgdeclare/blob/main/LICENSE) and [NOTICE](https://github.com/powertime-org/pgdeclare/blob/main/NOTICE).
149
+
150
+ Extracted from [Powertime](https://powertime.org), where it manages the application's schema.
@@ -0,0 +1,117 @@
1
+ # pgdeclare
2
+
3
+ pgdeclare is a Postgres schema differ.
4
+
5
+ Why we built it: [Your Database Schema Should Be Code You Can Read](https://blog.powertime.org/pgdeclare).
6
+
7
+ ## Overview
8
+
9
+ **Your database schema should be code you can read.**
10
+
11
+ With migration files, reviewers read deltas, not the schema, and an LLM reading the repository has to reconstruct the state too, getting it wrong in the same places people do. pgdeclare keeps the schema as declarations: one `CREATE TABLE` per table, in plain SQL files, always describing the database as it is now. You change a table by editing its definition. pgdeclare builds the declared schema in a scratch database, diffs it against the live one through `pg_catalog`, and applies the difference.
12
+
13
+ A diff cannot infer everything, such as a rename or a backfill. For those you write small imperative `@migrate-before` / `@migrate-after` blocks next to the DDL they belong to. Each runs once per database and is recorded in a hash ledger, so an edit after it ran is refused rather than silently ignored. Destructive changes on tables that hold data need an explicit `@drop` directive. Migrations that have run can be pruned so they don't pile up. History still exists, in git, where history belongs.
14
+
15
+ ![The schema files are built into a scratch plan database and introspected. Pending @migrate-before blocks run on the live database, which is then introspected. The two are diffed, the difference is applied, @migrate-after and DO blocks run, and a second diff must come back empty.](https://raw.githubusercontent.com/powertime-org/pgdeclare/main/docs/images/pipeline.svg)
16
+
17
+ Status: **0.1.2.** The engine has run the production schema of [Powertime](https://powertime.org) since it went into service on 10 December 2025. Backwards compatibility may not be preserved until 1.0.
18
+
19
+ ## Design choices
20
+
21
+ - **Postgres parses your SQL.** The desired schema is not reconstructed from a parser's model of your files. pgdeclare executes them in a scratch "plan" database and introspects the result, so defaults, implicit constraints and type normalisation come out exactly as Postgres would produce them.
22
+ - **Postgres orders the work.** Statements, and the changes themselves, run retry-until-stable: anything that fails on a missing dependency is retried after the rest, until everything succeeds or no progress is made. You do not maintain a dependency order.
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ pip install pgdeclare
28
+ # or, inside a uv project
29
+ uv add pgdeclare
30
+ ```
31
+
32
+ Requires Python 3.12+ and a PostgreSQL 14 to 18 server.
33
+
34
+ Connect as a role that owns the target database's schemas. Each run builds your schema in a scratch plan database on the same server, which by default is created and dropped per run, so the role needs `CREATEDB`. Without it, create a plan database you own (`createdb -O app app_plan`) and pass `--plan-database app_plan`.
35
+
36
+ ## Quickstart
37
+
38
+ A schema tree:
39
+
40
+ ```text
41
+ sql/
42
+ └── schemas/
43
+ ├── 01_types.sql
44
+ └── 02_note.sql
45
+ ```
46
+
47
+ ```sql
48
+ -- sql/schemas/01_types.sql
49
+ CREATE TYPE mood AS ENUM ('calm', 'loud');
50
+ ```
51
+
52
+ ```sql
53
+ -- sql/schemas/02_note.sql
54
+ CREATE TABLE IF NOT EXISTS note (
55
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
56
+ author text NOT NULL,
57
+ body text NOT NULL,
58
+ mood mood NOT NULL DEFAULT 'calm'
59
+ );
60
+
61
+ CREATE INDEX IF NOT EXISTS note_author_idx ON note (author);
62
+ ```
63
+
64
+ ### Command line
65
+
66
+ ```bash
67
+ export DATABASE_URL=postgresql://app:secret@localhost:5432/app
68
+
69
+ pgdeclare diff # what would change, as a summary plus SQL
70
+ pgdeclare diff --json # the same, machine-readable
71
+ pgdeclare diff --exit-code # exit 2 when anything is pending (for CI)
72
+ pgdeclare apply --dry-run # plan only, nothing written
73
+ pgdeclare apply --dry-run --prove # rehearse the real run on a throwaway clone
74
+ pgdeclare apply # converge the database
75
+ ```
76
+
77
+ Now add a column and a backfill:
78
+
79
+ ```sql
80
+ -- sql/schemas/02_note.sql
81
+ CREATE TABLE IF NOT EXISTS note (
82
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
83
+ author text NOT NULL,
84
+ body text NOT NULL,
85
+ mood mood NOT NULL DEFAULT 'calm',
86
+ title text
87
+ );
88
+
89
+ CREATE INDEX IF NOT EXISTS note_author_idx ON note (author);
90
+
91
+ -- @migrate-after:2026-01-15_note_titles
92
+ UPDATE note SET title = left(body, 40) WHERE title IS NULL;
93
+ -- @end-migrate
94
+ ```
95
+
96
+ `pgdeclare apply` adds the column, then runs the block once and records it.
97
+
98
+ Every command, flag and exit code is in [docs/cli.md](https://github.com/powertime-org/pgdeclare/blob/main/docs/cli.md); the library API is in [docs/python.md](https://github.com/powertime-org/pgdeclare/blob/main/docs/python.md).
99
+
100
+ ## Documentation
101
+
102
+ - [Command line](https://github.com/powertime-org/pgdeclare/blob/main/docs/cli.md): flags, exit codes, `--prove`.
103
+ - [Python API](https://github.com/powertime-org/pgdeclare/blob/main/docs/python.md): the library entry points and their errors.
104
+ - [Schema files](https://github.com/powertime-org/pgdeclare/blob/main/docs/schema-files.md): directory layout, `@migrate-before` / `@migrate-after`, `@drop`, `DO` blocks.
105
+ - [Coverage](https://github.com/powertime-org/pgdeclare/blob/main/docs/coverage.md): every object kind pgdeclare manages, how, and what it leaves alone.
106
+ - [Configuration](https://github.com/powertime-org/pgdeclare/blob/main/docs/configuration.md): every `PgDeclareConfig` field.
107
+ - [Safety](https://github.com/powertime-org/pgdeclare/blob/main/docs/safety.md): previews, `--prove`, online/offline/blocked changes, quoting, masking, and the supported PostgreSQL versions (14 to 18).
108
+
109
+ ## Contributing
110
+
111
+ Issues and pull requests are welcome on [GitHub](https://github.com/powertime-org/pgdeclare). See [CONTRIBUTING.md](https://github.com/powertime-org/pgdeclare/blob/main/CONTRIBUTING.md) for running the tests, and [SECURITY.md](https://github.com/powertime-org/pgdeclare/blob/main/SECURITY.md) for reporting vulnerabilities.
112
+
113
+ ## License
114
+
115
+ Apache License 2.0. See [LICENSE](https://github.com/powertime-org/pgdeclare/blob/main/LICENSE) and [NOTICE](https://github.com/powertime-org/pgdeclare/blob/main/NOTICE).
116
+
117
+ Extracted from [Powertime](https://powertime.org), where it manages the application's schema.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pgdeclare"
7
- version = "0.1.0"
7
+ version = "0.1.2"
8
8
  description = "Declarative Postgres schemas: diff the live database against your SQL files, with before/after migration blocks and a hash ledger."
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -17,22 +17,33 @@ file layout, bootstrap SQL, locking, failure classification) comes in through
17
17
  embeds it.
18
18
  """
19
19
 
20
- __version__ = "0.1.0"
20
+ __version__ = "0.1.2"
21
21
 
22
22
  from .config import DEFAULT_CONFIG, PgDeclareConfig
23
23
  from .models import (
24
24
  ChangeCategory,
25
+ Collation,
25
26
  Column,
27
+ Comment,
26
28
  Constraint,
29
+ DefaultPrivilege,
27
30
  Dependency,
31
+ Domain,
28
32
  EnumType,
33
+ EventTrigger,
29
34
  Function,
30
35
  Grant,
31
36
  Index,
37
+ MaterializedView,
32
38
  Policy,
39
+ RangeType,
40
+ Publication,
41
+ PublicationTable,
33
42
  Role,
34
43
  RoleMembership,
44
+ Rule,
35
45
  Schema,
46
+ Sequence,
36
47
  Table,
37
48
  Trigger,
38
49
  View,
@@ -45,7 +56,9 @@ from .introspection import (
45
56
  from .differ import (
46
57
  compute_diff,
47
58
  categorize_changes,
59
+ partition_notes,
48
60
  split_index_operations,
61
+ undeclared_partitions,
49
62
  )
50
63
  from .executor import (
51
64
  execute_migration,
@@ -88,6 +101,14 @@ from .migrate import (
88
101
  compute_residual_changes,
89
102
  report_pending_migration_blocks,
90
103
  )
104
+ from .prove import (
105
+ LedgerEntry,
106
+ ProveError,
107
+ ProveFailedError,
108
+ ProveResult,
109
+ TableRows,
110
+ prove_declared_schema,
111
+ )
91
112
 
92
113
  __all__ = [
93
114
  "__version__",
@@ -96,17 +117,28 @@ __all__ = [
96
117
  "PgDeclareConfig",
97
118
  # Models
98
119
  "ChangeCategory",
120
+ "Collation",
99
121
  "Column",
122
+ "Comment",
100
123
  "Constraint",
124
+ "DefaultPrivilege",
101
125
  "Dependency",
126
+ "Domain",
102
127
  "EnumType",
128
+ "EventTrigger",
103
129
  "Function",
104
130
  "Grant",
105
131
  "Index",
132
+ "MaterializedView",
106
133
  "Policy",
134
+ "RangeType",
135
+ "Publication",
136
+ "PublicationTable",
107
137
  "Role",
108
138
  "RoleMembership",
139
+ "Rule",
109
140
  "Schema",
141
+ "Sequence",
110
142
  "Table",
111
143
  "Trigger",
112
144
  "View",
@@ -117,7 +149,9 @@ __all__ = [
117
149
  # Differ
118
150
  "compute_diff",
119
151
  "categorize_changes",
152
+ "partition_notes",
120
153
  "split_index_operations",
154
+ "undeclared_partitions",
121
155
  # Executor
122
156
  "execute_migration",
123
157
  "cleanup_invalid_indexes",
@@ -154,4 +188,11 @@ __all__ = [
154
188
  "assert_schema_converged",
155
189
  "compute_residual_changes",
156
190
  "report_pending_migration_blocks",
191
+ # Prove: rehearse a run on a throwaway clone
192
+ "LedgerEntry",
193
+ "ProveError",
194
+ "ProveFailedError",
195
+ "ProveResult",
196
+ "TableRows",
197
+ "prove_declared_schema",
157
198
  ]