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.
- pgdeclare-0.1.2/CHANGELOG.md +211 -0
- pgdeclare-0.1.2/PKG-INFO +150 -0
- pgdeclare-0.1.2/README.md +117 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/pyproject.toml +1 -1
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/__init__.py +42 -1
- pgdeclare-0.1.2/src/pgdeclare/changes.py +3818 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/cli.py +112 -11
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/config.py +9 -0
- pgdeclare-0.1.2/src/pgdeclare/differ.py +2604 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/executor.py +118 -13
- pgdeclare-0.1.2/src/pgdeclare/introspection.py +2380 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/migrate.py +132 -10
- pgdeclare-0.1.2/src/pgdeclare/models.py +1379 -0
- pgdeclare-0.1.2/src/pgdeclare/prove.py +413 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/retry_executor.py +3 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/schema_parser.py +286 -3
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/statement_parser.py +228 -11
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_boundary.py +1 -1
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_cli.py +224 -0
- pgdeclare-0.1.2/tests/test_comments.py +428 -0
- pgdeclare-0.1.2/tests/test_default_privileges.py +436 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_diff.py +29 -2
- pgdeclare-0.1.2/tests/test_domains.py +493 -0
- pgdeclare-0.1.2/tests/test_foreign_data.py +945 -0
- pgdeclare-0.1.2/tests/test_materialized_views.py +569 -0
- pgdeclare-0.1.2/tests/test_partitions.py +745 -0
- pgdeclare-0.1.2/tests/test_prove.py +410 -0
- pgdeclare-0.1.2/tests/test_publications_rules.py +895 -0
- pgdeclare-0.1.2/tests/test_ranges_collations.py +729 -0
- pgdeclare-0.1.2/tests/test_routines.py +541 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_security.py +13 -1
- pgdeclare-0.1.2/tests/test_sequences.py +486 -0
- pgdeclare-0.1.2/tests/test_views.py +244 -0
- pgdeclare-0.1.0/CHANGELOG.md +0 -68
- pgdeclare-0.1.0/PKG-INFO +0 -403
- pgdeclare-0.1.0/README.md +0 -370
- pgdeclare-0.1.0/src/pgdeclare/changes.py +0 -1528
- pgdeclare-0.1.0/src/pgdeclare/differ.py +0 -999
- pgdeclare-0.1.0/src/pgdeclare/introspection.py +0 -979
- pgdeclare-0.1.0/src/pgdeclare/models.py +0 -603
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/.gitignore +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/LICENSE +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/NOTICE +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/__main__.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/drop_directive.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/ledger.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/py.typed +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/src/pgdeclare/quoting.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/conftest.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/dbutil.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_integration.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_lifecycle.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_pipeline.py +0 -0
- {pgdeclare-0.1.0 → pgdeclare-0.1.2}/tests/test_retry_executor.py +0 -0
- {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
|
pgdeclare-0.1.2/PKG-INFO
ADDED
|
@@ -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
|
+

|
|
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
|
+

|
|
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.
|
|
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.
|
|
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
|
]
|