pgdeclare 0.1.2__tar.gz → 0.2.0__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.1.2 → pgdeclare-0.2.0}/CHANGELOG.md +35 -0
  2. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/PKG-INFO +2 -2
  3. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/README.md +1 -1
  4. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/pyproject.toml +1 -1
  5. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/__init__.py +8 -1
  6. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/changes.py +5 -0
  7. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/cli.py +9 -1
  8. pgdeclare-0.2.0/src/pgdeclare/contract.py +134 -0
  9. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/differ.py +104 -11
  10. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/introspection.py +20 -0
  11. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/migrate.py +59 -2
  12. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/models.py +29 -0
  13. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/prove.py +4 -0
  14. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_boundary.py +1 -1
  15. pgdeclare-0.2.0/tests/test_expand_contract.py +367 -0
  16. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_routines.py +20 -3
  17. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/.gitignore +0 -0
  18. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/LICENSE +0 -0
  19. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/NOTICE +0 -0
  20. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/__main__.py +0 -0
  21. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/config.py +0 -0
  22. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/drop_directive.py +0 -0
  23. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/executor.py +0 -0
  24. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/ledger.py +0 -0
  25. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/py.typed +0 -0
  26. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/quoting.py +0 -0
  27. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/retry_executor.py +0 -0
  28. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/schema_parser.py +0 -0
  29. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/src/pgdeclare/statement_parser.py +0 -0
  30. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/conftest.py +0 -0
  31. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/dbutil.py +0 -0
  32. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_cli.py +0 -0
  33. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_comments.py +0 -0
  34. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_default_privileges.py +0 -0
  35. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_diff.py +0 -0
  36. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_domains.py +0 -0
  37. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_foreign_data.py +0 -0
  38. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_integration.py +0 -0
  39. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_lifecycle.py +0 -0
  40. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_materialized_views.py +0 -0
  41. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_partitions.py +0 -0
  42. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_pipeline.py +0 -0
  43. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_prove.py +0 -0
  44. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_publications_rules.py +0 -0
  45. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_ranges_collations.py +0 -0
  46. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_retry_executor.py +0 -0
  47. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_security.py +0 -0
  48. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_sequences.py +0 -0
  49. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_statement_parser.py +0 -0
  50. {pgdeclare-0.1.2 → pgdeclare-0.2.0}/tests/test_views.py +0 -0
@@ -5,6 +5,41 @@ 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.0] - 2026-11-19
9
+
10
+ ### Added
11
+
12
+ - Expand/contract for routines. Dropping an undeclared function, procedure
13
+ or aggregate, and revoking a grant on it, is a *contract* change:
14
+ `apply --expand-only` (`expand_only=True`) holds contract changes back for
15
+ a later run without the flag, so a deploy can migrate while the previous
16
+ version of the application still calls them. The convergence check of an
17
+ expand run allows exactly those changes.
18
+ - An expand run refuses, before anything runs, a pending `@migrate-before`
19
+ or `@migrate-after` block that takes away what the serving version may use
20
+ (`ExpandRefusedError`): a `DROP` (but of an index, trigger or extended
21
+ statistics without `CASCADE`), a rename of anything a query names, `SET
22
+ SCHEMA`, or a column dropped, retyped or made `NOT NULL`. A block is SQL
23
+ run as written and cannot be postponed past the diff, so such a migration
24
+ runs offline. `breaking_statements(sql)` and `breaking_blocks(blocks,
25
+ applied)` give the same answer to a caller deciding how to deploy.
26
+ - `Function` carries its call shape (`arg_types`, `min_call_args`,
27
+ `max_call_args`), read from `pg_proc`.
28
+
29
+ ### Changed
30
+
31
+ - A routine whose signature changes is no longer always dropped and
32
+ re-created online. When no call can match both the old and the new
33
+ signature (the argument counts they accept do not overlap), the new one is
34
+ created beside the old and the old one is dropped as a contract change.
35
+ When a call could match both (a new parameter with a `DEFAULT`, or new
36
+ types at the same arity), the drop and re-create is now **offline**: an
37
+ application still calling the old signature fails from the drop on, and
38
+ the two overloads cannot coexist without making its calls ambiguous. A
39
+ change of parameter names only stays one online statement.
40
+ - A dropped routine whose definition names a view, materialized view, domain
41
+ or range type the same run drops is dropped in that run, offline.
42
+
8
43
  ## [0.1.2] - 2026-10-19
9
44
 
10
45
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pgdeclare
3
- Version: 0.1.2
3
+ Version: 0.2.0
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.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.
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.
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.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.
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.
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.1.2"
7
+ version = "0.2.0"
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.1.2"
20
+ __version__ = "0.2.0"
21
21
 
22
22
  from .config import DEFAULT_CONFIG, PgDeclareConfig
