pgdeclare 0.2.0__tar.gz → 0.2.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 (50) hide show
  1. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/CHANGELOG.md +20 -0
  2. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/PKG-INFO +2 -2
  3. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/README.md +1 -1
  4. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/pyproject.toml +1 -1
  5. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/__init__.py +1 -1
  6. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/differ.py +62 -14
  7. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_boundary.py +1 -1
  8. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_expand_contract.py +88 -14
  9. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_routines.py +5 -3
  10. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/.gitignore +0 -0
  11. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/LICENSE +0 -0
  12. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/NOTICE +0 -0
  13. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/__main__.py +0 -0
  14. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/changes.py +0 -0
  15. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/cli.py +0 -0
  16. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/config.py +0 -0
  17. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/contract.py +0 -0
  18. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/drop_directive.py +0 -0
  19. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/executor.py +0 -0
  20. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/introspection.py +0 -0
  21. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/ledger.py +0 -0
  22. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/migrate.py +0 -0
  23. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/models.py +0 -0
  24. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/prove.py +0 -0
  25. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/py.typed +0 -0
  26. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/quoting.py +0 -0
  27. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/retry_executor.py +0 -0
  28. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/schema_parser.py +0 -0
  29. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/src/pgdeclare/statement_parser.py +0 -0
  30. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/conftest.py +0 -0
  31. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/dbutil.py +0 -0
  32. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_cli.py +0 -0
  33. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_comments.py +0 -0
  34. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_default_privileges.py +0 -0
  35. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_diff.py +0 -0
  36. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_domains.py +0 -0
  37. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_foreign_data.py +0 -0
  38. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_integration.py +0 -0
  39. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_lifecycle.py +0 -0
  40. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_materialized_views.py +0 -0
  41. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_partitions.py +0 -0
  42. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_pipeline.py +0 -0
  43. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_prove.py +0 -0
  44. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_publications_rules.py +0 -0
  45. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_ranges_collations.py +0 -0
  46. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_retry_executor.py +0 -0
  47. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_security.py +0 -0
  48. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_sequences.py +0 -0
  49. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_statement_parser.py +0 -0
  50. {pgdeclare-0.2.0 → pgdeclare-0.2.2}/tests/test_views.py +0 -0
