dataplat 0.2.1__tar.gz → 0.2.3__tar.gz

{dataplat-0.2.1 → dataplat-0.2.3}/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 0.2.3
+
+Redshift-only fixes. Nothing changes for PostgreSQL targets.
+
+### Fixed
+
+- `dp db role show` no longer claims every Redshift user has no password. The
+  attribute query reported `password_set=False` unconditionally, but
+  `pg_user.passwd` is masked to `'********'` there just as `pg_roles.rolpassword`
+  is on PostgreSQL — so it asserted "this login has no password" for every user,
+  the same falsehood 0.2.2 fixed on the PostgreSQL side. It now reports
+  `unknown`, with the reason. A Redshift *group* still reports `no`, because a
+  group has no password to hold.
+
+- `dp db describe <schema>` now reports `USAGE` grants on Redshift. The query
+  read `information_schema.usage_privileges` filtered to `object_type = 'SCHEMA'`,
+  which the SQL standard defines over domains, collations and sequences — never
+  schemas — so it returned nothing on every server. It now scans
+  `has_schema_privilege`, mirroring how the same query has always reported
+  `CREATE` on that path. As with `CREATE`, a privilege scan cannot report a
+  grantor or a grant option, so both stay empty; the PostgreSQL path reads the
+  ACL and does better on both counts.
+
+  Both fixes rest on documented behaviour and internal precedent rather than a
+  live cluster — Redshift cannot be containerized, so CI cannot cover it. See
+  below.
+
+### Added
+
+- A Redshift conformance harness (`tests/integration/redshift/`) for anyone who
+  runs dataplat against a real cluster. The read-only tier is safe to point at a
+  warehouse in use — a guard refuses anything that is not plainly a read before
+  it reaches the server — and it interrogates the assumptions the two fixes above
+  depend on, printing what your cluster answered. `CONTRIBUTING.md` documents
+  both tiers and the evidence rules for changing SQL that runs on a dialect CI
+  cannot reach.
+
+## 0.2.2
+
+Closes the six defects 0.2.1's integration suite found and pinned as expected
+failures. No expected failures remain.
+
+### Fixed
+
+- `dp db role show` claimed `Password set: yes` for every role, including a
+  passwordless `NOLOGIN` group. The attribute query read `rolpassword` from
+  `pg_roles`, whose view definition returns the literal `'********'` and can
+  never be NULL. Only `pg_authid` holds the real verifier and it is
+  superuser-only, so the field is now tri-state and reports `unknown` — with a
+  hint saying why — when the connecting role cannot read it. The privilege is
+  probed before the query rather than discovered by catching an error, since a
+  permission failure would abort the surrounding transaction.
+
+- `dp db describe <schema>` never reported `USAGE` grants. The query read
+  `information_schema.usage_privileges`, which on PostgreSQL does not cover
+  schemas at all, so the USAGE half of the union always returned nothing. The
+  PostgreSQL path now reads the schema ACL directly.
+
+- `dp db role show` under-counted a role's tables when it owned a partitioned
+  table. Both `relkind` `'r'` and `'p'` map to the label "table" and the
+  aggregation assigned rather than accumulated, so one group overwrote the
+  other while the total was summed separately and stayed right — the per-schema
+  breakdown contradicted its own total.
+
+- `dp db dbt-orphans purge` aborted the whole batch when a single relation had
+  vanished between scan and purge. The generated statement now uses
+  `IF EXISTS`, matching `top-tables`, so a missing relation is a no-op. When a
+  dependent object genuinely blocks a drop the purge still stops — that
+  all-or-nothing property is deliberate for a destructive batch — but it now
+  names the relation and everything depending on it instead of surfacing a raw
+  driver error, and records the blockage in the audit log.
+
+- `dp db describe <relation>` raised nothing but returned an invalid result for
+  a non-view relation: `pg_get_viewdef()` yields NULL rather than erroring, and
+  the PostgreSQL branch returned a view definition whose `sql` was `None`,
+  violating its own annotation. It now raises, as the Redshift branch already
+  did.
+
+- `dp db long-queries --history` died with a driver traceback on any server
+  where `pg_stat_statements` is installed but not preloaded — the most common
+  misconfiguration. The guard that was meant to catch this probed the view's
+  columns, which PostgreSQL answers from the view definition without invoking
+  the extension, so the probe always succeeded. The failure is now reported as
+  an actionable error naming `shared_preload_libraries` and the required
+  restart.
+
+### Changed
+
+- `RoleAttributes.password_set` widened from `bool` to `bool | None`, where
+  `None` means "not determinable by this connection". Relevant only if you
+  import the dataclass; the CLI renders the third state as `unknown`.
+
+- On PostgreSQL, `dp db describe <schema>` privileges now come from the schema
+  ACL rather than a `has_schema_privilege` scan. A role holding `CREATE` only
+  through membership in a granted role is no longer listed as its own row, and
+  `grantor` and `WITH GRANT OPTION` are now real values where the previous
+  CREATE half hardcoded them.
+
 ## 0.2.1
 
 ### Fixed

dataplat-0.2.3/CONTRIBUTING.md

@@ -0,0 +1,177 @@
+# Contributing to dataplat
+
+## Setup
+
+```bash
+git clone https://github.com/hanslemm/dataplat
+cd dataplat
+uv sync --group dev --all-extras
+```
+
+## Checks
+
+The four gates CI runs, across Python 3.12 and 3.13:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy dataplat
+```
+
+`uv run pytest` is green without Docker: the database-backed tests skip. To run
+them, start a server and point the suite at it:
+
+```bash
+docker run -d --name dp-pg-test \
+  -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=dataplat_test \
+  -p 55432:5432 postgres:16 -c shared_preload_libraries=pg_stat_statements
+docker exec dp-pg-test psql -U postgres -d dataplat_test \
+  -c 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements'
+
+DP_TEST_PG_REQUIRED=1 uv run pytest              # everything
+uv run pytest -m "not integration"               # skip the database half
+docker rm -f -v dp-pg-test                       # -v, or the volume dangles
+```
+
+`DP_TEST_PG_REQUIRED=1` turns an unreachable server into an error instead of a
+skip. CI sets it; without it a broken database would make the whole suite skip
+and still report success.
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+## Testing against a real Redshift cluster
+
+Redshift is a managed service, so there is no container and CI cannot cover it.
+If you have a cluster, you can. The suite is in `tests/integration/redshift/` and
+is split into two tiers, because they need different permission to run:
+
+| Marker | Mutates? | Needs |
+| --- | --- | --- |
+| `redshift` | no — read-only, safe against a warehouse in use | a reachable cluster |
+| `redshift_ddl` | **yes** | a cluster you can throw away |
+
+Credentials come from an ordinary dataplat target, so they stay in your own
+`.envrc` and never reach the repo:
+
+```bash
+export DP_TARGETS=warehouse WAREHOUSE_ENGINE=redshift \
+    WAREHOUSE_HOST=... WAREHOUSE_USER=... WAREHOUSE_DATABASE=... \
+    WAREHOUSE_PASSWORD=...
+export DP_TEST_RS_TARGET=warehouse      # or DP_TEST_RS_DSN=... as an escape hatch
+
+DP_TEST_RS_REQUIRED=1 uv run pytest -m redshift        # read-only tier
+```
+
+| Variable | Effect |
+| --- | --- |
+| `DP_TEST_RS_TARGET` | a dataplat target name, resolved by the tool's own config |
+| `DP_TEST_RS_DSN` | a raw libpq URL, if you would rather not declare a target |
+| `DP_TEST_RS_REQUIRED` | an unreachable cluster becomes an error instead of a skip |
+| `DP_TEST_RS_DISPOSABLE` | **required** before any `redshift_ddl` test will run |
+| `DP_TEST_RS_SCHEMA` | a schema the read-only tier may inspect (otherwise discovered) |
+
+A plain `uv run pytest` is unaffected: with nothing configured, both tiers skip.
+
+### Why there is a client-side read-only guard
+
+`rs_cursor` refuses anything that is not plainly a read *before it is sent*, on
+top of the server-side `READ ONLY` transaction. Two layers, because the cluster
+may be production: Redshift roles are cluster-wide, and its transactional-DDL
+semantics differ from PostgreSQL's, so the rollback-per-test isolation the
+PostgreSQL harness relies on cannot be assumed to clean up a mistake. A
+server-side check would refuse the statement too — but only after it crossed the
+network to a warehouse someone depends on.
+
+It denies by default: only `SELECT`, `WITH … SELECT`, `EXPLAIN` and `SHOW` pass.
+It is not fooled by a leading comment, case, a stray semicolon, a second
+statement smuggled after a `SELECT`, a data-modifying CTE, `SELECT … INTO`, or a
+side-effecting builtin such as `pg_terminate_backend`. The statement splitter is
+hand-written rather than regex-based because a regex that ignores quoting can
+*hide* a statement — naive comment stripping turns `SELECT '--' ; DROP TABLE t`
+into a harmless-looking fragment plus a `DROP` the server will happily run. The
+one hole it cannot close is an unlisted side-effecting UDF; that is what the
+server-side layer is for, and `assert_read_only`'s docstring says so.
+
+### What a run does and does not prove
+
+A green read-only run proves dataplat's `SELECT`s are **valid Redshift SQL
+against a real server, returning results that unpack** — which is precisely the
+class of defect the PostgreSQL suite found repeatedly in these same functions
+(an empty `pg_partition_tree`, a masked column, a view that does not cover
+schemas). It cannot tell you anything about `GRANT`, `DROP`, `RENAME` or session
+termination; those need the DDL tier and a disposable cluster.
+
+The run also prints a conformance table of what the cluster answered, because
+the point is learning what the engine does — a green run that recorded nothing
+has taught nobody anything.
+
+## Dialect changes: what counts as evidence
+
+`dataplat/services/db` targets PostgreSQL and Redshift. PostgreSQL has a real
+integration suite behind it. Redshift has none and cannot get one cheaply — it
+is a managed service, so there is no container to run in CI.
+
+For a while the rule was simply "don't touch SQL that runs on Redshift, because
+you can't test it." That is a good instinct and a bad rule. Applied literally it
+blocked seven known defects, and when they were finally looked at one at a time,
+six were fixable and only one genuinely needed Redshift-specific SQL. Five did
+not touch Redshift SQL at all, and the sixth turned out to use a construct the
+codebase was already shipping to Redshift elsewhere.
+
+So the question is not "can I test this?" but **"what evidence do I have?"** A
+change affecting the Redshift path needs at least one of the following, in
+descending order of strength:
+
+0. **A conformance run confirmed it against a real cluster.** Strongest, and the
+   only one that is evidence rather than inference — see the section above. A fix
+   currently resting on class 2 should be upgraded to class 0 when someone runs
+   the suite, and revisited if the run *refutes* it. `test_conformance.py` names
+   the assumptions each shipped fix depends on for exactly this reason.
+
+1. **It changes no Redshift SQL.** The fix is pure Python, or touches only a
+   `_*_SQL_POSTGRES` constant. Dialect risk is zero by construction — verify
+   that claim honestly, then go ahead. Aggregation bugs, error handling, and
+   return-value shaping usually land here.
+
+2. **The construct is already in production on the Redshift path.** Cite the
+   file and line. `ESCAPE '\'` was safe to add to `orphans.py` because
+   `top_tables.py` had always sent it to both engines;
+   `has_schema_privilege(...)` is safe in `describe.py`'s Redshift branch
+   because that branch already calls it. Internal precedent beats
+   documentation: it is the same server, the same driver, and code someone is
+   already running.
+
+3. **It withdraws a claim rather than making one.** Replacing a confidently
+   wrong value with "unknown" cannot be more wrong than what it replaced. See
+   the standing rule below.
+
+4. **Documented Redshift behaviour, cited, plus a fake-cursor test** pinning the
+   SQL the Redshift branch emits. Weakest of the four, because documentation and
+   deployed reality drift. Use it when the change is worth the residual risk,
+   and say so in the commit.
+
+If none of the four applies, **do not guess.** Leave the defect, and record it
+in a comment next to the code it affects — not in a tracker nobody reads. The
+comment is what lets the next person re-evaluate instead of rediscovering.
+
+### Requirements either way
+
+- **Keep the engine constants split.** Never edit a `_*_SQL_REDSHIFT` constant
+  to fix a PostgreSQL bug. If a shared statement needs to diverge, split it and
+  leave the Redshift half byte-for-byte as it was.
+- **Add a fake-cursor test** asserting what the Redshift branch emits. It is the
+  only mechanism that covers that path at all, and it catches the common
+  accident of "fixed both branches when I meant one".
+- **Record the evidence in the code**, not just the commit message. A future
+  reader deciding whether they may touch the line needs to see why it is the way
+  it is.
+
+### Standing rule: prefer "unknown" to a confident falsehood
+
+`dp db role show` used to print `Password set: yes` for every role, including
+passwordless ones, because the column it read is masked to `'********'` and can
+never be NULL. A report that states something false is worse than one that
+admits a gap — especially a report someone is using for an audit. When the
+server will not tell you, say so, and say why in the same breath: a bare
+"unknown" reads as a tool defect.

{dataplat-0.2.1 → dataplat-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataplat
-Version: 0.2.1
+Version: 0.2.3
 Summary: One command to manage any shape of data platform: databases, ingestion, BI, cloud, and CI.
 Project-URL: Homepage, https://github.com/hanslemm/dataplat
 Project-URL: Repository, https://github.com/hanslemm/dataplat
@@ -324,6 +324,9 @@ dp ingest airbyte connections set-cursor -c <connection-id> --xmin 0 --yes
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the integration suite and the rules
+for changing SQL that runs on Redshift.
+
 ```bash
 git clone https://github.com/hanslemm/dataplat
 cd dataplat
@@ -337,6 +340,13 @@ uv run mypy dataplat
 CI runs those four across Python 3.12 and 3.13 — the floor the wheel
 advertises as well as the pinned dev version.
 
+Redshift cannot be containerized, so CI cannot cover it. If you run dataplat
+against a Redshift cluster, you can verify your own deployment: point
+`DP_TEST_RS_TARGET` at one of your targets and run the read-only tier
+(`uv run pytest -m redshift`). It only issues `SELECT`s — a guard refuses
+anything else before it reaches the server — and prints what your cluster
+answered. See [CONTRIBUTING.md](CONTRIBUTING.md#testing-against-a-real-redshift-cluster).
+
 ### Integration tests against a real PostgreSQL
 
 Most of the suite drives a fake database cursor. That proves a code path

{dataplat-0.2.1 → dataplat-0.2.3}/README.md

@@ -279,6 +279,9 @@ dp ingest airbyte connections set-cursor -c <connection-id> --xmin 0 --yes
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the integration suite and the rules
+for changing SQL that runs on Redshift.
+
 ```bash
 git clone https://github.com/hanslemm/dataplat
 cd dataplat
@@ -292,6 +295,13 @@ uv run mypy dataplat
 CI runs those four across Python 3.12 and 3.13 — the floor the wheel
 advertises as well as the pinned dev version.
 
+Redshift cannot be containerized, so CI cannot cover it. If you run dataplat
+against a Redshift cluster, you can verify your own deployment: point
+`DP_TEST_RS_TARGET` at one of your targets and run the read-only tier
+(`uv run pytest -m redshift`). It only issues `SELECT`s — a guard refuses
+anything else before it reaches the server — and prints what your cluster
+answered. See [CONTRIBUTING.md](CONTRIBUTING.md#testing-against-a-real-redshift-cluster).
+
 ### Integration tests against a real PostgreSQL
 
 Most of the suite drives a fake database cursor. That proves a code path

{dataplat-0.2.1 → dataplat-0.2.3}/dataplat/cli/db/dbt_orphans.py

@@ -20,6 +20,8 @@ from dataplat.services.db.connection import SqlEngine
 from dataplat.services.db.orphans import (
     DEPRECATED_SUFFIX,
     LIVE_STATUSES,
+    BlockedEntry,
+    DependentObjectsError,
     DropEntry,
     ObjectKind,
     RenameEntry,
@@ -661,7 +663,19 @@ def purge_cmd(
         help="Path to a file with one exclusion token per line.",
     ),
 ) -> None:
-    """Permanently drop every object ending in _deprecated (irreversible)."""
+    """Permanently drop every object ending in _deprecated (irreversible).
+
+    All-or-nothing per target, by design: every drop for one warehouse runs
+    inside a single transaction, so if the warehouse refuses one of them
+    nothing is dropped for that target and the error names the blocking
+    relation. Keeping the drops that already succeeded would need either a
+    SAVEPOINT per object (Redshift has none) or a commit per object (which
+    would break the guarantee that --dry-run writes nothing) — and for a
+    destructive batch, stopping on the first surprise is the safer default. No
+    CASCADE is issued either, so a live view or foreign key still pointing at a
+    _deprecated relation is a real signal: resolve the dependents the error
+    lists, then re-run.
+    """
     if log is None:
         log = _timestamped_log_path(PURGE_LOG_PREFIX)
 
@@ -691,24 +705,48 @@ def purge_cmd(
     )
 
     all_drops: list[DropEntry] = []
+    blocked: list[BlockedEntry] = []
     try:
         for label, engine, env_prefix in engines:
-            all_drops.extend(
-                _purge_for_engine(
-                    label,
-                    engine,
-                    env_prefix=env_prefix,
-                    excluded_user_schemas=excluded_user_schemas,
-                    excluded_user_relations=excluded_user_relations,
-                    dry_run=dry_run,
-                    renamed_at=renamed_at,
-                    cutoff=cutoff,
-                    include_unknown=include_unknown,
+            try:
+                all_drops.extend(
+                    _purge_for_engine(
+                        label,
+                        engine,
+                        env_prefix=env_prefix,
+                        excluded_user_schemas=excluded_user_schemas,
+                        excluded_user_relations=excluded_user_relations,
+                        dry_run=dry_run,
+                        renamed_at=renamed_at,
+                        cutoff=cutoff,
+                        include_unknown=include_unknown,
+                    )
                 )
-            )
+            except DependentObjectsError as exc:
+                # The engine's transaction is already rolled back, so the drops
+                # it had made are (correctly) absent from all_drops. Record the
+                # refused attempt so the audit log shows why this target did
+                # nothing, then re-raise with the [<engine>] prefix every other
+                # error from this command carries.
+                blocked.append(
+                    BlockedEntry(
+                        database=label,
+                        schema=exc.schema,
+                        name=exc.name,
+                        kind=exc.kind,
+                        dependents=exc.dependents,
+                    )
+                )
+                raise ServiceError(f"[{label}] {exc}") from exc
     except ServiceError as exc:
-        _write_purge_log(log, all_drops, dry_run=dry_run)
+        _write_purge_log(log, all_drops, dry_run=dry_run, blocked=blocked)
         console.print(f"[red]{esc(exc)}[/red]")
+        if blocked:
+            console.print(
+                "[yellow]Nothing was dropped for that target: the purge is one "
+                "transaction, so a refused drop rolls the whole batch "
+                "back.[/yellow]"
+            )
         console.print(
             f"[yellow]Partial purge log written to {esc(log)} "
             f"({len(all_drops)} entries).[/yellow]"
@@ -839,12 +877,22 @@ def _drop_one(
     return DropEntry(database=label, schema=schema, name=name, kind=kind)
 
 
-def _write_purge_log(log_path: str, entries: list[DropEntry], *, dry_run: bool) -> None:
+def _write_purge_log(
+    log_path: str,
+    entries: list[DropEntry],
+    *,
+    dry_run: bool,
+    blocked: list[BlockedEntry] | None = None,
+) -> None:
     payload = {
         "generated_at": datetime.now(UTC).isoformat(),
         "dry_run": dry_run,
         "source": "dbt-orphans-purge",
         "drops": entries,
+        # A refused drop rolls its target's transaction back, so "drops" cannot
+        # hold the attempt; recorded separately or the log would show a purge
+        # that raised as having done nothing at all.
+        "blocked": blocked or [],
     }
     with open(log_path, "w") as f:
         json.dump(payload, f, indent=4)

{dataplat-0.2.1 → dataplat-0.2.3}/dataplat/cli/db/role.py

@@ -72,6 +72,26 @@ def _more_line(hidden: int) -> str:
     return f"  [dim italic]… and {hidden} more (raise --limit to see all).[/dim italic]"
 
 
+def _password_set_value(password_set: bool | None, engine: SqlEngine) -> str:
+    """Render the tri-state ``password_set`` as markup.
+
+    ``None`` means the server would not say, and the reason travels with the
+    word: a bare "unknown" in a security report reads as a tool defect, and
+    rendering it as "no" would be a false negative on exactly the field an
+    auditor came for. The reason differs by engine, and naming pg_authid on
+    Redshift — which has no such relation — would send the reader somewhere
+    that does not exist.
+    """
+    if password_set is None:
+        reason = (
+            "no readable password catalog on Redshift"
+            if engine == SqlEngine.redshift
+            else "needs superuser to read pg_authid"
+        )
+        return f"unknown [dim]({reason})[/dim]"
+    return "yes" if password_set else "no"
+
+
 def _attributes_metadata(attrs: RoleAttributes) -> list[tuple[str, str]]:
     flags: list[str] = []
     if attrs.superuser:
@@ -97,13 +117,20 @@ def _attributes_metadata(attrs: RoleAttributes) -> list[tuple[str, str]]:
         # The title card renders metadata values as markup, and this one is
         # warehouse data (rolvaliduntil rendered by the driver).
         metadata.append(("Valid until", esc(attrs.valid_until)))
-    if attrs.password_set:
+    # `is True` on purpose: password_set is tri-state, and the card has room
+    # only for a bare word. An unexplained "unknown" chip is worse than no
+    # chip, so the unknown case is left to the Attributes table, which has
+    # room to say why.
+    if attrs.password_set is True:
         metadata.append(("Password", "set"))
     return metadata
 
 
 def _render_attributes(
-    console: Console, counter: _SectionCounter, attrs: RoleAttributes
+    console: Console,
+    counter: _SectionCounter,
+    attrs: RoleAttributes,
+    engine: SqlEngine,
 ) -> None:
     _print_section_heading(
         console, counter, "Attributes", "Role flags, login, and limits."
@@ -122,7 +149,7 @@ def _render_attributes(
         "Connection limit",
         "unlimited" if attrs.connection_limit < 0 else str(attrs.connection_limit),
     )
-    table.add_row("Password set", "yes" if attrs.password_set else "no")
+    table.add_row("Password set", _password_set_value(attrs.password_set, engine))
     table.add_row("Valid until", cell(attrs.valid_until or "—"))
     console.print(_indent(table))
 
@@ -328,7 +355,7 @@ def render_role_description(
     console.print()
 
     counter = _SectionCounter()
-    _render_attributes(console, counter, desc.attributes)
+    _render_attributes(console, counter, desc.attributes, engine)
     parent_caption = (
         "Roles this role is a member of (single-level; Redshift groups)."
         if engine == SqlEngine.redshift

{dataplat-0.2.1 → dataplat-0.2.3}/dataplat/services/db/describe.py

@@ -665,6 +665,12 @@ def fetch_view_definition(cursor: Any, oid: int, engine: SqlEngine) -> ViewDefin
     if row is None:
         raise TargetNotFoundError(f"view with oid {oid} not found")
     sql, is_updatable, check_option = row
+    # pg_get_viewdef() does not error on a non-view oid, it returns NULL, so a
+    # table's oid produces a row whose definition is missing. Reject it the way
+    # the Redshift branch above does: returning ViewDefinition(sql=None) would
+    # break this dataclass's own `sql: str` contract for every caller.
+    if sql is None:
+        raise TargetNotFoundError(f"view with oid {oid} not found")
     updatable = isinstance(is_updatable, str) and is_updatable.upper() == "YES"
     if check_option is None or check_option == "NONE":
         check_option_value: str | None = None
@@ -752,10 +758,58 @@ ORDER BY c.relkind, c.relname
 """
 
 
-_SCHEMA_PRIVILEGES_SQL = """
-SELECT grantee, privilege_type, is_grantable = 'YES', grantor
-FROM information_schema.usage_privileges
-WHERE object_schema = %s AND object_type = 'SCHEMA'
+# PostgreSQL exposes schema ACLs only through pg_namespace.nspacl; there is no
+# information_schema view for them. usage_privileges reports DOMAIN, COLLATION,
+# FDW, foreign server and sequence object types and never 'SCHEMA', so the
+# USAGE half of the old shared query silently matched zero rows and every
+# GRANT USAGE ON SCHEMA was missing from the report.
+#
+# The COALESCE is load-bearing: nspacl stays NULL until the first GRANT or
+# REVOKE touches the schema, and NULL means "the built-in default" -- the owner
+# holding USAGE + CREATE -- not "nobody holds anything". acldefault('n', owner)
+# materialises that default so a freshly created schema still reports its
+# owner's privileges.
+#
+# Reading the ACL also makes grantor and WITH GRANT OPTION truthful: the CREATE
+# half of the old query derived grantees from has_schema_privilege() and had to
+# hardcode grantor='' and with_grant_option=false.
+_SCHEMA_PRIVILEGES_SQL_POSTGRES = """
+SELECT
+    CASE WHEN (acl).grantee = 0 THEN 'PUBLIC'
+         ELSE pg_get_userbyid((acl).grantee) END AS grantee,
+    (acl).privilege_type AS privilege_type,
+    (acl).is_grantable AS with_grant_option,
+    pg_get_userbyid((acl).grantor) AS grantor
+FROM pg_namespace n
+CROSS JOIN LATERAL aclexplode(COALESCE(n.nspacl, acldefault('n', n.nspowner))) AS acl
+WHERE n.nspname = %s
+ORDER BY grantee, privilege_type
+"""
+
+
+# Not the aclexplode form above: Redshift has no aclexplode(), and no cluster is
+# available to test a replacement against.
+#
+# The USAGE half used to read information_schema.usage_privileges filtered to
+# object_type = 'SCHEMA', which the SQL standard defines over domains,
+# collations and sequences — never schemas. It returned zero rows on every
+# server, so a GRANT USAGE ON SCHEMA was invisible here exactly as it was on
+# PostgreSQL. It is replaced by a has_schema_privilege() scan mirroring the
+# CREATE half directly below, which this same query has always run against
+# Redshift: same function, same catalog, same shape, only the privilege string
+# differs (CONTRIBUTING, evidence 2 — internal precedent on this very path).
+#
+# Known limitation, shared with the CREATE half and unchanged: a privilege scan
+# cannot report a grantor or a grant option, so both are reported empty, and
+# roles holding the privilege only through membership appear as their own rows.
+# The PostgreSQL path reads the ACL and does better on both counts.
+_SCHEMA_PRIVILEGES_SQL_REDSHIFT = """
+SELECT grantee, 'USAGE', false, ''
+FROM (
+    SELECT r.rolname AS grantee
+    FROM pg_roles r
+    WHERE has_schema_privilege(r.rolname, %s, 'USAGE')
+) u
 UNION ALL
 SELECT grantee, 'CREATE', false, ''
 FROM (
@@ -820,9 +874,19 @@ def fetch_schema_contents(
     ]
 
 
-def fetch_schema_privileges(cursor: Any, schema: str) -> list[PrivilegeGrant]:
-    """Return USAGE + CREATE grants for the schema."""
-    cursor.execute(_SCHEMA_PRIVILEGES_SQL, (schema, schema))
+def fetch_schema_privileges(
+    cursor: Any, schema: str, engine: SqlEngine
+) -> list[PrivilegeGrant]:
+    """Return USAGE + CREATE grants for the schema.
+
+    On PostgreSQL these come from ``pg_namespace.nspacl``, which lists explicit
+    ACL entries plus the owner's implicit default; a role that only holds the
+    privilege through membership in a granted role is not a separate row.
+    """
+    if engine == SqlEngine.redshift:
+        cursor.execute(_SCHEMA_PRIVILEGES_SQL_REDSHIFT, (schema, schema))
+    else:
+        cursor.execute(_SCHEMA_PRIVILEGES_SQL_POSTGRES, (schema,))
     return [PrivilegeGrant(*row) for row in cursor.fetchall()]
 
 
@@ -1044,7 +1108,7 @@ def describe_schema(
 ) -> SchemaDescription:
     """Compose a full schema description by invoking each fetcher."""
     header = fetch_schema_header(cursor, ref.schema)
-    privileges = fetch_schema_privileges(cursor, ref.schema)
+    privileges = fetch_schema_privileges(cursor, ref.schema, engine)
     default_privileges = fetch_schema_default_privileges(cursor, ref.schema, engine)
     contents = fetch_schema_contents(cursor, ref.schema, engine)
     return SchemaDescription(