23
23
  from .models import (
@@ -94,7 +94,9 @@ from .ledger import (
94
94
  parse_migration_blocks_from_content,
95
95
  parse_migration_blocks_from_git,
96
96
  )
97
+ from .contract import BreakingBlock, breaking_blocks, breaking_statements
97
98
  from .migrate import (
99
+ ExpandRefusedError,
98
100
  SchemaConvergenceError,
99
101
  apply_declared_schema,
100
102
  assert_schema_converged,
@@ -183,11 +185,16 @@ __all__ = [
183
185
  "parse_migration_blocks_from_content",
184
186
  "parse_migration_blocks_from_git",
185
187
  # Pipeline
188
+ "ExpandRefusedError",
186
189
  "SchemaConvergenceError",
187
190
  "apply_declared_schema",
188
191
  "assert_schema_converged",
189
192
  "compute_residual_changes",
190
193
  "report_pending_migration_blocks",
194
+ # Expand/contract: inline migrations an expand run refuses
195
+ "BreakingBlock",
196
+ "breaking_blocks",
197
+ "breaking_statements",
191
198
  # Prove: rehearse a run on a throwaway clone
192
199
  "LedgerEntry",
193
200
  "ProveError",
@@ -87,6 +87,11 @@ class Change(ABC):
87
87
  requires_drop_directive: bool = False
88
88
  object_type: str = ""
89
89
  object_name: str = ""
90
+ # The contract half of an expand/contract deploy: a change the previous
91
+ # version of the application may still depend on while it serves (today:
92
+ # dropping a routine it may still call). A run with `expand_only` holds
93
+ # it back; the run after the old version has stopped applies it.
94
+ contract: bool = False
90
95
 
91
96
  @abstractmethod
92
97
  def to_sql(self) -> str:
@@ -1,7 +1,7 @@
1
1
  """The `pgdeclare` command line: a thin convenience over the library.
2
2
 
3
3
  pgdeclare diff [--json] [--exit-code] [--prove]
4
- pgdeclare apply [--dry-run [--prove]] [--offline] [--force]
4
+ pgdeclare apply [--dry-run [--prove]] [--offline] [--expand-only] [--force]
5
5
 
6
6
  Both build the declared schema in a scratch "plan" database on the same server
7
7
  (created on demand and dropped afterwards, unless `--plan-database` names one
@@ -359,6 +359,7 @@ def cmd_apply(args: argparse.Namespace) -> int:
359
359
  offline=args.offline,
360
360
  force=args.force,
361
361
  dry_run=args.dry_run,
362
+ expand_only=args.expand_only,
362
363
  prove=args.prove,
363
364
  prepare_clone=_clone_preparer(cfg),
364
365
  config=cfg,
@@ -460,6 +461,13 @@ def build_parser() -> argparse.ArgumentParser:
460
461
  action="store_true",
461
462
  help="bypass @drop checks, re-run edited blocks, ignore non-convergence",
462
463
  )
464
+ apply.add_argument(
465
+ "--expand-only",
466
+ action="store_true",
467
+ help="the expand half of an expand/contract deploy: keep the routines "
468
+ "the running application may still call (dropped, or replaced by a new "
469
+ "signature) for a later run without this flag",
470
+ )
463
471
  apply.add_argument(
464
472
  "--prove",
465
473
  action="store_true",
@@ -0,0 +1,134 @@
1
+ """Inline migrations that take away what a running application may still use.
2
+
3
+ A deploy that migrates while the previous version of the application still
4
+ serves can hold back the differ's contract changes (`expand_only`), but an
5
+ inline `@migrate-before` / `@migrate-after` block is SQL the engine runs as
6
+ written. A pending block that drops, renames or moves an object, or drops or
7
+ retypes a column, breaks that version's queries from the moment it runs, and
8
+ cannot be postponed past a diff that may depend on it. An expand run refuses
9
+ such a block, so the migration has to run with the application stopped.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from dataclasses import dataclass
16
+
17
+ from pglast import parse_sql
18
+ from pglast.enums import AlterTableType, DropBehavior, ObjectType
19
+
20
+ from .ledger import MigrationBlock
21
+
22
+ # Dropping these takes nothing a query names.
23
+ _HARMLESS_DROPS = frozenset(
24
+ {
25
+ ObjectType.OBJECT_INDEX,
26
+ ObjectType.OBJECT_TRIGGER,
27
+ ObjectType.OBJECT_STATISTIC_EXT,
28
+ }
29
+ )
30
+ # Renaming these changes nothing a query names.
31
+ _HARMLESS_RENAMES = frozenset(
32
+ {
33
+ ObjectType.OBJECT_INDEX,
34
+ ObjectType.OBJECT_TRIGGER,
35
+ ObjectType.OBJECT_TABCONSTRAINT,
36
+ ObjectType.OBJECT_DOMCONSTRAINT,
37
+ ObjectType.OBJECT_POLICY,
38
+ ObjectType.OBJECT_STATISTIC_EXT,
39
+ }
40
+ )
41
+ _BREAKING_TABLE_CMDS = frozenset(
42
+ {
43
+ AlterTableType.AT_DropColumn,
44
+ AlterTableType.AT_AlterColumnType,
45
+ AlterTableType.AT_SetNotNull,
46
+ }
47
+ )
48
+ # A DO block is PL/pgSQL the parser does not look into, so its text is read.
49
+ _DO_BREAKING = re.compile(
50
+ r"\bDROP\s+(?!INDEX\b|TRIGGER\b|DEFAULT\b|NOT\s+NULL\b|IDENTITY\b|EXPRESSION\b)\w+"
51
+ r"|\bRENAME\b|\bSET\s+SCHEMA\b|\bSET\s+NOT\s+NULL\b|\bALTER\s+COLUMN\b[^;]*\bTYPE\b",
52
+ re.IGNORECASE,
53
+ )
54
+
55
+
56
+ @dataclass(frozen=True)
57
+ class BreakingBlock:
58
+ """A pending inline migration and what in it breaks the serving version."""
59
+
60
+ block: MigrationBlock
61
+ statements: tuple[str, ...]
62
+
63
+ def describe(self) -> str:
64
+ first = " ".join(self.statements[0].split())
65
+ if len(first) > 120:
66
+ first = first[:117] + "..."
67
+ more = (
68
+ f" (and {len(self.statements) - 1} more)"
69
+ if len(self.statements) > 1
70
+ else ""
71
+ )
72
+ return f"@migrate-{self.block.phase}:{self.block.id}: {first}{more}"
73
+
74
+
75
+ def _as_enum(enum_type, value):
76
+ try:
77
+ return enum_type(value)
78
+ except ValueError:
79
+ return None
80
+
81
+
82
+ def _breaks(stmt) -> bool:
83
+ kind = type(stmt).__name__
84
+ if kind == "DropStmt":
85
+ return (
86
+ _as_enum(ObjectType, stmt.removeType) not in _HARMLESS_DROPS
87
+ or _as_enum(DropBehavior, stmt.behavior) == DropBehavior.DROP_CASCADE
88
+ )
89
+ if kind == "RenameStmt":
90
+ return _as_enum(ObjectType, stmt.renameType) not in _HARMLESS_RENAMES
91
+ if kind == "AlterObjectSchemaStmt":
92
+ return True
93
+ if kind == "AlterTableStmt":
94
+ return any(
95
+ _as_enum(AlterTableType, cmd.subtype) in _BREAKING_TABLE_CMDS
96
+ for cmd in stmt.cmds or ()
97
+ if type(cmd).__name__ == "AlterTableCmd"
98
+ )
99
+ if kind == "DoStmt":
100
+ body = " ".join(str(getattr(arg.arg, "sval", "")) for arg in stmt.args or ())
101
+ return bool(_DO_BREAKING.search(body))
102
+ return False
103
+
104
+
105
+ def breaking_statements(sql: str) -> list[str]:
106
+ """The statements in `sql` that take away what an older application uses.
107
+
108
+ SQL that does not parse counts as breaking: what it does is unknown.
109
+ """
110
+ try:
111
+ raw = parse_sql(sql)
112
+ except Exception:
113
+ return [sql.strip()]
114
+ # pglast's locations count bytes, not characters.
115
+ data = sql.encode()
116
+ found: list[str] = []
117
+ for item in raw:
118
+ if _breaks(item.stmt):
119
+ start = item.stmt_location or 0
120
+ end = start + item.stmt_len if item.stmt_len else len(data)
121
+ found.append(data[start:end].decode(errors="replace").strip())
122
+ return found
123
+
124
+
125
+ def breaking_blocks(blocks: list[MigrationBlock], applied: dict) -> list[BreakingBlock]:
126
+ """The blocks not yet in the ledger whose SQL breaks the serving version."""
127
+ found: list[BreakingBlock] = []
128
+ for block in blocks:
129
+ if block.id in applied:
130
+ continue
131
+ statements = breaking_statements(block.sql)
132
+ if statements:
133
+ found.append(BreakingBlock(block, tuple(statements)))
134
+ return found
@@ -277,6 +277,8 @@ def compute_diff(
277
277
  changes.extend(default_privilege_grants)
278
278
  changes = _skip_revokes_on_dropped_relations(changes)
279
279
  changes = _skip_canonical_function_drops(changes, actual)
280
+ _drop_now_what_other_drops_need(changes, actual)
281
+ _hold_revokes_with_their_routine(changes)
280
282
 
281
283
  # Re-apply grants for objects being dropped and recreated.
282
284
  #
@@ -1301,6 +1303,11 @@ def _diff_constraints(
1301
1303
  return changes
1302
1304
 
1303
1305
 
1306
+ def _same_call_types(a: Function, b: Function) -> bool:
1307
+ """Whether two routines take the same input types (only names differ)."""
1308
+ return a.call_shape_known and b.call_shape_known and a.arg_types == b.arg_types
1309
+
1310
+
1304
1311
  def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1305
1312
  """Diff functions between desired and actual schemas."""
1306
1313
  changes: list[Change] = []
@@ -1328,19 +1335,44 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1328
1335
  rename_source = existing
1329
1336
  break
1330
1337
 
1331
- if rename_source:
1332
- # Parameter names changed - use DropAndCreateFunction with the OLD args
1333
- # to ensure proper DROP before CREATE
1338
+ if rename_source is None:
1339
+ changes.append(CreateFunction(function=func))
1340
+ elif not _same_call_types(func, rename_source) and not (
1341
+ func.call_arity_overlaps(rename_source)
1342
+ ):
1343
+ # A new signature no call to the old one can reach: the new
1344
+ # overload is created beside the old, and the old one is an
1345
+ # undeclared routine like any other, dropped as a contract
1346
+ # change below. An application still calling the old
1347
+ # signature keeps working until it has been replaced.
1348
+ changes.append(CreateFunction(function=func))
1349
+ else:
1350
+ # The old signature has to go in the same statement, with the
1351
+ # OLD args so the DROP names what is there. When only the
1352
+ # parameter names changed the identity is the same, so the
1353
+ # two cannot coexist, and a call by position still resolves.
1354
+ # Otherwise the overloads would compete for some call (a new
1355
+ # 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.
1334
1359
  functions_to_drop_for_rename.add(rename_source.signature)
1335
- changes.append(
1336
- DropAndCreateFunction(
1337
- function=func,
1338
- old_args=rename_source.args, # Pass old args for correct DROP
1339
- old_kind=rename_source.kind,
1340
- )
1360
+ same_identity = _same_call_types(func, rename_source)
1361
+ change = DropAndCreateFunction(
1362
+ function=func,
1363
+ old_args=rename_source.args, # Pass old args for correct DROP
1364
+ old_kind=rename_source.kind,
1341
1365
  )
1342
- else:
1343
- changes.append(CreateFunction(function=func))
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
+ changes.append(change)
1344
1376
  elif func.definition_hash != actual.functions[key].definition_hash:
1345
1377
  # A changed return type or kind requires DROP + CREATE: CREATE OR
1346
1378
  # REPLACE refuses both.
@@ -1383,12 +1415,15 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1383
1415
  # Functions to drop (excluding those handled by parameter rename above)
1384
1416
  for key, func in actual.functions.items():
1385
1417
  if key not in desired.functions and key not in functions_to_drop_for_rename:
1418
+ # A contract change: the application that is serving may still
1419
+ # call it, so an expand run keeps it for the run after.
1386
1420
  changes.append(
1387
1421
  DropFunction(
1388
1422
  schema=func.schema,
1389
1423
  name=func.name,
1390
1424
  args=func.args,
1391
1425
  kind=func.kind,
1426
+ contract=True,
1392
1427
  )
1393
1428
  )
1394
1429
 
@@ -1937,6 +1972,64 @@ def _skip_canonical_function_drops(
1937
1972
  ]
1938
1973
 
1939
1974
 
1975
+ def _drop_now_what_other_drops_need(changes: list[Change], actual: Schema) -> None:
1976
+ """Make a routine drop that another drop needs a drop of this run.
1977
+
1978
+ A routine depends on the types its signature names: a dropped view's or
1979
+ domain's or range's (these drops run without CASCADE). If an expand run
1980
+ held the routine back, that other drop would fail on it. So the routine
1981
+ goes in the same run, and since the application that is serving may still
1982
+ call it, that run is offline. A routine whose definition does not even
1983
+ mention the object's name cannot depend on it; one that does may, so the
1984
+ test errs towards offline.
1985
+ """
1986
+ names: set[str] = set()
1987
+ for c in changes:
1988
+ if isinstance(c, DropView):
1989
+ names.add(c.view_name.lower())
1990
+ elif isinstance(c, DropMaterializedView):
1991
+ names.add(c.matview_name.lower())
1992
+ elif isinstance(c, (DropDomain, DropRangeType)):
1993
+ names.add(c.name.lower())
1994
+ if not names:
1995
+ return
1996
+ for c in changes:
1997
+ if not (isinstance(c, DropFunction) and c.contract):
1998
+ continue
1999
+ old = actual.functions.get(f"{c.schema}.{c.name}({c.args})")
2000
+ text = (old.full_definition if old else c.args).lower()
2001
+ needed = sorted(n for n in names if n in text)
2002
+ if needed:
2003
+ c.contract = False
2004
+ c.category = ChangeCategory.OFFLINE
2005
+ c.description += (
2006
+ f" (offline: dropped with {', '.join(needed)}, which it may "
2007
+ f"depend on, while the application may still call it)"
2008
+ )
2009
+
2010
+
2011
+ def _hold_revokes_with_their_routine(changes: list[Change]) -> None:
2012
+ """A revoke on a routine dropped as a contract change is one too.
2013
+
2014
+ Revoking the serving application's EXECUTE breaks its calls exactly as
2015
+ the drop would, so an expand run holds both back.
2016
+ """
2017
+ held = {
2018
+ (c.schema, c.name, c.args)
2019
+ for c in changes
2020
+ if isinstance(c, DropFunction) and c.contract
2021
+ }
2022
+ if not held:
2023
+ return
2024
+ for c in changes:
2025
+ if (
2026
+ isinstance(c, RevokePrivilege)
2027
+ and c.grant.object_type in ("FUNCTION", "PROCEDURE")
2028
+ and (c.grant.schema, c.grant.object_name, c.grant.args) in held
2029
+ ):
2030
+ c.contract = True
2031
+
2032
+
1940
2033
  def _drop_domains(desired: Schema, actual: Schema) -> list[Change]:
1941
2034
  """Drop domains that are no longer declared.
1942
2035
 
@@ -375,6 +375,16 @@ def _query_constraints(conn, schema: str, table_name: str) -> list[Constraint]:
375
375
  return constraints
376
376
 
377
377
 
378
+ def _call_shape(row) -> dict:
379
+ """A pg_proc row's call shape, as `Function` keeps it."""
380
+ nargs = row["nargs"]
381
+ return {
382
+ "arg_types": row["arg_types"] or "",
383
+ "min_call_args": nargs - row["nargdefaults"],
384
+ "max_call_args": None if row["variadic"] else nargs,
385
+ }
386
+
387
+
378
388
  def _query_functions(conn, schema: str) -> dict[str, Function]:
379
389
  """Query functions, procedures and window functions from pg_proc.
380
390
 
@@ -393,6 +403,10 @@ def _query_functions(conn, schema: str) -> dict[str, Function]:
393
403
  pg_get_functiondef(p.oid) AS full_definition,
394
404
  p.oid AS func_oid,
395
405
  p.prokind AS kind,
406
+ oidvectortypes(p.proargtypes) AS arg_types,
407
+ p.pronargs AS nargs,
408
+ p.pronargdefaults AS nargdefaults,
409
+ p.provariadic <> 0 AS variadic,
396
410
  -- PUBLIC retains EXECUTE if the ACL is default (NULL => PUBLIC
397
411
  -- EXECUTE) or an explicit grantee=0 EXECUTE entry exists.
398
412
  (
@@ -435,6 +449,7 @@ def _query_functions(conn, schema: str) -> dict[str, Function]:
435
449
  security_definer=row["security_definer"],
436
450
  public_execute=row["public_execute"],
437
451
  kind=row["kind"],
452
+ **_call_shape(row),
438
453
  )
439
454
  functions[func.signature] = func
440
455
 
@@ -474,6 +489,10 @@ def _query_aggregates(conn, schema: str) -> dict[str, Function]:
474
489
  SELECT
475
490
  p.proname AS name,
476
491
  pg_get_function_identity_arguments(p.oid) AS args,
492
+ oidvectortypes(p.proargtypes) AS arg_types,
493
+ p.pronargs AS nargs,
494
+ p.pronargdefaults AS nargdefaults,
495
+ p.provariadic <> 0 AS variadic,
477
496
  format_type(p.prorettype, NULL) AS result_type,
478
497
  p.proparallel AS parallel,
479
498
  a.aggkind, {support_cols},
@@ -581,6 +600,7 @@ def _query_aggregates(conn, schema: str) -> dict[str, Function]:
581
600
  support_functions=tuple(signatures),
582
601
  # Aggregates are never SECURITY DEFINER.
583
602
  security_definer=False,
603
+ **_call_shape(row),
584
604
  )
585
605
  body = ",\n ".join(options)
586
606
  func.full_definition = (
@@ -12,6 +12,7 @@ from pathlib import Path
12
12
  from typing import Callable, Optional
13
13
 
14
14
  from .changes import Change
15
+ from .contract import breaking_blocks
15
16
  from .config import PgDeclareConfig, logger, resolve
16
17
  from .differ import compute_diff, partition_notes, undeclared_extensions
17
18
  from .drop_directive import format_drop_errors, validate_drops_runtime
@@ -25,7 +26,7 @@ from .ledger import (
25
26
  mark_blocks_applied,
26
27
  parse_migration_blocks,
27
28
  )
28
- from .models import Schema
29
+ from .models import ChangeCategory, Schema
29
30
  from .schema_parser import build_desired_schema, execute_do_blocks, parse_do_blocks
30
31
 
31
32
  # Roles and role memberships are cluster-wide: applying them in one database
@@ -38,6 +39,15 @@ def is_cluster_change(change: Change) -> bool:
38
39
  return change.object_type in CLUSTER_OBJECT_TYPES
39
40
 
40
41
 
42
+ def is_held_back(change: Change) -> bool:
43
+ """True for a change an `expand_only` run leaves for the run after.
44
+
45
+ Only an online contract change: one the differ already made offline (it
46
+ could not wait) is refused by the offline check like any other.
47
+ """
48
+ return change.contract and change.category == ChangeCategory.ONLINE
49
+
50
+
41
51
  @dataclass
42
52
  class SchemaRunResult:
43
53
  """What one run of the pipeline did (or, on a dry run, planned)."""
@@ -46,6 +56,8 @@ class SchemaRunResult:
46
56
  changes: list[Change] = field(default_factory=list)
47
57
  executed_sql: list[str] = field(default_factory=list)
48
58
  skipped_cluster_changes: list[Change] = field(default_factory=list)
59
+ # With `expand_only`: the contract changes left for the run after.
60
+ held_back: list[Change] = field(default_factory=list)
49
61
  migration_blocks: list[MigrationBlock] = field(default_factory=list)
50
62
  fresh_install: bool = False
51
63
 
@@ -54,6 +66,10 @@ class SchemaConvergenceError(Exception):
54
66
  """A schema run applied its changes and still did not reach the declared schema."""
55
67
 
56
68
 
69
+ class ExpandRefusedError(Exception):
70
+ """An `expand_only` run found a pending inline migration it cannot hold back."""
71
+
72
+
57
73
  def compute_residual_changes(
58
74
  desired: Schema,
59
75
  connection_string: str,
@@ -61,13 +77,15 @@ def compute_residual_changes(
61
77
  config: Optional[PgDeclareConfig] = None,
62
78
  *,
63
79
  skip_cluster_changes: bool = False,
80
+ expand_only: bool = False,
64
81
  ) -> list[Change]:
65
82
  """Re-diff `desired` against the database, after changes have been applied.
66
83
 
67
84
  The list is empty when the run converged. Anything in it is a declaration
68
85
  the run failed to reach, which only the *next* diff would otherwise report.
69
86
  With `skip_cluster_changes`, role-level changes are left out (a rehearsal
70
- on a clone does not apply them).
87
+ on a clone does not apply them). With `expand_only`, so are the contract
88
+ changes an expand run holds back on purpose.
71
89
  """
72
90
  cfg = resolve(config)
73
91
  residual_actual = introspect_schema(
@@ -85,6 +103,8 @@ def compute_residual_changes(
85
103
  )
86
104
  if skip_cluster_changes:
87
105
  residual = [c for c in residual if not is_cluster_change(c)]
106
+ if expand_only:
107
+ residual = [c for c in residual if not is_held_back(c)]
88
108
  return residual
89
109
 
90
110
 
@@ -96,6 +116,7 @@ def assert_schema_converged(
96
116
  config: Optional[PgDeclareConfig] = None,
97
117
  *,
98
118
  skip_cluster_changes: bool = False,
119
+ expand_only: bool = False,
99
120
  ) -> None:
100
121
  """Fail the run if a second diff would still find work to do."""
101
122
  cfg = resolve(config)
@@ -106,6 +127,7 @@ def assert_schema_converged(
106
127
  locked_functions,
107
128
  cfg,
108
129
  skip_cluster_changes=skip_cluster_changes,
130
+ expand_only=expand_only,
109
131
  )
110
132
 
111
133
  if not residual:
@@ -164,6 +186,7 @@ def apply_declared_schema(
164
186
  force: bool = False,
165
187
  dry_run: bool = False,
166
188
  expect_converged: bool = False,
189
+ expand_only: bool = False,
167
190
  prove: bool = False,
168
191
  prepare_clone: Optional[Callable[[str], None]] = None,
169
192
  locked_functions: Optional[set[str]] = None,
@@ -192,6 +215,12 @@ def apply_declared_schema(
192
215
  inline block, no ledger row, no DDL, no DO block. Only the plan
193
216
  database is rebuilt.
194
217
  expect_converged: Any difference fails the run before anything is applied
218
+ expand_only: The expand half of an expand/contract deploy, run while
219
+ the previous version of the application still serves: contract
220
+ changes (a routine it may still call, dropped or replaced by a new
221
+ signature) are left in place for a later run without this flag,
222
+ made once that version has stopped. The convergence check allows
223
+ exactly those.
195
224
  prove: With `dry_run`, rehearse the real run on a throwaway clone of
196
225
  the database instead of previewing it (see
197
226
  `pgdeclare.prove.prove_declared_schema`). Needs `dry_run=True`.
@@ -217,6 +246,7 @@ def apply_declared_schema(
217
246
  plan_db_name,
218
247
  offline=offline,
219
248
  force=force,
249
+ expand_only=expand_only,
220
250
  prepare=prepare_clone,
221
251
  locked_functions=locked_functions,
222
252
  config=config,
@@ -230,6 +260,7 @@ def apply_declared_schema(
230
260
  force=force,
231
261
  dry_run=dry_run,
232
262
  expect_converged=expect_converged,
263
+ expand_only=expand_only,
233
264
  locked_functions=locked_functions,
234
265
  config=config,
235
266
  )
@@ -245,6 +276,7 @@ def run_declared_schema(
245
276
  dry_run: bool = False,
246
277
  expect_converged: bool = False,
247
278
  skip_cluster_changes: bool = False,
279
+ expand_only: bool = False,
248
280
  locked_functions: Optional[set[str]] = None,
249
281
  config: Optional[PgDeclareConfig] = None,
250
282
  ) -> SchemaRunResult:
@@ -292,6 +324,20 @@ def run_declared_schema(
292
324
  logger.info("Processing inline migrations...")
293
325
  pre_blocks = [b for b in migration_blocks if b.phase == "before"]
294
326
  post_blocks = [b for b in migration_blocks if b.phase == "after"]
327
+ if expand_only:
328
+ # Before any block runs: a block is SQL run as written, so one
329
+ # that takes away what the serving version uses cannot be held
330
+ # back past the diff that may rely on it. It runs offline.
331
+ breaking = breaking_blocks(
332
+ migration_blocks, get_applied_migrations(connection_string, cfg)
333
+ )
334
+ if breaking:
335
+ raise ExpandRefusedError(
336
+ "expand-only: pending inline migrations take away what the "
337
+ "application still serving may use, so this migration "
338
+ "must run offline:\n"
339
+ + "\n".join(f" - {b.describe()}" for b in breaking)
340
+ )
295
341
  if dry_run:
296
342
  applied = get_applied_migrations(connection_string, cfg)
297
343
  report_pending_migration_blocks(migration_blocks, applied, force=force)
@@ -354,6 +400,16 @@ def run_declared_schema(
354
400
  if skip_cluster_changes:
355
401
  result.skipped_cluster_changes = [c for c in changes if is_cluster_change(c)]
356
402
  changes = [c for c in changes if not is_cluster_change(c)]
403
+ if expand_only:
404
+ result.held_back = [c for c in changes if is_held_back(c)]
405
+ changes = [c for c in changes if not is_held_back(c)]
406
+ for c in result.held_back:
407
+ say(
408
+ style(
409
+ "yellow",
410
+ f"Held back for the contract run: {c.description}",
411
+ )
412
+ )
357
413
  result.changes = changes
358
414
 
359
415
  if not changes:
@@ -468,5 +524,6 @@ def run_declared_schema(
468
524
  locked_functions=locked_functions,
469
525
  config=cfg,
470
526
  skip_cluster_changes=skip_cluster_changes,
527
+ expand_only=expand_only,
471
528
  )
472
529
  return result
@@ -148,6 +148,35 @@ class Function:
148
148
  # Aggregates only: signatures of the functions the aggregate calls (state,
149
149
  # final, combine and so on). Dropping one of them drops the aggregate.
150
150
  support_functions: tuple[str, ...] = ()
151
+ # The call shape, which decides whether an old and a new overload of one
152
+ # name can live side by side (see `call_arity_overlaps`). `arg_types` is
153
+ # oidvectortypes(proargtypes): the input types without names or modes.
154
+ # A call passes from `min_call_args` (pronargs - pronargdefaults) to
155
+ # `max_call_args` (pronargs) arguments; None for a VARIADIC routine, which
156
+ # takes any number above the minimum. All three are None when unknown.
157
+ arg_types: Optional[str] = None
158
+ min_call_args: Optional[int] = None
159
+ max_call_args: Optional[int] = None
160
+
161
+ @property
162
+ def call_shape_known(self) -> bool:
163
+ return self.arg_types is not None and self.min_call_args is not None
164
+
165
+ def call_arity_overlaps(self, other: "Function") -> bool:
166
+ """Whether some call could match both routines by its argument count.
167
+
168
+ PostgreSQL resolves an overloaded call among the routines that accept
169
+ that many arguments, defaults and VARIADIC included. Two overloads of
170
+ one name whose ranges overlap can make a call ambiguous ("function ...
171
+ is not unique") or pick the other one; two whose ranges are disjoint
172
+ never compete for a call. An unknown shape counts as overlapping.
173
+ """
174
+ if not (self.call_shape_known and other.call_shape_known):
175
+ return True
176
+ assert self.min_call_args is not None and other.min_call_args is not None
177
+ self_hi = self.max_call_args if self.max_call_args is not None else 1 << 30
178
+ other_hi = other.max_call_args if other.max_call_args is not None else 1 << 30
179
+ return self.min_call_args <= other_hi and other.min_call_args <= self_hi
151
180
 
152
181
  @property
153
182
  def qualified_name(self) -> str:
@@ -238,6 +238,7 @@ def prove_declared_schema(
238
238
  *,
239
239
  offline: bool = False,
240
240
  force: bool = False,
241
+ expand_only: bool = False,
241
242
  prepare: Optional[Callable[[str], None]] = None,
242
243
  locked_functions: Optional[set[str]] = None,
243
244
  config: Optional[PgDeclareConfig] = None,
@@ -259,6 +260,7 @@ def prove_declared_schema(
259
260
  declared schema is built in it, and the clone is created and
260
261
  dropped through a connection to it
261
262
  offline: As for `apply_declared_schema`
263
+ expand_only: As for `apply_declared_schema`
262
264
  force: As for `apply_declared_schema`; the rehearsal still fails on
263
265
  residual changes and unexplained row loss
264
266
  prepare: Called with the clone's connection string before the run,
@@ -308,6 +310,7 @@ def prove_declared_schema(
308
310
  offline=offline,
309
311
  force=force,
310
312
  skip_cluster_changes=True,
313
+ expand_only=expand_only,
311
314
  locked_functions=locked_functions,
312
315
  config=run_cfg,
313
316
  )
@@ -336,6 +339,7 @@ def prove_declared_schema(
336
339
  locked_functions,
337
340
  run_cfg,
338
341
  skip_cluster_changes=True,
342
+ expand_only=expand_only,
339
343
  )
340
344
  drop_directives: set[str] = set()
341
345
  for block in run.migration_blocks:
@@ -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.1.2"
117
+ assert pgdeclare.__version__ == "0.2.0"
@@ -0,0 +1,367 @@
1
+ """Routines the running application may still call: expand/contract.
2
+
3
+ A blue-green deploy migrates while the previous version of the application
4
+ still serves. Dropping a routine it calls, or replacing its signature, breaks
5
+ every one of those calls until the new version takes over. The differ marks
6
+ such a drop as a contract change, which an `expand_only` run holds back for a
7
+ run after the old version has stopped; and a signature change whose old and
8
+ new overloads cannot coexist (a call could match both) is offline.
9
+
10
+ The unit tests drive the differ; the integration tests run the pipeline
11
+ against a real server and need TEST_DATABASE_URL.
12
+ """
13
+
14
+ import os
15
+ import uuid
16
+ from pathlib import Path
17
+
18
+ import psycopg2
19
+ import pytest
20
+
21
+ from pgdeclare import (
22
+ ExpandRefusedError,
23
+ PgDeclareConfig,
24
+ apply_declared_schema,
25
+ breaking_blocks,
26
+ breaking_statements,
27
+ compute_diff,
28
+ )
29
+ from pgdeclare.changes import (
30
+ CreateFunction,
31
+ DropAndCreateFunction,
32
+ DropFunction,
33
+ DropView,
34
+ RevokePrivilege,
35
+ )
36
+ from pgdeclare.ledger import MigrationBlock
37
+ from pgdeclare.migrate import is_held_back
38
+ from pgdeclare.models import ChangeCategory, Function, Grant, Schema, View
39
+
40
+
41
+ def _fn(
42
+ name: str,
43
+ args: str,
44
+ arg_types: str,
45
+ min_args: int,
46
+ max_args: int | None,
47
+ body: str = "1",
48
+ ) -> Function:
49
+ return Function(
50
+ schema="public",
51
+ name=name,
52
+ args=args,
53
+ full_definition=f"CREATE FUNCTION {name}({args}) {body}",
54
+ definition_hash=f"{name}-{args}-{body}",
55
+ arg_types=arg_types,
56
+ min_call_args=min_args,
57
+ max_call_args=max_args,
58
+ )
59
+
60
+
61
+ def _schema(*functions: Function, **kw) -> Schema:
62
+ return Schema(functions={f.signature: f for f in functions}, **kw)
63
+
64
+
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.
70
+ old = _fn("account", "a uuid, s uuid", "uuid, uuid", 2, 2)
71
+ new = _fn("account", "a uuid, s uuid, ip text", "uuid, uuid, text", 2, 3)
72
+ changes = compute_diff(_schema(new), _schema(old))
73
+ assert [type(c) for c in changes] == [DropAndCreateFunction]
74
+ assert changes[0].category == ChangeCategory.OFFLINE
75
+ assert "offline" in changes[0].description
76
+ assert not is_held_back(changes[0])
77
+
78
+ def test_a_signature_no_old_call_reaches_is_created_beside_the_old(self):
79
+ old = _fn("total", "a int", "integer", 1, 1)
80
+ new = _fn("total", "a int, b int", "integer, integer", 2, 2)
81
+ changes = compute_diff(_schema(new), _schema(old))
82
+ assert [type(c) for c in changes] == [CreateFunction, DropFunction]
83
+ assert all(c.category == ChangeCategory.ONLINE for c in changes)
84
+ assert not changes[0].contract
85
+ assert changes[1].contract and is_held_back(changes[1])
86
+ assert changes[1].object_name == "public.total(a int)"
87
+
88
+ def test_a_variadic_overload_overlaps_every_longer_call(self):
89
+ old = _fn("total", "a int, b int, c int", "integer, integer, integer", 3, 3)
90
+ new = _fn("total", "VARIADIC a int[]", "integer[]", 1, None)
91
+ changes = compute_diff(_schema(new), _schema(old))
92
+ assert [type(c) for c in changes] == [DropAndCreateFunction]
93
+ assert changes[0].category == ChangeCategory.OFFLINE
94
+
95
+ def test_renamed_parameters_stay_one_online_statement(self):
96
+ old = _fn("total", "a int", "integer", 1, 1)
97
+ new = _fn("total", "amount int", "integer", 1, 1)
98
+ changes = compute_diff(_schema(new), _schema(old))
99
+ assert [type(c) for c in changes] == [DropAndCreateFunction]
100
+ assert changes[0].category == ChangeCategory.ONLINE
101
+ assert not changes[0].contract
102
+
103
+ def test_an_unknown_call_shape_counts_as_overlapping(self):
104
+ old = Function("public", "f", "a int", "CREATE f 1", "f1")
105
+ new = Function("public", "f", "a int, b int", "CREATE f 2", "f2")
106
+ changes = compute_diff(_schema(new), _schema(old))
107
+ assert [type(c) for c in changes] == [DropAndCreateFunction]
108
+ assert changes[0].category == ChangeCategory.OFFLINE
109
+
110
+
111
+ class TestDroppedRoutines:
112
+ def test_an_undeclared_routine_is_a_contract_drop(self):
113
+ gone = _fn("gone", "a int", "integer", 1, 1)
114
+ changes = compute_diff(Schema(), _schema(gone))
115
+ assert [type(c) for c in changes] == [DropFunction]
116
+ assert changes[0].category == ChangeCategory.ONLINE
117
+ assert is_held_back(changes[0])
118
+
119
+ def test_the_revoke_on_a_dropped_routine_waits_with_it(self):
120
+ gone = _fn("gone", "a int", "integer", 1, 1)
121
+ grant = Grant("FUNCTION", "gone", "public", "EXECUTE", "app", args="a int")
122
+ changes = compute_diff(Schema(), _schema(gone, grants=[grant]))
123
+ revokes = [c for c in changes if isinstance(c, RevokePrivilege)]
124
+ assert len(revokes) == 1 and is_held_back(revokes[0])
125
+
126
+ def test_a_routine_another_drop_needs_goes_now_and_offline(self):
127
+ # DROP VIEW runs without CASCADE, so it would fail on a function
128
+ # returning its row type that an expand run had held back.
129
+ view = View(schema="public", name="report", definition="SELECT 1 AS x")
130
+ gone = _fn("gone", "", "", 0, 0, body="RETURNS SETOF report")
131
+ kept = _fn("kept", "", "", 0, 0)
132
+ changes = compute_diff(
133
+ _schema(kept), _schema(gone, kept, views={"public.report": view})
134
+ )
135
+ assert any(isinstance(c, DropView) for c in changes)
136
+ drop = next(c for c in changes if isinstance(c, DropFunction))
137
+ assert drop.category == ChangeCategory.OFFLINE
138
+ assert not drop.contract
139
+ assert "report" in drop.description
140
+
141
+
142
+ # =============================================================================
143
+ # Integration tests
144
+ # =============================================================================
145
+
146
+
147
+ @pytest.fixture
148
+ def server_url():
149
+ url = os.environ.get("TEST_DATABASE_URL")
150
+ if not url:
151
+ pytest.skip("TEST_DATABASE_URL not set")
152
+ return url
153
+
154
+
155
+ def _with_db(url: str, name: str) -> str:
156
+ return url.rsplit("/", 1)[0] + f"/{name}"
157
+
158
+
159
+ def _run(url: str, sql: str) -> list[tuple]:
160
+ conn = psycopg2.connect(url)
161
+ conn.autocommit = True
162
+ try:
163
+ with conn.cursor() as cur:
164
+ cur.execute(sql)
165
+ return cur.fetchall() if cur.description else []
166
+ finally:
167
+ conn.close()
168
+
169
+
170
+ @pytest.fixture
171
+ def databases(server_url):
172
+ suffix = uuid.uuid4().hex[:8]
173
+ target, plan = f"pgdeclare_ec_target_{suffix}", f"pgdeclare_ec_plan_{suffix}"
174
+ for name in (target, plan):
175
+ _run(server_url, f'CREATE DATABASE "{name}"')
176
+ try:
177
+ yield _with_db(server_url, target), plan
178
+ finally:
179
+ for name in (target, plan):
180
+ _run(server_url, f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE)')
181
+
182
+
183
+ QUIET = PgDeclareConfig(report=lambda _line: None)
184
+
185
+
186
+ def _declare(sql_dir: Path, sql: str) -> None:
187
+ schemas = sql_dir / "schemas"
188
+ schemas.mkdir(parents=True, exist_ok=True)
189
+ (schemas / "schema.sql").write_text(sql)
190
+
191
+
192
+ V1 = """
193
+ CREATE FUNCTION account(a uuid, s uuid) RETURNS int
194
+ LANGUAGE sql AS 'SELECT 1';
195
+ CREATE FUNCTION total(a int) RETURNS int LANGUAGE sql AS 'SELECT a';
196
+ CREATE FUNCTION gone() RETURNS int LANGUAGE sql AS 'SELECT 3';
197
+ """
198
+
199
+ OLD_CALLS = "SELECT account(gen_random_uuid(), gen_random_uuid()), total(1), gone()"
200
+
201
+
202
+ class TestDeployWhileTheOldVersionServes:
203
+ def test_a_new_default_parameter_is_refused_online(self, tmp_path, databases):
204
+ target, plan = databases
205
+ sql_dir = tmp_path / "sql"
206
+ _declare(sql_dir, V1)
207
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
208
+
209
+ _declare(
210
+ sql_dir,
211
+ V1.replace(
212
+ "account(a uuid, s uuid)",
213
+ "account(a uuid, s uuid, ip text DEFAULT NULL)",
214
+ ),
215
+ )
216
+ # Before the fix this dropped account(uuid, uuid) online, and every
217
+ # call the serving version made failed "does not exist".
218
+ with pytest.raises(Exception, match="Migration execution failed"):
219
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
220
+ assert _run(target, OLD_CALLS) == [(1, 1, 3)]
221
+
222
+ apply_declared_schema(target, sql_dir, plan, offline=True, config=QUIET)
223
+ assert _run(
224
+ target, "SELECT account(gen_random_uuid(), gen_random_uuid(), 'x')"
225
+ ) == [(1,)]
226
+
227
+ def test_expand_keeps_old_calls_working_and_contract_drops(
228
+ self, tmp_path, databases
229
+ ):
230
+ target, plan = databases
231
+ sql_dir = tmp_path / "sql"
232
+ _declare(sql_dir, V1)
233
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
234
+
235
+ v2 = V1.replace(
236
+ "total(a int) RETURNS int LANGUAGE sql AS 'SELECT a'",
237
+ "total(a int, b int) RETURNS int LANGUAGE sql AS 'SELECT a + b'",
238
+ ).replace("CREATE FUNCTION gone() RETURNS int LANGUAGE sql AS 'SELECT 3';", "")
239
+ _declare(sql_dir, v2)
240
+
241
+ # Expand: the new signature exists, and so does everything the old
242
+ # version calls; the run converges up to the held-back drops.
243
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
244
+ assert _run(target, OLD_CALLS) == [(1, 1, 3)]
245
+ assert _run(target, "SELECT total(1, 2)") == [(3,)]
246
+
247
+ # Contract, once the old version has stopped.
248
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
249
+ assert _run(
250
+ target,
251
+ "SELECT proname || '(' || pg_get_function_identity_arguments(oid) || ')' "
252
+ "FROM pg_proc WHERE pronamespace = 'public'::regnamespace ORDER BY 1",
253
+ ) == [("account(a uuid, s uuid)",), ("total(a integer, b integer)",)]
254
+ # And a second run, expand or not, finds nothing.
255
+ apply_declared_schema(
256
+ target, sql_dir, plan, expect_converged=True, config=QUIET
257
+ )
258
+
259
+
260
+ # =============================================================================
261
+ # Inline migrations
262
+ # =============================================================================
263
+
264
+
265
+ class TestBreakingStatements:
266
+ @pytest.mark.parametrize(
267
+ "sql",
268
+ [
269
+ # The block that broke production on 2026-11-19.
270
+ "DROP FUNCTION IF EXISTS sec_get_account_for_session(UUID, UUID);",
271
+ "DROP TABLE old_things;",
272
+ "DROP VIEW v;",
273
+ "DROP INDEX i CASCADE;",
274
+ "ALTER TABLE t RENAME COLUMN a TO b;",
275
+ "ALTER TABLE t RENAME TO u;",
276
+ "ALTER FUNCTION f(int) RENAME TO g;",
277
+ "ALTER FUNCTION f(int) SET SCHEMA archive;",
278
+ "ALTER TABLE t DROP COLUMN c;",
279
+ "ALTER TABLE t ALTER COLUMN c TYPE bigint;",
280
+ "ALTER TABLE t ALTER COLUMN c SET NOT NULL;",
281
+ "DO $$ BEGIN EXECUTE 'DROP FUNCTION g()'; END $$;",
282
+ "DO $$ BEGIN ALTER TABLE t RENAME COLUMN a TO b; END $$;",
283
+ "THIS IS NOT SQL;",
284
+ ],
285
+ )
286
+ def test_breaks(self, sql):
287
+ assert breaking_statements(sql)
288
+
289
+ @pytest.mark.parametrize(
290
+ "sql",
291
+ [
292
+ "UPDATE t SET a = 1 WHERE a IS NULL;",
293
+ "INSERT INTO t (a) SELECT 1 ON CONFLICT DO NOTHING;",
294
+ "DROP INDEX IF EXISTS i;",
295
+ "DROP TRIGGER IF EXISTS tr ON t;",
296
+ "ALTER INDEX i RENAME TO j;",
297
+ "ALTER TABLE t RENAME CONSTRAINT c TO d;",
298
+ "ALTER TABLE t ALTER COLUMN c DROP NOT NULL;",
299
+ "ALTER TABLE t ADD COLUMN c int;",
300
+ "DO $$ BEGIN UPDATE t SET a = 1; END $$;",
301
+ "-- DROP FUNCTION f(); in a comment\nSELECT 1;",
302
+ ],
303
+ )
304
+ def test_does_not_break(self, sql):
305
+ assert breaking_statements(sql) == []
306
+
307
+ def test_names_the_statement_in_a_block(self):
308
+ sql = "UPDATE t SET a = 1;\n-- why\nDROP FUNCTION f(uuid);\nSELECT 'é';"
309
+ assert breaking_statements(sql) == ["DROP FUNCTION f(uuid)"]
310
+
311
+ def test_only_pending_blocks_count(self):
312
+ def block(id_: str, sql: str) -> MigrationBlock:
313
+ return MigrationBlock(id_, Path("x.sql"), sql, "h")
314
+
315
+ blocks = [
316
+ block("old", "DROP FUNCTION f();"),
317
+ block("new", "DROP FUNCTION g();"),
318
+ block("backfill", "UPDATE t SET a = 1;"),
319
+ ]
320
+ found = breaking_blocks(blocks, {"old": ("when", "h")})
321
+ assert [b.block.id for b in found] == ["new"]
322
+ assert found[0].describe() == "@migrate-before:new: DROP FUNCTION g()"
323
+
324
+
325
+ INCIDENT_V1 = """
326
+ CREATE TABLE session (id uuid);
327
+ CREATE FUNCTION account(a uuid, s uuid) RETURNS int LANGUAGE sql AS 'SELECT 1';
328
+ """
329
+
330
+ # What #15547 wrote: a block dropping the old signature by hand.
331
+ INCIDENT_V2 = """
332
+ -- @migrate-before:2026-11-18_account_ip
333
+ DROP FUNCTION IF EXISTS account(UUID, UUID);
334
+ -- @end-migrate
335
+ CREATE TABLE session (id uuid);
336
+ CREATE FUNCTION account(a uuid, s uuid, ip text DEFAULT NULL) RETURNS int
337
+ LANGUAGE sql AS 'SELECT 1';
338
+ """
339
+
340
+
341
+ class TestExpandRefusesBreakingBlocks:
342
+ def test_a_pending_block_dropping_a_routine_is_refused(self, tmp_path, databases):
343
+ target, plan = databases
344
+ sql_dir = tmp_path / "sql"
345
+ _declare(sql_dir, INCIDENT_V1)
346
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
347
+
348
+ _declare(sql_dir, INCIDENT_V2)
349
+ with pytest.raises(ExpandRefusedError, match="2026-11-18_account_ip"):
350
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
351
+ # Nothing ran: the serving version's call still resolves.
352
+ old_call = "SELECT account(gen_random_uuid(), gen_random_uuid())"
353
+ assert _run(target, old_call) == [(1,)]
354
+
355
+ apply_declared_schema(target, sql_dir, plan, offline=True, config=QUIET)
356
+ # Once applied, the block is in the ledger and no longer holds anything.
357
+ apply_declared_schema(
358
+ target, sql_dir, plan, expand_only=True, expect_converged=True, config=QUIET
359
+ )
360
+
361
+ def test_a_fresh_database_runs_no_block_and_is_not_refused(
362
+ self, tmp_path, databases
363
+ ):
364
+ target, plan = databases
365
+ sql_dir = tmp_path / "sql"
366
+ _declare(sql_dir, INCIDENT_V2)
367
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
@@ -245,11 +245,18 @@ def databases(server_url):
245
245
  QUIET = PgDeclareConfig(report=lambda _line: None)
246
246
 
247
247
 
248
- def _apply(sql_dir: Path, sql: str, target_url: str, plan_db: str, config=QUIET):
248
+ def _apply(
249
+ sql_dir: Path,
250
+ sql: str,
251
+ target_url: str,
252
+ plan_db: str,
253
+ config=QUIET,
254
+ offline: bool = False,
255
+ ):
249
256
  schemas = sql_dir / "schemas"
250
257
  schemas.mkdir(parents=True, exist_ok=True)
251
258
  (schemas / "schema.sql").write_text(sql)
252
- apply_declared_schema(target_url, sql_dir, plan_db, config=config)
259
+ apply_declared_schema(target_url, sql_dir, plan_db, offline=offline, config=config)
253
260
 
254
261
 
255
262
  def _pending(sql_dir: Path, target_url: str, plan_db: str, config=QUIET):
@@ -399,7 +406,17 @@ class TestRoutineRoundTrip:
399
406
  .replace("step(a int, b int)", "step(x int, y int)")
400
407
  .replace("'SELECT a + b'", "'SELECT x + y'")
401
408
  )
402
- _apply(sql_dir, recreated, target_url, plan_db)
409
+ # The new procedure signature competes with the old one for a call
410
+ # of two arguments, so the swap is offline.
411
+ offline = [
412
+ c
413
+ for c in _plan(sql_dir, recreated, target_url, plan_db)
414
+ if c.category.value == "offline"
415
+ ]
416
+ assert [c.object_name for c in offline] == [
417
+ "public.book(IN amount bigint, INOUT booked bigint)"
418
+ ]
419
+ _apply(sql_dir, recreated, target_url, plan_db, offline=True)
403
420
  routines = _routines(target_url)
404
421
  assert ("book", "p", "IN amount bigint, INOUT booked bigint") in routines
405
422
  assert ('odd "proc"', "f", "") in routines
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