pgdeclare 0.1.1__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.1 → pgdeclare-0.2.0}/CHANGELOG.md +49 -0
  2. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/PKG-INFO +2 -15
  3. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/README.md +1 -14
  4. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/pyproject.toml +1 -1
  5. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/__init__.py +8 -1
  6. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/changes.py +40 -0
  7. {pgdeclare-0.1.1 → 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.1 → pgdeclare-0.2.0}/src/pgdeclare/differ.py +127 -15
  10. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/introspection.py +34 -1
  11. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/migrate.py +59 -2
  12. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/models.py +35 -0
  13. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/prove.py +4 -0
  14. {pgdeclare-0.1.1 → 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.1 → pgdeclare-0.2.0}/tests/test_materialized_views.py +29 -0
  17. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_routines.py +20 -3
  18. pgdeclare-0.2.0/tests/test_views.py +244 -0
  19. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/.gitignore +0 -0
  20. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/LICENSE +0 -0
  21. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/NOTICE +0 -0
  22. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/__main__.py +0 -0
  23. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/config.py +0 -0
  24. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/drop_directive.py +0 -0
  25. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/executor.py +0 -0
  26. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/ledger.py +0 -0
  27. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/py.typed +0 -0
  28. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/quoting.py +0 -0
  29. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/retry_executor.py +0 -0
  30. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/schema_parser.py +0 -0
  31. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/src/pgdeclare/statement_parser.py +0 -0
  32. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/conftest.py +0 -0
  33. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/dbutil.py +0 -0
  34. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_cli.py +0 -0
  35. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_comments.py +0 -0
  36. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_default_privileges.py +0 -0
  37. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_diff.py +0 -0
  38. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_domains.py +0 -0
  39. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_foreign_data.py +0 -0
  40. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_integration.py +0 -0
  41. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_lifecycle.py +0 -0
  42. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_partitions.py +0 -0
  43. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_pipeline.py +0 -0
  44. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_prove.py +0 -0
  45. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_publications_rules.py +0 -0
  46. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_ranges_collations.py +0 -0
  47. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_retry_executor.py +0 -0
  48. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_security.py +0 -0
  49. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_sequences.py +0 -0
  50. {pgdeclare-0.1.1 → pgdeclare-0.2.0}/tests/test_statement_parser.py +0 -0
@@ -5,6 +5,54 @@ 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
+
43
+ ## [0.1.2] - 2026-10-19
44
+
45
+ ### Changed
46
+
47
+ - A view whose query changes while every existing output column keeps its
48
+ name, type and collation (new columns may be appended) is now replaced in
49
+ place with `CREATE OR REPLACE VIEW`, online, instead of dropped and
50
+ re-created. The view keeps its OID, so its grants, comments and owner stay,
51
+ and the views, materialized views and SQL functions reading from it are not
52
+ dropped and rebuilt. A materialized view reading from it keeps its data
53
+ until it is refreshed. A renamed, retyped, reordered or removed column still
54
+ drops and re-creates the view with its dependents.
55
+
8
56
  ## [0.1.1] - 2026-10-18
9
57
 
10
58
  ### Added
@@ -192,6 +240,7 @@ First real release: a schema engine proven in production, extracted and made gen
192
240
 
193
241
  Placeholder release to reserve the name on PyPI. No functionality.
194
242
 
243
+ [0.1.2]: https://github.com/powertime-org/pgdeclare/compare/v0.1.1...v0.1.2
195
244
  [0.1.1]: https://github.com/powertime-org/pgdeclare/compare/v0.1.0...v0.1.1
196
245
  [0.1.0]: https://github.com/powertime-org/pgdeclare/compare/v0.0.1...v0.1.0
197
246
  [0.0.1]: https://github.com/powertime-org/pgdeclare/releases/tag/v0.0.1
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pgdeclare
3
- Version: 0.1.1
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.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.
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
 
