Workspace‑Catalog Binding in Unity Catalog (Limit Catalog Access by Workspace)

Mohammad Gufran Jahangir August 18, 2025 0

Table of Contents

Why workspace‑catalog binding?

By default, any workspace attached to the same Unity Catalog metastore can see and access catalogs (subject to object‑level grants). Workspace‑catalog binding lets you restrict which workspaces can access a catalog—so you can keep production data visible only from prod workspaces, isolate dev/test, or share a specific catalog with only a subset of workspaces.

Use cases

Environment isolation: prod data only from the prod workspace.
Business unit isolation: Finance catalog visible only to Finance workspace(s).
Selective sharing: Provide a shared catalog to a handful of partner workspaces without exposing all catalogs.

Binding also exists for external locations and storage credentials when you need workspace‑level guardrails on file access.

Concepts & roles

OPEN vs ISOLATED: An OPEN catalog is visible in all workspaces attached to the metastore. An ISOLATED catalog is visible only in the workspaces you assign (bind) to it.
Who can bind: Metastore admins, catalog owners, or users with MANAGE + USE CATALOG on the catalog.
Read‑only vs read & write (per‑workspace): When binding, you can mark a workspace’s access as read‑only if you want to prevent writes from that workspace.

Quick start (UI) — bind a catalog to one or more workspaces

In your Databricks workspace, open Catalog → select the catalog.
Go to the Workspaces tab.
Uncheck All workspaces have access → the catalog switches to ISOLATED mode.
Click Assign to workspaces → pick one or more target workspaces.
(Optional) Set Manage access level to Read‑only for specific workspaces.
Save. The catalog is now visible only in the listed workspaces.

Unbind / revoke

From the same tab, select a workspace and Revoke to remove access. Re‑check All workspaces have access to return the catalog to OPEN mode.

CLI (automation) — workspace‑bindings

Requires modern Databricks CLI (OAuth login). Replace placeholders with your values.

Inspect current bindings

# Get binding mode and assignments (catalog, external_location, or storage_credential)
databricks workspace-bindings get catalog <catalog-name>

# List bound workspaces
databricks workspace-bindings get-bindings catalog <catalog-name>

Update bindings (add/remove workspaces; set mode)

# Make catalog ISOLATED and bind two workspaces (read & write)
databricks workspace-bindings update catalog <catalog-name> --isolation-mode ISOLATED

databricks workspace-bindings update-bindings catalog <catalog-name> --json '{
  "add": [
    {"workspace_id": <WS1_ID>, "binding_type": "BINDING_TYPE_READ_WRITE"},
    {"workspace_id": <WS2_ID>, "binding_type": "BINDING_TYPE_READ_WRITE"}
  ]
}'

# Change one workspace to read-only
databricks workspace-bindings update-bindings catalog <catalog-name> --json '{
  "add": [
    {"workspace_id": <WS1_ID>, "binding_type": "BINDING_TYPE_READ_ONLY"}
  ],
  "remove": [
    {"workspace_id": <WS1_ID>, "binding_type": "BINDING_TYPE_READ_WRITE"}
  ]
}'

# Return the catalog to OPEN (visible in all workspaces on the metastore)
databricks workspace-bindings update catalog <catalog-name> --isolation-mode OPEN

Tips

Bindings apply regardless of per‑table grants: if a workspace isn’t bound, users there won’t even see the catalog.
Metastore admins and catalog owners can still see the catalog entry from any workspace, but child objects won’t be visible or queryable unless the workspace is bound.

Terraform (IaC) — catalog to workspace bindings

# Bind a catalog only to the listed workspaces
resource "databricks_catalog_workspace_binding" "finance" {
  catalog_name = "finance"
  workspace_id = var.prod_workspace_id
}

# Add more workspaces by declaring additional resources or using for_each
resource "databricks_catalog_workspace_binding" "finance_dev" {
  catalog_name = "finance"
  workspace_id = var.dev_workspace_id
}

When you manage bindings via Terraform, the catalog is treated as ISOLATED and only bound to the workspace_ids you declare.

Patterns that work well

Environment split: Separate catalogs per env (for example, finance_dev, finance_prod) and bind each to its matching workspace. Apply future grants inside each catalog so tables inherit the right privileges.
BU isolation + shared hub: Business‑unit catalogs are isolated to their workspaces; a separate shared catalog is bound to multiple workspaces for cross‑BU datasets.
Storage guardrails: Bind external locations and storage credentials too, so developers in dev workspaces can’t mount or read prod buckets by mistake.

FAQ & troubleshooting

“Users still see the catalog but not tables” → That’s expected for metastore admins and catalog owners; bind the workspace or use a separate admin workspace.
“Grants look correct but table isn’t visible” → Check the catalog’s Workspaces tab; the workspace likely isn’t bound.
“Need to script bindings” → Use the CLI commands above or Terraform databricks_catalog_workspace_binding.
“Share data between workspaces without binding everything” → Keep catalogs isolated and grant SELECT on specific tables in a shared or hub catalog; only bind that catalog to the consuming workspaces.

One‑page checklist

Decide OPEN vs ISOLATED per catalog.
Bind catalogs to the correct workspaces; choose read‑only where appropriate.
Mirror bindings on external locations & storage credentials for file access.
Use future grants within each catalog for least‑privilege at table level.
Automate with CLI or Terraform; review regularly.

That’s it—you now have environment‑aware catalogs that are visible only where they should be.

Tags: Databricks

Category:

Databricks