pgdeclare 0.2.2__tar.gz → 0.3.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.2.2 → pgdeclare-0.3.0}/CHANGELOG.md +29 -0
  2. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/PKG-INFO +2 -2
  3. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/README.md +1 -1
  4. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/pyproject.toml +1 -1
  5. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/__init__.py +1 -1
  6. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/changes.py +16 -3
  7. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/cli.py +4 -3
  8. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/differ.py +234 -10
  9. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/executor.py +28 -3
  10. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_boundary.py +1 -1
  11. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_diff.py +15 -11
  12. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_expand_contract.py +296 -7
  13. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/.gitignore +0 -0
  14. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/LICENSE +0 -0
  15. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/NOTICE +0 -0
  16. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/__main__.py +0 -0
  17. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/config.py +0 -0
  18. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/contract.py +0 -0
  19. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/drop_directive.py +0 -0
  20. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/introspection.py +0 -0
  21. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/ledger.py +0 -0
  22. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/migrate.py +0 -0
  23. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/models.py +0 -0
  24. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/prove.py +0 -0
  25. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/py.typed +0 -0
  26. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/quoting.py +0 -0
  27. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/retry_executor.py +0 -0
  28. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/schema_parser.py +0 -0
  29. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/src/pgdeclare/statement_parser.py +0 -0
  30. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/conftest.py +0 -0
  31. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/dbutil.py +0 -0
  32. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_cli.py +0 -0
  33. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_comments.py +0 -0
  34. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_default_privileges.py +0 -0
  35. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_domains.py +0 -0
  36. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_foreign_data.py +0 -0
  37. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_integration.py +0 -0
  38. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_lifecycle.py +0 -0
  39. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_materialized_views.py +0 -0
  40. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_partitions.py +0 -0
  41. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_pipeline.py +0 -0
  42. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_prove.py +0 -0
  43. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_publications_rules.py +0 -0
  44. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_ranges_collations.py +0 -0
  45. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_retry_executor.py +0 -0
  46. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_routines.py +0 -0
  47. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_security.py +0 -0
  48. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_sequences.py +0 -0
  49. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_statement_parser.py +0 -0
  50. {pgdeclare-0.2.2 → pgdeclare-0.3.0}/tests/test_views.py +0 -0
@@ -5,6 +5,35 @@ 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.3.0] - 2026-11-19
9
+
10
+ ### Changed
11
+
12
+ - Expand/contract covers what a query reads, not only routines. Dropping an
13
+ undeclared view, materialized view, sequence or foreign table, and revoking
14
+ a privilege on a table, view, column, sequence or schema, is now a
15
+ contract change: `apply --expand-only` holds it back, so the version still
16
+ serving keeps reading the relation, calling `nextval()` and running with
17
+ its privileges until the run after it has stopped.
18
+ - A relation drop that cannot wait goes in the same run, offline: when the
19
+ schema files declare another relation under its name, when a view it reads
20
+ from is recreated in the run, or when its query names what the run drops,
21
+ recreates or retypes (and what depends on such a drop goes with it). A
22
+ routine and the view whose row type it returns now wait together instead of
23
+ both going offline.
24
+ - A table-level revoke grants the declared column-level grants of the same
25
+ privilege back in the same statement (`RevokePrivilege.regrant_columns`), and
26
+ those grants leave the plan as separate changes. The contract run's revoke
27
+ would otherwise strip the column grants the expand run wrote, and the run
28
+ after a table-wide grant narrowed to some columns no longer depends on the
29
+ revoke running first.
30
+
31
+ ### Fixed
32
+
33
+ - A relation declared under the name of an undeclared relation of another
34
+ kind (a view becoming a table) no longer fails `relation already exists`:
35
+ the create is retried once the old relation is dropped.
36
+
8
37
  ## [0.2.2] - 2026-11-19
9
38
 
10
39
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pgdeclare
3
- Version: 0.2.2
3
+ Version: 0.3.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.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.
50
+ Status: **0.3.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.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.
17
+ Status: **0.3.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.2.2"
7
+ version = "0.3.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.2.2"
20
+ __version__ = "0.3.0"
21
21
 
22
22
  from .config import DEFAULT_CONFIG, PgDeclareConfig
23
23
  from .models import (
@@ -88,8 +88,10 @@ class Change(ABC):
88
88
  object_type: str = ""
89
89
  object_name: str = ""
90
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
91
+ # version of the application may still depend on while it serves:
92
+ # dropping a routine it may still call, or a view, materialized view,
93
+ # sequence or foreign table it may still read, or revoking a privilege on
94
+ # one of those, a table, column or schema. A run with `expand_only` holds
93
95
  # it back; the run after the old version has stopped applies it.
94
96
  contract: bool = False
95
97
 
@@ -2621,6 +2623,11 @@ class RevokePrivilege(Change):
2621
2623
  description: str = ""
2622
2624
  object_type: str = "REVOKE"
2623
2625
 
2626
+ # A table-level revoke strips the column-level grants of the same
2627
+ # privilege and grantee; the declared ones are granted again in the same
2628
+ # statement, so no run, held back or not, can leave them stripped.
2629
+ regrant_columns: list[Grant] = field(default_factory=list)
2630
+
2624
2631
  def __post_init__(self):
2625
2632
  self.object_name = self.grant.key
2626
2633
  if not self.description:
@@ -2652,7 +2659,13 @@ class RevokePrivilege(Change):
2652
2659
  f"BEGIN {revoke_sql}; EXCEPTION WHEN undefined_table THEN NULL; END"
2653
2660
  )