@@ -139,19 +139,6 @@ Every command, flag and exit code is in [docs/cli.md](https://github.com/powerti
139
139
  - [Configuration](https://github.com/powertime-org/pgdeclare/blob/main/docs/configuration.md): every `PgDeclareConfig` field.
140
140
  - [Safety](https://github.com/powertime-org/pgdeclare/blob/main/docs/safety.md): previews, `--prove`, online/offline/blocked changes, quoting, masking, and the supported PostgreSQL versions (14 to 18).
141
141
 
142
- ## How it compares
143
-
144
- As of October 2026, pgdeclare manages nearly every object kind [pg-delta](https://github.com/supabase/pg-toolbelt) and [pgschema](https://github.com/pgplex/pgschema) do; the exact differences are in [Coverage](https://github.com/powertime-org/pgdeclare/blob/main/docs/coverage.md#compared-with-other-tools). pgdeclare's difference is where the steps a diff cannot infer live: next to the DDL they belong to, run once, and recorded by hash.
145
-
146
- | Tool | Renames and backfills | Records what ran | Free licence | Notes |
147
- |------|-----------------------|------------------|--------------|-------|
148
- | pgdeclare | `@migrate` blocks beside the DDL | Hash ledger; edited blocks are refused | Apache-2.0 | Re-diffs after applying and fails the run if anything is left; `--prove` rehearses the full run, `@migrate` blocks included, on a clone |
149
- | [pgschema](https://github.com/pgplex/pgschema) | Outside the tool | No; state only | Apache-2.0 | Terraform-style plan and apply; broad object coverage |
150
- | [pg-delta](https://github.com/supabase/pg-toolbelt) | Renames come out as drop plus add, edited by hand; never writes row changes | Through Supabase migration files | PostgreSQL | Alpha; very broad coverage; `prove` tests a plan on a clone first |
151
- | [Atlas](https://atlasgo.io) | Versioned migration files | Yes, in versioned mode | Apache-2.0 Community Edition | The Community Edition omits views, functions, triggers and RLS policies; the full binary is under the Atlas MSA |
152
- | [pg-schema-diff](https://github.com/stripe/pg-schema-diff) | Renames come out as drop plus add | No | MIT | Strong lock avoidance for online changes |
153
- | [migra](https://github.com/djrobstep/migra) | Not handled | No | Unlicense | Deprecated; last release 2022 |
154
-
155
142
  ## Contributing
156
143
 
157
144
  Issues and pull requests are welcome on [GitHub](https://github.com/powertime-org/pgdeclare). See [CONTRIBUTING.md](https://github.com/powertime-org/pgdeclare/blob/main/CONTRIBUTING.md) for running the tests, and [SECURITY.md](https://github.com/powertime-org/pgdeclare/blob/main/SECURITY.md) for reporting vulnerabilities.
@@ -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.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.
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
 
@@ -106,19 +106,6 @@ Every command, flag and exit code is in [docs/cli.md](https://github.com/powerti
106
106
  - [Configuration](https://github.com/powertime-org/pgdeclare/blob/main/docs/configuration.md): every `PgDeclareConfig` field.
107
107
  - [Safety](https://github.com/powertime-org/pgdeclare/blob/main/docs/safety.md): previews, `--prove`, online/offline/blocked changes, quoting, masking, and the supported PostgreSQL versions (14 to 18).
108
108
 
109
- ## How it compares
110
-
111
- As of October 2026, pgdeclare manages nearly every object kind [pg-delta](https://github.com/supabase/pg-toolbelt) and [pgschema](https://github.com/pgplex/pgschema) do; the exact differences are in [Coverage](https://github.com/powertime-org/pgdeclare/blob/main/docs/coverage.md#compared-with-other-tools). pgdeclare's difference is where the steps a diff cannot infer live: next to the DDL they belong to, run once, and recorded by hash.
112
-
113
- | Tool | Renames and backfills | Records what ran | Free licence | Notes |
114
- |------|-----------------------|------------------|--------------|-------|
115
- | pgdeclare | `@migrate` blocks beside the DDL | Hash ledger; edited blocks are refused | Apache-2.0 | Re-diffs after applying and fails the run if anything is left; `--prove` rehearses the full run, `@migrate` blocks included, on a clone |
116
- | [pgschema](https://github.com/pgplex/pgschema) | Outside the tool | No; state only | Apache-2.0 | Terraform-style plan and apply; broad object coverage |
117
- | [pg-delta](https://github.com/supabase/pg-toolbelt) | Renames come out as drop plus add, edited by hand; never writes row changes | Through Supabase migration files | PostgreSQL | Alpha; very broad coverage; `prove` tests a plan on a clone first |
118
- | [Atlas](https://atlasgo.io) | Versioned migration files | Yes, in versioned mode | Apache-2.0 Community Edition | The Community Edition omits views, functions, triggers and RLS policies; the full binary is under the Atlas MSA |
119
- | [pg-schema-diff](https://github.com/stripe/pg-schema-diff) | Renames come out as drop plus add | No | MIT | Strong lock avoidance for online changes |
120
- | [migra](https://github.com/djrobstep/migra) | Not handled | No | Unlicense | Deprecated; last release 2022 |
121
-
122
109
  ## Contributing
123
110
 
124
111
  Issues and pull requests are welcome on [GitHub](https://github.com/powertime-org/pgdeclare). See [CONTRIBUTING.md](https://github.com/powertime-org/pgdeclare/blob/main/CONTRIBUTING.md) for running the tests, and [SECURITY.md](https://github.com/powertime-org/pgdeclare/blob/main/SECURITY.md) for reporting vulnerabilities.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pgdeclare"
7
- version = "0.1.1"
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.1"
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:
@@ -2171,6 +2176,41 @@ class CreateView(Change):
2171
2176
  )
2172
2177
 
2173
2178
 
2179
+ @dataclass
2180
+ class ReplaceView(Change):
2181
+ """Change an existing view's query in place with CREATE OR REPLACE VIEW.
2182
+
2183
+ The path for a definition change that keeps every existing output column
2184
+ (same names, types and collations, in order; new ones may only be
2185
+ appended). The view keeps its OID, so its ACL, comments, owner and the
2186
+ views, materialized views and SQL functions reading from it all stay as
2187
+ they are: nothing is dropped, so nothing needs rebuilding.
2188
+ """
2189
+
2190
+ view: View = field(
2191
+ default_factory=lambda: View(schema="public", name="", definition="")
2192
+ )
2193
+ category: ChangeCategory = ChangeCategory.ONLINE
2194
+ description: str = ""
2195
+ object_type: str = "VIEW"
2196
+
2197
+ def __post_init__(self):
2198
+ self.object_name = self.view.qualified_name
2199
+ if not self.description:
2200
+ self.description = f"Replace view {self.view.name}" + view_options_note(
2201
+ self.view
2202
+ )
2203
+
2204
+ def to_sql(self) -> str:
2205
+ # CREATE OR REPLACE VIEW replaces the reloptions with the WITH clause
2206
+ # (none clears them), so the declared options converge in the same
2207
+ # statement.
2208
+ return (
2209
+ f"CREATE OR REPLACE VIEW {quote_ident(self.view.schema)}.{quote_ident(self.view.name)}"
2210
+ f"{self.view.options_clause} AS {self.view.definition}"
2211
+ )
2212
+
2213
+
2174
2214
  @dataclass
2175
2215
  class DropView(Change):
2176
2216
  """Drop a view."""
@@ -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
@@ -111,6 +111,7 @@ from .changes import (
111
111
  RevokePublicExecute,
112
112
  ReplacePublicationTable,
113
113
  RevokeRoleMembership,
114
+ ReplaceView,
114
115
  SetComment,
115
116
  SetDefault,
116
117
  SetSequenceOwner,
@@ -276,6 +277,8 @@ def compute_diff(
276
277
  changes.extend(default_privilege_grants)
277
278
  changes = _skip_revokes_on_dropped_relations(changes)
278
279
  changes = _skip_canonical_function_drops(changes, actual)
280
+ _drop_now_what_other_drops_need(changes, actual)
281
+ _hold_revokes_with_their_routine(changes)
279
282
 
280
283
  # Re-apply grants for objects being dropped and recreated.
281
284
  #
@@ -642,6 +645,7 @@ def _carry_recreate_dependents(
642
645
  (
643
646
  AlterViewOptions,
644
647
  AlterMaterializedViewOptions,
648
+ ReplaceView,
645
649
  ),
646
650
  )
647
651
  and c.object_name in folded
@@ -1299,6 +1303,11 @@ def _diff_constraints(
1299
1303
  return changes
1300
1304
 
1301
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
+
1302
1311
  def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1303
1312
  """Diff functions between desired and actual schemas."""
1304
1313
  changes: list[Change] = []
@@ -1326,19 +1335,44 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1326
1335
  rename_source = existing
1327
1336
  break
1328
1337
 
1329
- if rename_source:
1330
- # Parameter names changed - use DropAndCreateFunction with the OLD args
1331
- # 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.
1332
1359
  functions_to_drop_for_rename.add(rename_source.signature)
1333
- changes.append(
1334
- DropAndCreateFunction(
1335
- function=func,
1336
- old_args=rename_source.args, # Pass old args for correct DROP
1337
- old_kind=rename_source.kind,
1338
- )
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,
1339
1365
  )
1340
- else:
1341
- 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)
1342
1376
  elif func.definition_hash != actual.functions[key].definition_hash:
1343
1377
  # A changed return type or kind requires DROP + CREATE: CREATE OR
1344
1378
  # REPLACE refuses both.
@@ -1381,12 +1415,15 @@ def _diff_functions(desired: Schema, actual: Schema) -> list[Change]:
1381
1415
  # Functions to drop (excluding those handled by parameter rename above)
1382
1416
  for key, func in actual.functions.items():
1383
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.
1384
1420
  changes.append(
1385
1421
  DropFunction(
1386
1422
  schema=func.schema,
1387
1423
  name=func.name,
1388
1424
  args=func.args,
1389
1425
  kind=func.kind,
1426
+ contract=True,
1390
1427
  )
1391
1428
  )
1392
1429
 
@@ -1935,6 +1972,64 @@ def _skip_canonical_function_drops(
1935
1972
  ]
1936
1973
 
1937
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
+
1938
2033
  def _drop_domains(desired: Schema, actual: Schema) -> list[Change]:
1939
2034
  """Drop domains that are no longer declared.
1940
2035
 
@@ -1958,10 +2053,15 @@ def _diff_views(desired: Schema, actual: Schema) -> list[Change]:
1958
2053
  if key not in actual.views:
1959
2054
  changes.append(CreateView(view=view))
1960
2055
  elif view.definition.strip() != actual.views[key].definition.strip():
1961
- # Use DropAndCreateView to handle column order/type changes
1962
- # that CREATE OR REPLACE VIEW can't handle. The recreate carries the
1963
- # declared WITH (...) options itself.
1964
- changes.append(DropAndCreateView(view=view))
2056
+ if _view_replaceable(actual.views[key], view):
2057
+ # Same leading columns: replace in place, so the view keeps its
2058
+ # ACL and the relations reading from it are left alone.
2059
+ changes.append(ReplaceView(view=view))
2060
+ else:
2061
+ # A column renamed, retyped, reordered or removed: CREATE OR
2062
+ # REPLACE VIEW refuses those, so drop and recreate. The
2063
+ # recreate carries the declared WITH (...) options itself.
2064
+ changes.append(DropAndCreateView(view=view))
1965
2065
  elif view.reloptions != actual.views[key].reloptions:
1966
2066
  # Definition already matches, only the security mode drifted (say,
1967
2067
  # `security_invoker` was declared but never written). ALTER VIEW
@@ -1981,6 +2081,18 @@ def _diff_views(desired: Schema, actual: Schema) -> list[Change]:
1981
2081
  return changes
1982
2082
 
1983
2083
 
2084
+ def _view_replaceable(current: View, declared: View) -> bool:
2085
+ """Whether CREATE OR REPLACE VIEW can turn `current` into `declared`.
2086
+
2087
+ PostgreSQL accepts it when the new query keeps every existing output
2088
+ column with the same name, type and collation, in the same position, and
2089
+ only appends new ones. Unknown columns (an empty list) never qualify.
2090
+ """
2091
+ if not current.columns or not declared.columns:
2092
+ return False
2093
+ return declared.columns[: len(current.columns)] == current.columns
2094
+
2095
+
1984
2096
  def _diff_materialized_views(desired: Schema, actual: Schema) -> list[Change]:
1985
2097
  """Diff materialized views between desired and actual schemas.
1986
2098