pgdeclare 0.1.2__tar.gz → 0.2.1__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.1}/CHANGELOG.md +44 -0
  2. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/PKG-INFO +2 -2
  3. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/README.md +1 -1
  4. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/pyproject.toml +1 -1
  5. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/__init__.py +8 -1
  6. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/changes.py +5 -0
  7. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/cli.py +9 -1
  8. pgdeclare-0.2.1/src/pgdeclare/contract.py +134 -0
  9. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/differ.py +108 -11
  10. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/introspection.py +20 -0
  11. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/migrate.py +59 -2
  12. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/models.py +29 -0
  13. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/prove.py +4 -0
  14. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_boundary.py +1 -1
  15. pgdeclare-0.2.1/tests/test_expand_contract.py +390 -0
  16. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_routines.py +22 -3
  17. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/.gitignore +0 -0
  18. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/LICENSE +0 -0
  19. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/NOTICE +0 -0
  20. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/__main__.py +0 -0
  21. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/config.py +0 -0
  22. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/drop_directive.py +0 -0
  23. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/executor.py +0 -0
  24. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/ledger.py +0 -0
  25. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/py.typed +0 -0
  26. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/quoting.py +0 -0
  27. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/retry_executor.py +0 -0
  28. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/schema_parser.py +0 -0
  29. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/src/pgdeclare/statement_parser.py +0 -0
  30. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/conftest.py +0 -0
  31. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/dbutil.py +0 -0
  32. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_cli.py +0 -0
  33. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_comments.py +0 -0
  34. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_default_privileges.py +0 -0
  35. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_diff.py +0 -0
  36. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_domains.py +0 -0
  37. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_foreign_data.py +0 -0
  38. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_integration.py +0 -0
  39. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_lifecycle.py +0 -0
  40. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_materialized_views.py +0 -0
  41. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_partitions.py +0 -0
  42. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_pipeline.py +0 -0
  43. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_prove.py +0 -0
  44. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_publications_rules.py +0 -0
  45. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_ranges_collations.py +0 -0
  46. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_retry_executor.py +0 -0
  47. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_security.py +0 -0
  48. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_sequences.py +0 -0
  49. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_statement_parser.py +0 -0
  50. {pgdeclare-0.1.2 → pgdeclare-0.2.1}/tests/test_views.py +0 -0
@@ -5,6 +5,50 @@ 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.1] - 2026-11-19
9
+
10
+ ### Changed
11
+
12
+ - A change of a routine's parameter names alone is now offline. The drop and
13
+ re-create is still one statement, but a call that names the old
14
+ parameters (`f(p_old => 1)`) fails from then on, so an application still
15
+ using them must be stopped.
16
+
17
+ ## [0.2.0] - 2026-11-19
18
+
19
+ ### Added
20
+
21
+ - Expand/contract for routines. Dropping an undeclared function, procedure
22
+ or aggregate, and revoking a grant on it, is a *contract* change:
23
+ `apply --expand-only` (`expand_only=True`) holds contract changes back for
24
+ a later run without the flag, so a deploy can migrate while the previous
25
+ version of the application still calls them. The convergence check of an
26
+ expand run allows exactly those changes.
27
+ - An expand run refuses, before anything runs, a pending `@migrate-before`
28
+ or `@migrate-after` block that takes away what the serving version may use
29
+ (`ExpandRefusedError`): a `DROP` (but of an index, trigger or extended
30
+ statistics without `CASCADE`), a rename of anything a query names, `SET
31
+ SCHEMA`, or a column dropped, retyped or made `NOT NULL`. A block is SQL
32
+ run as written and cannot be postponed past the diff, so such a migration
33
+ runs offline. `breaking_statements(sql)` and `breaking_blocks(blocks,
34
+ applied)` give the same answer to a caller deciding how to deploy.
35
+ - `Function` carries its call shape (`arg_types`, `min_call_args`,
36
+ `max_call_args`), read from `pg_proc`.
37
+
38
+ ### Changed
39
+
40
+ - A routine whose signature changes is no longer always dropped and
41
+ re-created online. When no call can match both the old and the new
42
+ signature (the argument counts they accept do not overlap), the new one is
43
+ created beside the old and the old one is dropped as a contract change.
44
+ When a call could match both (a new parameter with a `DEFAULT`, or new
45
+ types at the same arity), the drop and re-create is now **offline**: an
46
+ application still calling the old signature fails from the drop on, and
47
+ the two overloads cannot coexist without making its calls ambiguous. A
48
+ change of parameter names only stays one online statement.
49
+ - A dropped routine whose definition names a view, materialized view, domain
50
+ or range type the same run drops is dropped in that run, offline.
51
+
8
52
  ## [0.1.2] - 2026-10-19
9
53
 
10
54
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pgdeclare
3
- Version: 0.1.2
3
+ Version: 0.2.1
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.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.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.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.1.2"
7
+ version = "0.2.1"
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.1"
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,48 @@ 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 that names the old
1354
+ # parameters (`p_old => ...`) fails from the DROP on.
1355
+ # Otherwise the overloads would compete for some call (a new
1356
+ # DEFAULT that lets a call of the old length match both is
1357
+ # the usual case: "function ... is not unique"), and a call
1358
+ # to the old signature fails from the DROP on. Either way an
1359
+ # application still calling the old form breaks: offline.
1334
1360
  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
- )
1361
+ change = DropAndCreateFunction(
1362
+ function=func,
1363
+ old_args=rename_source.args, # Pass old args for correct DROP
1364
+ old_kind=rename_source.kind,
1365
+ category=ChangeCategory.OFFLINE,
1341
1366
  )
1342
- else:
1343
- changes.append(CreateFunction(function=func))
1367
+ why = (
1368
+ "a call naming the old parameters fails once it is dropped"
1369
+ if _same_call_types(func, rename_source)
1370
+ else "a call to the old signature fails once it is "
1371
+ "dropped, and the two cannot coexist because a call "
1372
+ "could match both"
1373
+ )
1374
+ change.description = (
1375
+ f"Drop {rename_source.keyword.lower()} "
1376
+ f"{rename_source.signature} and create "
1377
+ f"{func.signature} (offline: {why})"
1378
+ )
1379
+ changes.append(change)
1344
1380
  elif func.definition_hash != actual.functions[key].definition_hash:
1345
1381
  # A changed return type or kind requires DROP + CREATE: CREATE OR
1346
1382
  # REPLACE refuses both.
@@ -1383,12 +1419,15 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1383
1419
  # Functions to drop (excluding those handled by parameter rename above)
1384
1420
  for key, func in actual.functions.items():
1385
1421
  if key not in desired.functions and key not in functions_to_drop_for_rename:
1422
+ # A contract change: the application that is serving may still
1423
+ # call it, so an expand run keeps it for the run after.
1386
1424
  changes.append(
1387
1425
  DropFunction(
1388
1426
  schema=func.schema,
1389
1427
  name=func.name,
1390
1428
  args=func.args,
1391
1429
  kind=func.kind,
1430
+ contract=True,
1392
1431
  )
1393
1432
  )
1394
1433
 
@@ -1937,6 +1976,64 @@ def _skip_canonical_function_drops(
1937
1976
  ]
1938
1977
 
1939
1978
 
1979
+ def _drop_now_what_other_drops_need(changes: list[Change], actual: Schema) -> None:
1980
+ """Make a routine drop that another drop needs a drop of this run.
1981
+
1982
+ A routine depends on the types its signature names: a dropped view's or
1983
+ domain's or range's (these drops run without CASCADE). If an expand run
1984
+ held the routine back, that other drop would fail on it. So the routine
1985
+ goes in the same run, and since the application that is serving may still
1986
+ call it, that run is offline. A routine whose definition does not even
1987
+ mention the object's name cannot depend on it; one that does may, so the
1988
+ test errs towards offline.
1989
+ """
1990
+ names: set[str] = set()
1991
+ for c in changes:
1992
+ if isinstance(c, DropView):
1993
+ names.add(c.view_name.lower())
1994
+ elif isinstance(c, DropMaterializedView):
1995
+ names.add(c.matview_name.lower())
1996
+ elif isinstance(c, (DropDomain, DropRangeType)):
1997
+ names.add(c.name.lower())
1998
+ if not names:
1999
+ return
2000
+ for c in changes:
2001
+ if not (isinstance(c, DropFunction) and c.contract):
2002
+ continue
2003
+ old = actual.functions.get(f"{c.schema}.{c.name}({c.args})")
2004
+ text = (old.full_definition if old else c.args).lower()
2005
+ needed = sorted(n for n in names if n in text)
2006
+ if needed:
2007
+ c.contract = False
2008
+ c.category = ChangeCategory.OFFLINE
2009
+ c.description += (
2010
+ f" (offline: dropped with {', '.join(needed)}, which it may "
2011
+ f"depend on, while the application may still call it)"
2012
+ )
2013
+
2014
+
2015
+ def _hold_revokes_with_their_routine(changes: list[Change]) -> None:
2016
+ """A revoke on a routine dropped as a contract change is one too.
2017
+
2018
+ Revoking the serving application's EXECUTE breaks its calls exactly as
2019
+ the drop would, so an expand run holds both back.
2020
+ """
2021
+ held = {
2022
+ (c.schema, c.name, c.args)
2023
+ for c in changes
2024
+ if isinstance(c, DropFunction) and c.contract
2025
+ }
2026
+ if not held:
2027
+ return
2028
+ for c in changes:
2029
+ if (
2030
+ isinstance(c, RevokePrivilege)
2031
+ and c.grant.object_type in ("FUNCTION", "PROCEDURE")
2032
+ and (c.grant.schema, c.grant.object_name, c.grant.args) in held
2033
+ ):
2034
+ c.contract = True
2035
+
2036
+
1940
2037
  def _drop_domains(desired: Schema, actual: Schema) -> list[Change]:
1941
2038
  """Drop domains that are no longer declared.
1942
2039
 
@@ -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 = (