2654
2661
  else:
2655
- return f"REVOKE {self.grant.privilege} ON {quote_ident(self.grant.schema)}.{quote_ident(self.grant.object_name)} FROM {role_ident(self.grant.grantee)};"
2662
+ revoke_sql = f"REVOKE {self.grant.privilege} ON {quote_ident(self.grant.schema)}.{quote_ident(self.grant.object_name)} FROM {role_ident(self.grant.grantee)}"
2663
+ if not self.regrant_columns:
2664
+ return f"{revoke_sql};"
2665
+ regrants = " ".join(
2666
+ GrantPrivilege(grant=g).to_sql() for g in self.regrant_columns
2667
+ )
2668
+ return do_block(f"BEGIN {revoke_sql}; {regrants} END")
2656
2669
 
2657
2670
 
2658
2671
  @dataclass
@@ -464,9 +464,10 @@ def build_parser() -> argparse.ArgumentParser:
464
464
  apply.add_argument(
465
465
  "--expand-only",
466
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",
467
+ help="the expand half of an expand/contract deploy: keep what the "
468
+ "running application may still use (routines dropped or replaced by a "
469
+ "new signature, views, materialized views, sequences and foreign tables "
470
+ "dropped, privileges revoked) for a later run without this flag",
470
471
  )
471
472
  apply.add_argument(
472
473
  "--prove",
@@ -6,6 +6,7 @@ a list of Change objects needed to synchronize them.
6
6
  """
7
7
 
8
8
  from dataclasses import replace as dataclass_replace
9
+ import re
9
10
  from typing import Any, Callable, Optional, Union
10
11
 
11
12
  from .changes import (
@@ -277,7 +278,14 @@ def compute_diff(
277
278
  changes.extend(default_privilege_grants)
278
279
  changes = _skip_revokes_on_dropped_relations(changes)
279
280
  changes = _skip_canonical_function_drops(changes, actual)
280
- _drop_now_what_other_drops_need(changes, actual)
281
+ _hold_relation_drops(changes)
282
+ changes = _hold_relation_revokes(changes, desired)
283
+ # Whether a relation drop can wait depends on which routine drops go now,
284
+ # and the other way round, so settle both together.
285
+ while _drop_now_what_relations_need(
286
+ changes, desired, actual
287
+ ) | _drop_now_what_other_drops_need(changes, actual):
288
+ pass
281
289
  _hold_revokes_with_their_routine(changes)
282
290
 
283
291
  # Re-apply grants for objects being dropped and recreated.
@@ -2020,27 +2028,31 @@ def _skip_canonical_function_drops(
2020
2028
  ]
2021
2029
 
2022
2030
 
2023
- def _drop_now_what_other_drops_need(changes: list[Change], actual: Schema) -> None:
2031
+ def _drop_now_what_other_drops_need(changes: list[Change], actual: Schema) -> bool:
2024
2032
  """Make a routine drop that another drop needs a drop of this run.
2025
2033
 
2026
2034
  A routine depends on the types its signature names: a dropped view's or
2027
2035
  domain's or range's (these drops run without CASCADE). If an expand run
2028
- held the routine back, that other drop would fail on it. So the routine
2029
- goes in the same run, and since the application that is serving may still
2030
- call it, that run is offline. A routine whose definition does not even
2031
- mention the object's name cannot depend on it; one that does may, so the
2032
- test errs towards offline.
2036
+ held the routine back while the other drop went now, that drop would fail
2037
+ on it. So the routine goes in the same run, and since the application that
2038
+ is serving may still call it, that run is offline. A routine whose
2039
+ definition does not even mention the object's name cannot depend on it;
2040
+ one that does may, so the test errs towards offline. A view held back as a
2041
+ contract change waits with the routine, so it forces nothing.
2042
+
2043
+ Returns whether it moved a routine drop to this run.
2033
2044
  """
2034
2045
  names: set[str] = set()
2035
2046
  for c in changes:
2036
- if isinstance(c, DropView):
2047
+ if isinstance(c, DropView) and not c.contract:
2037
2048
  names.add(c.view_name.lower())
2038
- elif isinstance(c, DropMaterializedView):
2049
+ elif isinstance(c, DropMaterializedView) and not c.contract:
2039
2050
  names.add(c.matview_name.lower())
2040
2051
  elif isinstance(c, (DropDomain, DropRangeType)):
2041
2052
  names.add(c.name.lower())
2042
2053
  if not names:
2043
- return
2054
+ return False
2055
+ moved = False
2044
2056
  for c in changes:
2045
2057
  if not (isinstance(c, DropFunction) and c.contract):
2046
2058
  continue
@@ -2054,6 +2066,218 @@ def _drop_now_what_other_drops_need(changes: list[Change], actual: Schema) -> No
2054
2066
  f" (offline: dropped with {', '.join(needed)}, which it may "
2055
2067
  f"depend on, while the application may still call it)"
2056
2068
  )
2069
+ moved = True
2070
+ return moved
2071
+
2072
+
2073
+ # Drops of relations a query names. The application that is serving may still
2074
+ # read them, so an expand run holds them back for the run after.
2075
+ _RelationDrop = Union[DropView, DropMaterializedView, DropSequence, DropForeignTable]
2076
+
2077
+
2078
+ def _relation_drop_name(c: _RelationDrop) -> str:
2079
+ if isinstance(c, DropView):
2080
+ return c.view_name
2081
+ if isinstance(c, DropMaterializedView):
2082
+ return c.matview_name
2083
+ if isinstance(c, DropSequence):
2084
+ return c.sequence_name
2085
+ return c.table_name
2086
+
2087
+
2088
+ def _hold_relation_drops(changes: list[Change]) -> None:
2089
+ """A view, materialized view, sequence or foreign table no longer declared
2090
+ is dropped as a contract change.
2091
+
2092
+ The application that is serving may still read the relation or call
2093
+ nextval() on the sequence; dropping it breaks every such query until the
2094
+ new version takes over. `_drop_now_what_relations_need` then moves back to
2095
+ this run, offline, each drop that cannot wait.
2096
+ """
2097
+ for c in changes:
2098
+ if (
2099
+ isinstance(
2100
+ c, (DropView, DropMaterializedView, DropSequence, DropForeignTable)
2101
+ )
2102
+ and c.category == ChangeCategory.ONLINE
2103
+ ):
2104
+ c.contract = True
2105
+
2106
+
2107
+ def _mentions(text: str, name: str) -> bool:
2108
+ return (
2109
+ re.search(rf"(?<![\w$]){re.escape(name)}(?![\w$])", text, re.IGNORECASE)
2110
+ is not None
2111
+ )
2112
+
2113
+
2114
+ def _names_taken_now(changes: list[Change]) -> set[str]:
2115
+ """Names of what this run drops, recreates or retypes, as a query names them.
2116
+
2117
+ A view reading one of them holds a dependency that makes the change fail
2118
+ (DROP and ALTER COLUMN TYPE refuse while a view uses the object) or, for a
2119
+ routine re-created with CASCADE, takes the view along.
2120
+ """
2121
+ names: set[str] = set()
2122
+ for c in changes:
2123
+ if c.contract:
2124
+ continue
2125
+ if isinstance(c, (DropView, DropMaterializedView, DropForeignTable)):
2126
+ names.add(_relation_drop_name(c))
2127
+ elif isinstance(c, DropTable):
2128
+ names.add(c.table_name)
2129
+ elif isinstance(c, (DropColumn, AlterColumnType)):
2130
+ names.add(c.table)
2131
+ elif isinstance(c, (DropFunction, DropDomain, DropRangeType)):
2132
+ names.add(c.name)
2133
+ elif isinstance(c, DropAndCreateFunction):
2134
+ names.add(c.function.name)
2135
+ elif isinstance(c, DropAndCreateDomain):
2136
+ names.add(c.domain.name)
2137
+ elif isinstance(c, DropAndCreateRangeType):
2138
+ names.add(c.range_type.name)
2139
+ elif isinstance(c, DropAndCreateForeignTable):
2140
+ names.add(c.table.name)
2141
+ return {n.lower() for n in names}
2142
+
2143
+
2144
+ def _declared_relation_names(desired: Schema) -> set[str]:
2145
+ """`schema.name` of every declared object that lives in pg_class."""
2146
+ found: set[str] = set()
2147
+ for objects in (
2148
+ desired.tables,
2149
+ desired.views,
2150
+ desired.materialized_views,
2151
+ desired.sequences,
2152
+ desired.foreign_tables,
2153
+ desired.composite_types,
2154
+ desired.indexes,
2155
+ ):
2156
+ for obj in objects.values():
2157
+ found.add(f"{obj.schema}.{obj.name}")
2158
+ return found
2159
+
2160
+
2161
+ def _drop_now_what_relations_need(
2162
+ changes: list[Change], desired: Schema, actual: Schema
2163
+ ) -> bool:
2164
+ """Move a held-back relation drop to this run, offline, when it cannot wait.
2165
+
2166
+ It cannot wait when:
2167
+
2168
+ - the schema files declare another relation under its name, which this
2169
+ run creates and which would collide with it;
2170
+ - this run drops and recreates a view or materialized view it reads from,
2171
+ directly or not: the recreate drops it on the way;
2172
+ - it is a view or materialized view whose query names what this run
2173
+ drops, recreates or retypes (or what another drop moved to this run
2174
+ reads from): that change fails on it, or takes it along. Like the
2175
+ routine rule, a name in the query errs towards offline.
2176
+
2177
+ Each one then goes now, and the serving application may still read it,
2178
+ so the run is offline. Returns whether it moved any.
2179
+ """
2180
+ held = [
2181
+ c
2182
+ for c in changes
2183
+ if isinstance(
2184
+ c, (DropView, DropMaterializedView, DropSequence, DropForeignTable)
2185
+ )
2186
+ and c.contract
2187
+ ]
2188
+ if not held:
2189
+ return False
2190
+ declared = _declared_relation_names(desired)
2191
+ taken = _names_taken_now(changes)
2192
+ recreated_dependents: set[str] = set()
2193
+ for c in changes:
2194
+ if isinstance(c, DropAndCreateView):
2195
+ root = c.view.qualified_name
2196
+ elif isinstance(c, DropAndCreateMaterializedView):
2197
+ root = c.matview.qualified_name
2198
+ else:
2199
+ continue
2200
+ recreated_dependents.update(
2201
+ _relation_dependent_order(root, actual.relation_dependents)
2202
+ )
2203
+
2204
+ moved = False
2205
+ for c in held:
2206
+ name = _relation_drop_name(c)
2207
+ qualified = f"{c.schema}.{name}"
2208
+ reason = ""
2209
+ if qualified in declared:
2210
+ reason = f"{qualified} is declared again as another kind of relation"
2211
+ elif qualified in recreated_dependents:
2212
+ reason = "a view it reads from is recreated in this run"
2213
+ elif isinstance(c, (DropView, DropMaterializedView)):
2214
+ relation = actual.views.get(qualified) or actual.materialized_views.get(
2215
+ qualified
2216
+ )
2217
+ definition = relation.definition if relation is not None else ""
2218
+ needed = sorted(n for n in taken if _mentions(definition, n))
2219
+ if needed:
2220
+ reason = (
2221
+ f"it reads {', '.join(needed)}, which this run drops or changes"
2222
+ )
2223
+ if reason:
2224
+ c.contract = False
2225
+ c.category = ChangeCategory.OFFLINE
2226
+ c.description += (
2227
+ f" (offline: {reason}, while the application may still read it)"
2228
+ )
2229
+ moved = True
2230
+ return moved
2231
+
2232
+
2233
+ # Grants on these are what the serving application's queries run on.
2234
+ _HELD_REVOKE_OBJECTS = frozenset({"TABLE", "COLUMN", "SEQUENCE", "SCHEMA"})
2235
+
2236
+
2237
+ def _hold_relation_revokes(changes: list[Change], desired: Schema) -> list[Change]:
2238
+ """A revoke on a table, view, column, sequence or schema is a contract change.
2239
+
2240
+ The serving application's queries fail without the privilege exactly as
2241
+ they would without the object. A table-level REVOKE also strips every
2242
+ column-level grant of that privilege on the table, so the revoke grants
2243
+ the declared ones again in the same statement, and their own GRANTs leave
2244
+ the plan: while the table-wide grant stands they add nothing (and the
2245
+ catalog reports them as part of it), and once it goes they come back with
2246
+ the revoke, in whichever run that is.
2247
+ """
2248
+ folded: set[str] = set()
2249
+ for c in changes:
2250
+ if (
2251
+ isinstance(c, RevokePrivilege)
2252
+ and c.grant.object_type in _HELD_REVOKE_OBJECTS
2253
+ ):
2254
+ c.contract = True
2255
+ if c.grant.object_type == "TABLE" and not c.grant.column:
2256
+ c.regrant_columns = sorted(
2257
+ (
2258
+ g
2259
+ for g in desired.grants
2260
+ if g.column
2261
+ and g.schema == c.grant.schema
2262
+ and g.object_name == c.grant.object_name
2263
+ and g.privilege == c.grant.privilege
2264
+ and g.grantee == c.grant.grantee
2265
+ ),
2266
+ key=lambda g: g.key,
2267
+ )
2268
+ folded.update(g.key for g in c.regrant_columns)
2269
+ if c.regrant_columns:
2270
+ c.description += (
2271
+ f" (re-granting it on {len(c.regrant_columns)} "
2272
+ f"declared column(s), which the revoke strips)"
2273
+ )
2274
+ if not folded:
2275
+ return changes
2276
+ return [
2277
+ c
2278
+ for c in changes
2279
+ if not (isinstance(c, GrantPrivilege) and c.grant.key in folded)
2280
+ ]
2057
2281
 
2058
2282
 
2059
2283
  def _hold_revokes_with_their_routine(changes: list[Change]) -> None:
@@ -27,9 +27,14 @@ from .changes import (
27
27
  AlterOwner,
28
28
  Change,
29
29
  CreateEnum,
30
+ CreateForeignTable,
30
31
  CreateIndex,
32
+ CreateMaterializedView,
31
33
  CreatePartitionedIndex,
32
34
  CreateRole,
35
+ CreateSequence,
36
+ CreateTable,
37
+ CreateView,
33
38
  SetComment,
34
39
  DropCollation,
35
40
  DropDomain,
@@ -72,6 +77,19 @@ RETRY_WHILE_DEPENDED_ON = (
72
77
  DropForeignTable,
73
78
  )
74
79
 
80
+ # duplicate_table. Retryable for the creates of a relation: a relation of
81
+ # another kind that held the name (a view declared again as a table, say) is
82
+ # dropped by another change in the same run, which the differ orders after the
83
+ # create, and the create succeeds once it has.
84
+ DUPLICATE_RELATION_ERROR_CODE = "42P07"
85
+ RETRY_WHILE_NAME_TAKEN = (
86
+ CreateTable,
87
+ CreateView,
88
+ CreateMaterializedView,
89
+ CreateSequence,
90
+ CreateForeignTable,
91
+ )
92
+
75
93
  # Changes run in the final phase, after the DDL and index phases: comments, and
76
94
  # owners (a recreate in the DDL phase resets an object's owner).
77
95
  FINAL_PHASE_CHANGE_TYPES = (SetComment, AlterOwner)
@@ -414,9 +432,16 @@ def _execute_with_retry_savepoints(
414
432
  continue
415
433
 
416
434
  # Check if this is a dependency error (retryable)
417
- if error_code in DEPENDENCY_ERROR_CODES or (
418
- error_code == DEPENDENT_OBJECTS_ERROR_CODE
419
- and isinstance(change, RETRY_WHILE_DEPENDED_ON)
435
+ if (
436
+ error_code in DEPENDENCY_ERROR_CODES
437
+ or (
438
+ error_code == DEPENDENT_OBJECTS_ERROR_CODE
439
+ and isinstance(change, RETRY_WHILE_DEPENDED_ON)
440
+ )
441
+ or (
442
+ error_code == DUPLICATE_RELATION_ERROR_CODE
443
+ and isinstance(change, RETRY_WHILE_NAME_TAKEN)
444
+ )
420
445
  ):
421
446
  # Defer for retry
422
447
  deferred.append(
@@ -114,4 +114,4 @@ def test_the_default_config_is_neutral():
114
114
  def test_the_public_api_is_exported():
115
115
  for name in pgdeclare.__all__:
116
116
  assert hasattr(pgdeclare, name), name
117
- assert pgdeclare.__version__ == "0.2.2"
117
+ assert pgdeclare.__version__ == "0.3.0"
@@ -1933,13 +1933,13 @@ class TestGrantChanges:
1933
1933
  assert "REVOKE DELETE" in sql
1934
1934
  assert "FROM app_user" in sql
1935
1935
 
1936
- def test_table_revoke_precedes_column_grants(self):
1937
- """Table-wide INSERT narrowed to per-column INSERT revokes first.
1936
+ def test_table_revoke_grants_the_columns_back_in_one_statement(self):
1937
+ """Table-wide INSERT narrowed to per-column INSERT is one statement.
1938
1938
 
1939
1939
  PostgreSQL's table-level REVOKE also removes the column-level grants of
1940
- the same privilege, so emitting the column GRANTs before the table
1941
- REVOKE would wipe them and the run would never converge. The executor
1942
- runs changes in list order.
1940
+ the same privilege, so a column GRANT run before it would be wiped and
1941
+ the run would never converge. The revoke therefore grants the declared
1942
+ columns again itself, after revoking, whichever run applies it.
1943
1943
  """
1944
1944
 
1945
1945
  def g(column=None):
@@ -1961,13 +1961,17 @@ class TestGrantChanges:
1961
1961
  if isinstance(c, (GrantPrivilege, RevokePrivilege))
1962
1962
  ]
1963
1963
 
1964
- assert [type(c) for c in changes] == [
1965
- RevokePrivilege,
1966
- GrantPrivilege,
1967
- GrantPrivilege,
1968
- GrantPrivilege,
1964
+ assert [type(c) for c in changes] == [RevokePrivilege]
1965
+ revoke = changes[0]
1966
+ assert isinstance(revoke, RevokePrivilege)
1967
+ assert revoke.grant.column is None
1968
+ assert [r.column for r in revoke.regrant_columns] == [
1969
+ "as_owner",
1970
+ "note",
1971
+ "team_id",
1969
1972
  ]
1970
- assert changes[0].grant.column is None
1973
+ sql = revoke.to_sql()
1974
+ assert sql.index("REVOKE INSERT") < sql.index('GRANT INSERT ("as_owner")')
1971
1975
 
1972
1976
 
1973
1977
  class TestFunctionPublicExecute:
@@ -27,15 +27,33 @@ from pgdeclare import (
27
27
  compute_diff,
28
28
  )
29
29
  from pgdeclare.changes import (
30
+ AlterColumnType,
30
31
  CreateFunction,
31
32
  DropAndCreateFunction,
33
+ DropAndCreateView,
34
+ DropDomain,
35
+ DropForeignTable,
32
36
  DropFunction,
37
+ DropMaterializedView,
38
+ DropSequence,
33
39
  DropView,
34
40
  RevokePrivilege,
35
41
  )
36
42
  from pgdeclare.ledger import MigrationBlock
37
43
  from pgdeclare.migrate import is_held_back
38
- from pgdeclare.models import ChangeCategory, Function, Grant, Schema, View
44
+ from pgdeclare.models import (
45
+ ChangeCategory,
46
+ Column,
47
+ Domain,
48
+ ForeignTable,
49
+ Function,
50
+ Grant,
51
+ MaterializedView,
52
+ Schema,
53
+ Sequence,
54
+ Table,
55
+ View,
56
+ )
39
57
 
40
58
 
41
59
  def _fn(
@@ -172,19 +190,196 @@ class TestDroppedRoutines:
172
190
  assert len(revokes) == 1 and is_held_back(revokes[0])
173
191
 
174
192
  def test_a_routine_another_drop_needs_goes_now_and_offline(self):
175
- # DROP VIEW runs without CASCADE, so it would fail on a function
176
- # returning its row type that an expand run had held back.
193
+ # DROP DOMAIN runs without CASCADE, so it would fail on a function
194
+ # taking the domain that an expand run had held back.
195
+ domain = Domain(schema="public", name="cents", base_type="integer")
196
+ gone = _fn("gone", "a cents", "cents", 1, 1)
197
+ kept = _fn("kept", "", "", 0, 0)
198
+ changes = compute_diff(
199
+ _schema(kept), _schema(gone, kept, domains={"public.cents": domain})
200
+ )
201
+ assert any(isinstance(c, DropDomain) for c in changes)
202
+ drop = next(c for c in changes if isinstance(c, DropFunction))
203
+ assert drop.category == ChangeCategory.OFFLINE
204
+ assert not drop.contract
205
+ assert "cents" in drop.description
206
+
207
+ def test_a_routine_and_the_view_it_returns_wait_together(self):
177
208
  view = View(schema="public", name="report", definition="SELECT 1 AS x")
178
209
  gone = _fn("gone", "", "", 0, 0, body="RETURNS SETOF report")
179
210
  kept = _fn("kept", "", "", 0, 0)
180
211
  changes = compute_diff(
181
212
  _schema(kept), _schema(gone, kept, views={"public.report": view})
182
213
  )
183
- assert any(isinstance(c, DropView) for c in changes)
184
- drop = next(c for c in changes if isinstance(c, DropFunction))
214
+ drops = [c for c in changes if isinstance(c, (DropView, DropFunction))]
215
+ assert len(drops) == 2 and all(is_held_back(c) for c in drops)
216
+
217
+
218
+ def _view(name: str, definition: str) -> View:
219
+ return View(schema="public", name=name, definition=definition)
220
+
221
+
222
+ def _table(name: str, **columns: str) -> Table:
223
+ return Table(
224
+ schema="public",
225
+ name=name,
226
+ columns={c: Column(c, t, True) for c, t in columns.items()},
227
+ )
228
+
229
+
230
+ class TestDroppedRelations:
231
+ """Views, materialized views, sequences and foreign tables a query names."""
232
+
233
+ def test_undeclared_relations_are_contract_drops(self):
234
+ actual = Schema(
235
+ views={"public.v": _view("v", "SELECT 1 AS x")},
236
+ materialized_views={
237
+ "public.m": MaterializedView("public", "m", "SELECT 1 AS x")
238
+ },
239
+ sequences={"public.s": Sequence("public", "s")},
240
+ foreign_tables={
241
+ "public.f": ForeignTable("public", "f", server="remote", columns={})
242
+ },
243
+ )
244
+ changes = compute_diff(Schema(), actual)
245
+ drops = {
246
+ type(c): c
247
+ for c in changes
248
+ if isinstance(
249
+ c, (DropView, DropMaterializedView, DropSequence, DropForeignTable)
250
+ )
251
+ }
252
+ assert set(drops) == {
253
+ DropView,
254
+ DropMaterializedView,
255
+ DropSequence,
256
+ DropForeignTable,
257
+ }
258
+ assert all(c.category == ChangeCategory.ONLINE for c in drops.values())
259
+ assert all(is_held_back(c) for c in drops.values())
260
+
261
+ def test_a_name_declared_again_as_a_table_cannot_wait(self):
262
+ # CREATE TABLE v would collide with the view an expand run kept.
263
+ actual = Schema(views={"public.v": _view("v", "SELECT 1 AS x")})
264
+ desired = Schema(tables={"public.v": _table("v", x="integer")})
265
+ drop = next(c for c in compute_diff(desired, actual) if isinstance(c, DropView))
185
266
  assert drop.category == ChangeCategory.OFFLINE
186
- assert not drop.contract
187
- assert "report" in drop.description
267
+ assert not drop.contract and not is_held_back(drop)
268
+ assert "declared again" in drop.description
269
+
270
+ def test_a_view_reading_a_retyped_column_cannot_wait(self):
271
+ # ALTER COLUMN TYPE refuses while a view uses the column.
272
+ actual = Schema(
273
+ tables={"public.t": _table("t", a="integer")},
274
+ views={"public.v": _view("v", " SELECT t.a\n FROM t;")},
275
+ )
276
+ desired = Schema(tables={"public.t": _table("t", a="bigint")})
277
+ changes = compute_diff(desired, actual)
278
+ assert any(isinstance(c, AlterColumnType) for c in changes)
279
+ drop = next(c for c in changes if isinstance(c, DropView))
280
+ assert drop.category == ChangeCategory.OFFLINE
281
+ assert "it reads t" in drop.description
282
+
283
+ def test_a_view_reading_another_table_waits(self):
284
+ actual = Schema(
285
+ tables={
286
+ "public.t": _table("t", a="integer"),
287
+ "public.tt": _table("tt", a="integer"),
288
+ },
289
+ views={"public.v": _view("v", " SELECT tt.a\n FROM tt;")},
290
+ )
291
+ desired = Schema(
292
+ tables={
293
+ "public.t": _table("t", a="bigint"),
294
+ "public.tt": _table("tt", a="integer"),
295
+ }
296
+ )
297
+ drop = next(c for c in compute_diff(desired, actual) if isinstance(c, DropView))
298
+ assert is_held_back(drop)
299
+
300
+ def test_a_view_on_a_recreated_view_cannot_wait(self):
301
+ # The recreate drops what reads from it on the way.
302
+ base = View("public", "base", "SELECT 1 AS x", columns=["x integer"])
303
+ actual = Schema(
304
+ views={
305
+ "public.base": base,
306
+ "public.top": _view("top", "SELECT x FROM base"),
307
+ },
308
+ relation_dependents={"public.base": ["public.top"]},
309
+ )
310
+ desired = Schema(
311
+ views={
312
+ "public.base": View(
313
+ "public", "base", "SELECT 'a'::text AS y", columns=["y text"]
314
+ )
315
+ }
316
+ )
317
+ changes = compute_diff(desired, actual)
318
+ assert any(isinstance(c, DropAndCreateView) for c in changes)
319
+ drop = next(c for c in changes if isinstance(c, DropView))
320
+ assert drop.category == ChangeCategory.OFFLINE
321
+ assert "recreated" in drop.description
322
+ assert not any(is_held_back(c) for c in changes)
323
+
324
+ def test_dependents_of_a_view_that_goes_now_go_too(self):
325
+ # `low` collides with a new table, so it goes now; `high` reads it,
326
+ # and DROP VIEW low would fail on it.
327
+ actual = Schema(
328
+ views={
329
+ "public.low": _view("low", "SELECT 1 AS x"),
330
+ "public.high": _view("high", " SELECT low.x\n FROM low;"),
331
+ },
332
+ relation_dependents={"public.low": ["public.high"]},
333
+ )
334
+ desired = Schema(tables={"public.low": _table("low", x="integer")})
335
+ drops = [c for c in compute_diff(desired, actual) if isinstance(c, DropView)]
336
+ assert len(drops) == 2
337
+ assert all(c.category == ChangeCategory.OFFLINE for c in drops)
338
+
339
+
340
+ class TestRevokedRelationGrants:
341
+ @pytest.mark.parametrize(
342
+ "grant",
343
+ [
344
+ Grant("TABLE", "t", "public", "SELECT", "app"),
345
+ Grant("COLUMN", "t", "public", "SELECT", "app", column="a"),
346
+ Grant("SEQUENCE", "s", "public", "USAGE", "app"),
347
+ Grant("SCHEMA", "public", "public", "USAGE", "app"),
348
+ ],
349
+ )
350
+ def test_a_revoke_is_a_contract_change(self, grant):
351
+ actual = Schema(
352
+ tables={"public.t": _table("t", a="integer")},
353
+ sequences={"public.s": Sequence("public", "s")},
354
+ grants=[grant],
355
+ )
356
+ desired = Schema(
357
+ tables={"public.t": _table("t", a="integer")},
358
+ sequences={"public.s": Sequence("public", "s")},
359
+ )
360
+ changes = compute_diff(desired, actual)
361
+ assert [type(c) for c in changes] == [RevokePrivilege]
362
+ assert is_held_back(changes[0])
363
+
364
+ def test_a_table_revoke_regrants_the_declared_columns(self):
365
+ # Moving a role from table-wide SELECT to SELECT (a): the contract
366
+ # run's REVOKE strips the column grant the expand run already wrote.
367
+ table = _table("t", a="integer", b="integer")
368
+ column = Grant("COLUMN", "t", "public", "SELECT", "app", column="a")
369
+ actual = Schema(
370
+ tables={"public.t": table},
371
+ grants=[Grant("TABLE", "t", "public", "SELECT", "app")],
372
+ )
373
+ desired = Schema(tables={"public.t": table}, grants=[column])
374
+ changes = compute_diff(desired, actual)
375
+ # One statement: an expand run, under the table-wide grant, has no
376
+ # use for the column grant (the catalog reports it as part of that).
377
+ assert [type(c) for c in changes] == [RevokePrivilege]
378
+ revoke = changes[0]
379
+ assert isinstance(revoke, RevokePrivilege) and is_held_back(revoke)
380
+ assert revoke.regrant_columns == [column]
381
+ sql = revoke.to_sql()
382
+ assert sql.index("REVOKE SELECT") < sql.index('GRANT SELECT ("a")')
188
383
 
189
384
 
190
385
  # =============================================================================
@@ -439,3 +634,97 @@ class TestExpandRefusesBreakingBlocks:
439
634
  sql_dir = tmp_path / "sql"
440
635
  _declare(sql_dir, INCIDENT_V2)
441
636
  apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
637
+
638
+
639
+ # =============================================================================
640
+ # Relations and grants, against a real server
641
+ # =============================================================================
642
+
643
+
644
+ @pytest.fixture
645
+ def app_role(server_url):
646
+ role = f"pgdeclare_ec_app_{uuid.uuid4().hex[:8]}"
647
+ _run(server_url, f'CREATE ROLE "{role}"')
648
+ try:
649
+ yield role
650
+ finally:
651
+ _run(server_url, f'DROP ROLE IF EXISTS "{role}"')
652
+
653
+
654
+ RELATIONS_V1 = """
655
+ CREATE TABLE t (a int, b int);
656
+ CREATE VIEW v AS SELECT a FROM t;
657
+ CREATE MATERIALIZED VIEW m AS SELECT a FROM t;
658
+ CREATE SEQUENCE s;
659
+ GRANT USAGE ON SCHEMA public TO "{role}";
660
+ GRANT SELECT ON t TO "{role}";
661
+ GRANT SELECT ON v TO "{role}";
662
+ GRANT SELECT ON m TO "{role}";
663
+ GRANT USAGE ON SEQUENCE s TO "{role}";
664
+ """
665
+
666
+ # The old version reads all of it, as the application role.
667
+ OLD_READS = (
668
+ 'SET ROLE "{role}"; '
669
+ "SELECT (SELECT count(*) FROM t), (SELECT count(*) FROM v), "
670
+ "(SELECT count(*) FROM m), nextval('s') > 0, (SELECT count(b) FROM t)"
671
+ )
672
+
673
+ # The new version reads t's column a only, and needs none of the rest.
674
+ RELATIONS_V2 = """
675
+ CREATE TABLE t (a int, b int);
676
+ GRANT USAGE ON SCHEMA public TO "{role}";
677
+ GRANT SELECT (a) ON t TO "{role}";
678
+ """
679
+
680
+
681
+ class TestRelationsWhileTheOldVersionServes:
682
+ def test_expand_keeps_what_the_old_version_reads_and_contract_drops(
683
+ self, tmp_path, app_role, databases
684
+ ):
685
+ target, plan = databases
686
+ sql_dir = tmp_path / "sql"
687
+ config = PgDeclareConfig(report=lambda _line: None, managed_roles=(app_role,))
688
+ _declare(sql_dir, RELATIONS_V1.format(role=app_role))
689
+ apply_declared_schema(target, sql_dir, plan, config=config)
690
+ old_reads = OLD_READS.format(role=app_role)
691
+ assert _run(target, old_reads) == [(0, 0, 0, True, 0)]
692
+
693
+ _declare(sql_dir, RELATIONS_V2.format(role=app_role))
694
+ # Before the fix, this dropped v, m and s and revoked the table-wide
695
+ # SELECT, and every one of these reads failed until the switch.
696
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=config)
697
+ assert _run(target, old_reads) == [(0, 0, 0, True, 0)]
698
+
699
+ # Contract, once the old version has stopped: the role keeps column a
700
+ # (the table-wide REVOKE strips it, and the same statement restores it).
701
+ apply_declared_schema(target, sql_dir, plan, config=config)
702
+ assert _run(
703
+ target,
704
+ "SELECT relname FROM pg_class WHERE relnamespace = "
705
+ "'public'::regnamespace ORDER BY 1",
706
+ ) == [("t",)]
707
+ assert _run(target, f'SET ROLE "{app_role}"; SELECT count(a) FROM t') == [(0,)]
708
+ with pytest.raises(psycopg2.errors.InsufficientPrivilege):
709
+ _run(target, f'SET ROLE "{app_role}"; SELECT count(b) FROM t')
710
+ apply_declared_schema(
711
+ target, sql_dir, plan, expect_converged=True, config=config
712
+ )
713
+
714
+ def test_a_view_replaced_by_a_table_of_its_name_is_refused_online(
715
+ self, tmp_path, databases
716
+ ):
717
+ target, plan = databases
718
+ sql_dir = tmp_path / "sql"
719
+ _declare(sql_dir, "CREATE TABLE t (a int);\nCREATE VIEW v AS SELECT a FROM t;")
720
+ apply_declared_schema(target, sql_dir, plan, config=QUIET)
721
+
722
+ _declare(sql_dir, "CREATE TABLE t (a int);\nCREATE TABLE v (a int);")
723
+ with pytest.raises(Exception, match="Migration execution failed"):
724
+ apply_declared_schema(target, sql_dir, plan, expand_only=True, config=QUIET)
725
+ assert _run(target, "SELECT count(*) FROM v") == [(0,)]
726
+
727
+ apply_declared_schema(target, sql_dir, plan, offline=True, config=QUIET)
728
+ assert _run(target, "SELECT relkind FROM pg_class WHERE relname = 'v'") == [
729
+ ("r",)
730
+ ]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes