[mateoHernandez123]

Description

• Bug fix
• New feature

Third of four stacked PRs for Unity Catalog (CXH-2722). A schema sits between a catalog and the tables and volumes an access review certifies. A principal can hold USE_SCHEMA without holding anything on those tables, so the schema is its own resource.

#70 is merged. #71 merges before this one.

What the connector syncs

Before, with #71 applied. The catalog is a leaf.

flowchart TD
  account[account]
  metastore[metastore]
  catalog[catalog]
  other["user, group, service principal, role, workspace"]
  account --> other
  account --> metastore
  metastore --> catalog

Loading

After this PR. Schemas hang from the catalog, with their own entitlements and grants.

flowchart TD
  account[account]
  metastore[metastore]
  catalog[catalog]
  schema[schema]
  other["user, group, service principal, role, workspace"]
  account --> other
  account --> metastore
  metastore --> catalog
  catalog --> schema
  style schema fill:#1f6feb,color:#fff,stroke:#1f6feb

Loading

Order	PR	Delivers	Base	State
1	#91	staging landed on main	main	Open
2	#90	Fix for the metastore layer of #70	#91	Open
3	#71	Catalog	#91	Open
4	#72	Schema	#71	This PR
5	#73	Table and volume	#72	Open

Sync:

• Schemas (schema, NEW) — child of catalog, read with GET /api/2.1/unity-catalog/schemas?catalog_name=. Keyed {metastore_id}::{catalog}.{schema}. The privilege set is the catalog set without BROWSE, CREATE_SCHEMA and USE_CATALOG, plus a read-only owner.
• A 404 on the schema listing is an error, not an empty catalog. An empty page would read as deletions in ConductorOne. The one exception is a 404 that names the catalog in error_code: that is the catalog itself being gone, and the catalog syncer removes the parent in the same sync.
• information_schema is skipped. Its system views are owned by principals that do not exist in SCIM.
• A catalog outside the sync scope takes its schemas with it. That rule comes from [CXH-2721] - Add Unity Catalog catalog sync - Databricks Connector #71 and is unchanged here.
• The types above are unchanged from [CXH-2720] - Add Unity Catalog client, access-path routing, and metastore sync - Databricks Connector #70 and [CXH-2721] - Add Unity Catalog catalog sync - Databricks Connector #71.

flowchart LR
  catalog[catalog]
  info[information_schema]
  schema[schema]
  catalog -.->|skipped| info
  catalog --> schema
  schema --> entitlements[one entitlement per schema privilege]
  schema --> owner[read-only owner]

Loading

Provisioning:

• Grant/Revoke schema privileges — the same PATCH .../permissions path and the same echo-confirmed idempotency as the catalog: GrantAlreadyExists and GrantAlreadyRevoked.
• A revoke that fails with SCHEMA_DOES_NOT_EXIST or CATALOG_DOES_NOT_EXIST is already revoked, whether the code comes back from the permissions read or from the trust check before it. Only the error code proves the absence, because an unbound or unprivileged workspace answers 404 as well.
• Owner is read-only.

Auth:

Credentials are unchanged. There is no new config field.

Schema List fails with PermissionDenied unless the service principal owns the metastore, owns the catalog, or holds MANAGE, USE_SCHEMA or ALL_PRIVILEGES on the catalog. Workspace Admin alone is not enough.

A direct Admin is also enough when the catalog is owned by that workspace's admins group. The connector reads the workspace id off the group name _workspace_admins_<workspace>_<id> and checks that workspace, whatever route the schema is listed through. Permission visibility follows the caller, not the host.

The visibility probe walks the attached workspaces. A 401 or 403 leaves the privilege unproven and the probe tries the next workspace. A workspace answering CATALOG_DOES_NOT_EXIST has only said it does not serve the catalog, since an ISOLATED catalog answers the same way from every workspace it is not bound to, so the walk moves on there too. Only every workspace answering that way, with no refusal among them, lists no schemas. Any other probe error fails that catalog's schema List. The page token carries the workspace and the metastore owner. It does not carry the catalog owner.

Architecture highlights:

• Shared trust probe: holdsPrivilegeOn is the one uncached read of the connector's own effective privileges. Each level passes the privileges it accepts and the error codes that prove the securable is gone. The schema probes carry those codes, so a 404 naming the missing securable is read as an absence rather than as a privilege the caller cannot see. Without them a principal holding MANAGE but owning neither the metastore nor the catalog got PermissionDenied on a dropped parent instead of a revoke reporting the grant already gone.
• Proven absence on the write path: the trust check is the first call that can prove a securable gone, and resolveChange runs it before the permissions read. grant and revoke answer that proof with NotFound and GrantAlreadyRevoked rather than returning it as an unreadable securable.
• Routing: inherited from [CXH-2721] - Add Unity Catalog catalog sync - Databricks Connector #71. The metastore's routes and the workspace Admin check come from the sync session, so the account listings do not run again per catalog.
• Principals: schema Grants uses the same principal path as [CXH-2720] - Add Unity Catalog client, access-path routing, and metastore sync - Databricks Connector #70. It reads the full account SCIM only when assignments exist, and uses the Find* filters for an owner-only grant.

Useful links:

• Linear ticket CXH-2722 — schema sync
• List schemas
• Unity Catalog privileges
• Update permissions on a securable

Merge order and release flow

staging lands on main as its own PR, #91. The rest of the stack is rebased on top of it, so each PR below shows only the layer it adds. #84 is independent of this stack and merges on its own.

1. Land staging on main - Databricks Connector #91 — staging landed on main (46 files)
2. [CXH-3600] - Sync metastore privileges held by the workspace admins group - Databricks Connector #90 — metastore privileges held by the workspace admins group (15 files)
3. [CXH-2721] - Add Unity Catalog catalog sync - Databricks Connector #71 — Unity Catalog catalog sync (25 files)
4. [CXH-2722] - Add Unity Catalog schema sync - Databricks Connector #72 (this PR) — Unity Catalog schema sync (17 files)
5. [CXH-2723] - Add Unity Catalog table and volume sync - Databricks Connector #73 — Unity Catalog table and volume sync (19 files)

#90 and #71 target #91 until it merges, and GitHub retargets them to main at that point. #72 and #73 keep their parent branch as base.

Rebased on 2026-11-03, as requested on #90. Before this, #90 and #71 showed 42 staging-only commits and 50+ files, which hid the layer each one adds. Every branch was rebuilt on top of #91. The tree at each head is byte-identical to the one reviewed before the rebase, so no code changed. The commits are squashed into one per PR, which marks earlier review threads as outdated; they stay readable.

Release flow. Cut a test release (-test) from the feature branch and move the PR to draft. The ticket moves to validation. QA validates that release. Merge to main. Cut the official release from main, and the ticket moves to rollout.

[linear-code]

CXH-2722

[FeliLucero1]

Did a pass on this one. The main things are the two mediums: Revoke on a dropped schema fails instead of returning already-revoked, and List swallows a 404 into an empty page. The rest is perf/docs/nits.

Stuff tagged (out of scope) is inherited from #71 or is stack-wide, so FYI, not blocking for this PR. Also checked the schema privilege set against the Databricks docs and it matches exactly (27, minus BROWSE / CREATE_SCHEMA / USE_CATALOG) 👍

[FeliLucero1]

[FeliLucero1]

Another pass. Nice work on the live checks (SCHEMA_DOES_NOT_EXIST, the privilege PATCH) and moving Grant/Revoke onto the shared helpers 👍

The main things this round are about schemas silently disappearing: the partial-listing skip (replied on the :73 thread), the usable[0] regression (replied on Sergio's :353 thread), and a 404 that still comes out as NotFound. The rest are nits. (out of scope): the same NotFound-wrapping shape exists in catalog.go pushRoute (#71).

[sergiocorral-conductorone]

Automated review (follow-up)

Head moved since our last LGTM (ce73192 → abee6af). Resolved at head: the usable[0] regression (workspace walk is back, TestSchemaListTriesTheNextWorkspace restored), the partial-listing fail-closed behaviour, the docs nit on the workspace-admins-group exception. Still open from earlier rounds: FeliLucero1's thread on schema.go:269 (plain %w on the metastore-assignment / workspace / metastore-owner reads lets a NotFound become an SDK warning). New this round: 1 regression (Revoke on a dropped schema), 1 medium (built-in catalog skip), 2 low.

drafted 4 → confirmed 4, low-confidence 0, dropped 0, added 0 (panel: opus-5.5 / gpt-6-astra / gemini-4-argon, all high)

[sergiocorral-conductorone]

Automated review (follow-up round on new commits).

Stats: drafted 2 → confirmed 2, low-confidence 0, dropped 0, added 0 (panel: opus-5.5 / gpt-6-astra / gemini-4-argon, all high).

[sergiocorral-conductorone]

Automated review

drafted 3 → confirmed 3, low-confidence 0, dropped 0, added 0 (panel: opus-5.5 / gpt-6-astra / gemini-4-argon, all high).

[FeliLucero1]

[low] schemaListingIsComplete returns errCatalogGone on purpose (:408-409), but here it just return errs, so it goes up raw (codes.Unknown, no prefix) and fails the sync. It's the race where GetCatalog says 200 and the permissions read then says CATALOG_DOES_NOT_EXIST. The catalogThrough branch above already does sawGone = true; continue, so maybe do the same here? There's no test for it either.

[FeliLucero1]

nit: MANAGE / USE SCHEMA / ALL PRIVILEGES only makes the listing complete. Grants/Grant/Revoke still need ownership or MANAGE on the schema or catalog (schemaGrantsAreTrustworthy, and ALL_PRIVILEGES is excluded on purpose). So someone who follows this with just USE SCHEMA gets the schemas listed, and then Grants fails with PermissionDenied. Maybe add a line about what reading schema privileges needs, like the catalog section has?