@@ -5,6 +5,26 @@ All notable changes to this project are documented here. The format follows
5
5
  [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0 the API
6
6
  may change in minor releases.
7
7
 
8
+ ## [0.2.2] - 2026-11-19
9
+
10
+ ### Changed
11
+
12
+ - A signature change that only appends parameters with defaults is online
13
+ again. The old and new forms still cannot coexist, but the drop and
14
+ re-create is one statement, and every call of the old form, by position or
15
+ by name, resolves to the new one. Any other change whose forms compete for
16
+ a call (new types at the same count, an old default taken away, a new
17
+ return type or renamed parameters) stays offline.
18
+
19
+ ## [0.2.1] - 2026-11-19
20
+
21
+ ### Changed
22
+
23
+ - A change of a routine's parameter names alone is now offline. The drop and
24
+ re-create is still one statement, but a call that names the old
25
+ parameters (`f(p_old => 1)`) fails from then on, so an application still
26
+ using them must be stopped.
27
+
8
28
  ## [0.2.0] - 2026-11-19
9
29
 
10
30
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pgdeclare
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: Declarative Postgres schemas: diff the live database against your SQL files, with before/after migration blocks and a hash ledger.
5
5
  Project-URL: Homepage, https://github.com/powertime-org/pgdeclare
6
6
  Project-URL: Source, https://github.com/powertime-org/pgdeclare
@@ -47,7 +47,7 @@ A diff cannot infer everything, such as a rename or a backfill. For those you wr
47
47
 
48
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
49
 
50
- Status: **0.2.0.** 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.
50
+ Status: **0.2.1.** 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
51
 
52
52
  ## Design choices
53
53
 
@@ -14,7 +14,7 @@ A diff cannot infer everything, such as a rename or a backfill. For those you wr
14
14
 
15
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
16
 
17
- Status: **0.2.0.** 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.
17
+ Status: **0.2.1.** 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
18
 
19
19
  ## Design choices
20
20
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pgdeclare"
7
- version = "0.2.0"
7
+ version = "0.2.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,7 +17,7 @@ file layout, bootstrap SQL, locking, failure classification) comes in through
17
17
  embeds it.
18
18
  """
19
19
 
20
- __version__ = "0.2.0"
20
+ __version__ = "0.2.2"
21
21
 
22
22
  from .config import DEFAULT_CONFIG, PgDeclareConfig
23
23
  from .models import (
@@ -1308,6 +1308,32 @@ def _same_call_types(a: Function, b: Function) -> bool:
1308
1308
  return a.call_shape_known and b.call_shape_known and a.arg_types == b.arg_types
1309
1309
 
1310
1310
 
1311
+ def _appends_defaulted_parameters(new: Function, old: Function) -> bool:
1312
+ """Whether `new` is `old` with trailing parameters that all have defaults.
1313
+
1314
+ Every call the old form accepts, by position or by name, then resolves to
1315
+ the new one: the old parameters keep their names, types and order, the
1316
+ added ones fill in from their defaults, and no call loses a default it
1317
+ relied on (the new form needs no more arguments than the old). With the
1318
+ same kind and return clause, re-creating it in one statement is invisible
1319
+ to an application still calling the old form.
1320
+ """
1321
+ if not (new.call_shape_known and old.call_shape_known):
1322
+ return False
1323
+ if new.max_call_args is None or old.max_call_args is None:
1324
+ return False # VARIADIC: leave it to the overlap rule
1325
+ assert new.min_call_args is not None and old.min_call_args is not None
1326
+ if new.kind != old.kind or new.kind != "f":
1327
+ return False
1328
+ if new.get_return_clause() != old.get_return_clause():
1329
+ return False
1330
+ if old.args and not new.args.startswith(old.args + ", "):
1331
+ return False
1332
+ return (
1333
+ new.max_call_args > old.max_call_args and new.min_call_args <= old.min_call_args
1334
+ )
1335
+
1336
+
1311
1337
  def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1312
1338
  """Diff functions between desired and actual schemas."""
1313
1339
  changes: list[Change] = []
@@ -1350,28 +1376,50 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1350
1376
  # The old signature has to go in the same statement, with the
1351
1377
  # OLD args so the DROP names what is there. When only the
1352
1378
  # parameter names changed the identity is the same, so the
1353
- # two cannot coexist, and a call by position still resolves.
1379
+ # two cannot coexist, and a call that names the old
1380
+ # parameters (`p_old => ...`) fails from the DROP on.
1354
1381
  # Otherwise the overloads would compete for some call (a new
1355
1382
  # DEFAULT that lets a call of the old length match both is
1356
- # the usual case: "function ... is not unique"), and an
1357
- # application still calling the old signature fails from the
1358
- # DROP on: that can only run with the application stopped.
1383
+ # the usual case: "function ... is not unique"), and a call
1384
+ # to the old signature fails from the DROP on. Either way an
1385
+ # application still calling the old form breaks: offline.
1359
1386
  functions_to_drop_for_rename.add(rename_source.signature)
1360
- same_identity = _same_call_types(func, rename_source)
1387
+ if _appends_defaulted_parameters(func, rename_source):
1388
+ # Old and new would compete side by side, but swapped in
1389
+ # one statement there is no moment with both or neither,
1390
+ # and every old call resolves to the new form: online.
1391
+ change = DropAndCreateFunction(
1392
+ function=func,
1393
+ old_args=rename_source.args,
1394
+ old_kind=rename_source.kind,
1395
+ )
1396
+ change.description = (
1397
+ f"Drop {rename_source.keyword.lower()} "
1398
+ f"{rename_source.signature} and create "
1399
+ f"{func.signature} (online: it only appends "
1400
+ f"parameters with defaults, so every old call "
1401
+ f"resolves to it)"
1402
+ )
1403
+ changes.append(change)
1404
+ continue
1361
1405
  change = DropAndCreateFunction(
1362
1406
  function=func,
1363
1407
  old_args=rename_source.args, # Pass old args for correct DROP
1364
1408
  old_kind=rename_source.kind,
1409
+ category=ChangeCategory.OFFLINE,
1410
+ )
1411
+ why = (
1412
+ "a call naming the old parameters fails once it is dropped"
1413
+ if _same_call_types(func, rename_source)
1414
+ else "a call to the old signature fails once it is "
1415
+ "dropped, and the two cannot coexist because a call "
1416
+ "could match both"
1417
+ )
1418
+ change.description = (
1419
+ f"Drop {rename_source.keyword.lower()} "
1420
+ f"{rename_source.signature} and create "
1421
+ f"{func.signature} (offline: {why})"
1365
1422
  )
1366
- if not same_identity:
1367
- change.category = ChangeCategory.OFFLINE
1368
- change.description = (
1369
- f"Drop {rename_source.keyword.lower()} "
1370
- f"{rename_source.signature} and create "
1371
- f"{func.signature} (offline: a call to the old "
1372
- f"signature fails once it is dropped, and the two "
1373
- f"cannot coexist because a call could match both)"
1374
- )
1375
1423
  changes.append(change)
1376
1424
  elif func.definition_hash != actual.functions[key].definition_hash:
1377
1425
  # A changed return type or kind requires DROP + CREATE: CREATE OR
@@ -114,4 +114,4 @@ def test_the_default_config_is_neutral():
114
114
  def test_the_public_api_is_exported():
115
115
  for name in pgdeclare.__all__:
116
116
  assert hasattr(pgdeclare, name), name
117
- assert pgdeclare.__version__ == "0.2.0"
117
+ assert pgdeclare.__version__ == "0.2.2"
@@ -63,18 +63,64 @@ def _schema(*functions: Function, **kw) -> Schema:
63
63
 
64
64
 
65
65
  class TestSignatureChanges:
66
- def test_a_new_default_parameter_is_offline(self):
67
- # The 2026-11-19 incident: a third parameter with a DEFAULT. A call
68
- # with two arguments matches both overloads, so they cannot coexist,
69
- # and the old one cannot be dropped while anything calls it.
66
+ def test_appended_default_parameters_are_one_online_statement(self):
67
+ # A third parameter with a DEFAULT: the two forms cannot coexist (a
68
+ # call with two arguments matches both), but swapped in one statement
69
+ # every call of the old form resolves to the new one.
70
70
  old = _fn("account", "a uuid, s uuid", "uuid, uuid", 2, 2)
71
71
  new = _fn("account", "a uuid, s uuid, ip text", "uuid, uuid, text", 2, 3)
72
72
  changes = compute_diff(_schema(new), _schema(old))
73
73
  assert [type(c) for c in changes] == [DropAndCreateFunction]
74
- assert changes[0].category == ChangeCategory.OFFLINE
75
- assert "offline" in changes[0].description
74
+ assert changes[0].category == ChangeCategory.ONLINE
75
+ swap = changes[0]
76
+ assert isinstance(swap, DropAndCreateFunction)
77
+ assert swap.old_args == "a uuid, s uuid"
78
+ assert "online" in changes[0].description
76
79
  assert not is_held_back(changes[0])
77
80
 
81
+ def test_appended_defaults_keep_earlier_defaults_optional(self):
82
+ old = _fn("f", "a int, b int", "integer, integer", 1, 2)
83
+ new = _fn("f", "a int, b int, c int", "integer, integer, integer", 1, 3)
84
+ changes = compute_diff(_schema(new), _schema(old))
85
+ assert changes[0].category == ChangeCategory.ONLINE
86
+
87
+ @pytest.mark.parametrize(
88
+ "old,new",
89
+ [
90
+ # An old default dropped: a one-argument call no longer resolves.
91
+ (
92
+ _fn("f", "a int, b int", "integer, integer", 1, 2),
93
+ _fn("f", "a int, b int, c int", "integer, integer, integer", 2, 3),
94
+ ),
95
+ # An old parameter renamed: a call naming it fails.
96
+ (
97
+ _fn("f", "a int", "integer", 1, 1),
98
+ _fn("f", "x int, b int", "integer, integer", 1, 2),
99
+ ),
100
+ # Same count, new types: competes, and resolves to neither.
101
+ (
102
+ _fn("f", "a int", "integer", 1, 1),
103
+ _fn("f", "a text, b int", "text, integer", 1, 2),
104
+ ),
105
+ # A new return type: the old caller reads a different answer.
106
+ (
107
+ _fn("f", "a int", "integer", 1, 1, body="RETURNS int AS '1'"),
108
+ _fn(
109
+ "f",
110
+ "a int, b int",
111
+ "integer, integer",
112
+ 1,
113
+ 2,
114
+ body="RETURNS text AS '1'",
115
+ ),
116
+ ),
117
+ ],
118
+ )
119
+ def test_other_competing_signatures_stay_offline(self, old, new):
120
+ changes = compute_diff(_schema(new), _schema(old))
121
+ assert [type(c) for c in changes] == [DropAndCreateFunction]
122
+ assert changes[0].category == ChangeCategory.OFFLINE
123
+
78
124
  def test_a_signature_no_old_call_reaches_is_created_beside_the_old(self):
79
125
  old = _fn("total", "a int", "integer", 1, 1)
80
126
  new = _fn("total", "a int, b int", "integer, integer", 2, 2)
@@ -92,12 +138,14 @@ class TestSignatureChanges:
92
138
  assert [type(c) for c in changes] == [DropAndCreateFunction]
93
139
  assert changes[0].category == ChangeCategory.OFFLINE
94
140
 
95
- def test_renamed_parameters_stay_one_online_statement(self):
141
+ def test_renamed_parameters_are_one_offline_statement(self):
142
+ # A call in named notation (`total(a => 1)`) fails once `a` is gone.
96
143
  old = _fn("total", "a int", "integer", 1, 1)
97
144
  new = _fn("total", "amount int", "integer", 1, 1)
98
145
  changes = compute_diff(_schema(new), _schema(old))
99
146
  assert [type(c) for c in changes] == [DropAndCreateFunction]
100
- assert changes[0].category == ChangeCategory.ONLINE
147
+ assert changes[0].category == ChangeCategory.OFFLINE
148
+ assert "naming the old parameters" in changes[0].description
101
149
  assert not changes[0].contract
102
150
 
103
151
  def test_an_unknown_call_shape_counts_as_overlapping(self):
@@ -200,7 +248,7 @@ OLD_CALLS = "SELECT account(gen_random_uuid(), gen_random_uuid()), total(1), gon
200
248
 
201
249
 
202
250
  class TestDeployWhileTheOldVersionServes:
203
- def test_a_new_default_parameter_is_refused_online(self, tmp_path, databases):
251
+ def test_renamed_parameters_are_refused_online(self, tmp_path, databases):
204
252
  target, plan = databases
205
253
  sql_dir = tmp_path / "sql"
206
254
  _declare(sql_dir, V1)
@@ -209,20 +257,46 @@ class TestDeployWhileTheOldVersionServes:
209
257
  _declare(
210
258
  sql_dir,
211
259
  V1.replace(
212
- "account(a uuid, s uuid)",
213
- "account(a uuid, s uuid, ip text DEFAULT NULL)",
260
+ "total(a int) RETURNS int LANGUAGE sql AS 'SELECT a'",
261
+ "total(amount int) RETURNS int LANGUAGE sql AS 'SELECT amount'",
214
262
  ),
215
263
  )
216
- # Before the fix this dropped account(uuid, uuid) online, and every
217
- # call the serving version made failed "does not exist".
218
264
  with pytest.raises(Exception, match="Migration execution failed"):
219
265
  apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
220
- assert _run(target, OLD_CALLS) == [(1, 1, 3)]
266
+ # The serving version's named call still resolves.
267
+ assert _run(target, "SELECT total(a => 4)") == [(4,)]
221
268
 
222
269
  apply_declared_schema(target, sql_dir, plan, offline=True, config=QUIET)
270
+ assert _run(target, "SELECT total(amount => 4)") == [(4,)]
271
+
272
+ def test_a_new_default_parameter_swaps_online(self, tmp_path, databases):
273
+ target, plan = databases
274
+ sql_dir = tmp_path / "sql"
275
+ _declare(sql_dir, V1)
276
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
277
+
278
+ _declare(
279
+ sql_dir,
280
+ V1.replace(
281
+ "account(a uuid, s uuid)",
282
+ "account(a uuid, s uuid, ip text DEFAULT NULL)",
283
+ ),
284
+ )
285
+ # One statement drops account(uuid, uuid) and creates the new form,
286
+ # so no moment has neither (the 2026-11-19 incident, a hand DROP
287
+ # committed before the CREATE) or both ("is not unique").
288
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
289
+ # The serving version's calls, by position and by name, still resolve.
290
+ assert _run(target, OLD_CALLS) == [(1, 1, 3)]
291
+ assert _run(
292
+ target, "SELECT account(a => gen_random_uuid(), s => gen_random_uuid())"
293
+ ) == [(1,)]
223
294
  assert _run(
224
295
  target, "SELECT account(gen_random_uuid(), gen_random_uuid(), 'x')"
225
296
  ) == [(1,)]
297
+ apply_declared_schema(
298
+ target, sql_dir, plan, expect_converged=True, config=QUIET
299
+ )
226
300
 
227
301
  def test_expand_keeps_old_calls_working_and_contract_drops(
228
302
  self, tmp_path, databases
@@ -407,14 +407,16 @@ class TestRoutineRoundTrip:
407
407
  .replace("'SELECT a + b'", "'SELECT x + y'")
408
408
  )
409
409
  # The new procedure signature competes with the old one for a call
410
- # of two arguments, so the swap is offline.
410
+ # of two arguments, and `step`'s renamed parameters break a call
411
+ # naming the old ones, so both swaps are offline.
411
412
  offline = [
412
413
  c
413
414
  for c in _plan(sql_dir, recreated, target_url, plan_db)
414
415
  if c.category.value == "offline"
415
416
  ]
416
- assert [c.object_name for c in offline] == [
417
- "public.book(IN amount bigint, INOUT booked bigint)"
417
+ assert sorted(c.object_name for c in offline) == [
418
+ "public.book(IN amount bigint, INOUT booked bigint)",
419
+ "public.step(x integer, y integer)",
418
420
  ]
419
421
  _apply(sql_dir, recreated, target_url, plan_db, offline=True)
420
422
  routines = _routines(target_url)
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes