Limit catalog access to specific workspaces

This article introduces workspace-catalog binding, and describes how to bind a Unity Catalog catalog to a Databricks workspace to prevent other workspaces in your Databricks account from accessing it.

What is workspace-catalog binding?

If you use workspaces to isolate user data access, you can limit catalog access to specific workspaces in your account, also known as workspace-catalog binding. The default is to share the catalog with all workspaces attached to the current metastore.

The exception to this default is the workspace catalog that is created automatically for all new workspaces. This workspace catalog is bound only to your workspace, unless you choose to give other workspaces access to it. For important information about assigning permissions if you unbind this catalog, see Unbind a catalog from a workspace.

You can allow read and write access to the catalog from a workspace, or you can specify read-only access. If you specify read-only, then all write operations are blocked from that workspace to that catalog.

Typical use cases for binding a catalog to specific workspaces include:

  • Ensuring that users can only access production data from a production workspace environment.

  • Ensuring that users can only process sensitive data from a dedicated workspace.

  • Giving users read-only access to production data from a developer workspace to enable development and testing.

Note

You can also bind external locations and storage credentials to specific workspaces, limiting the ability to access data in external locations to privileged users in those workspaces. See (Optional) Assign an external location to specific workspaces and (Optional) Assign a storage credential to specific workspaces.

Workspace-catalog binding example

Take the example of production and development isolation. If you specify that your production data catalogs can only be accessed from production workspaces, this supersedes any individual grants that are issued to users.

Catalog-workspace binding diagram

In this diagram, prod_catalog is bound to two production workspaces. Suppose a user has been granted access to a table in prod_catalog called my_table (using GRANT SELECT ON my_table TO <user>). If the user tries to access my_table in the Dev workspace, they receive an error message. The user can access my_table only from the Prod ETL and Prod Analytics workspaces.

Workspace-catalog bindings are respected in all areas of the platform. For example, if you query the information schema, you see only the catalogs accessible in the workspace where you issue the query. Data lineage and search UIs likewise show only the catalogs that are assigned to the workspace (whether using bindings or by default).

Bind a catalog to one or more workspaces

To assign a catalog to specific workspaces, you can use Catalog Explorer or the Databricks CLI.

Permissions required: Metastore admin, catalog owner, or MANAGE and USE CATALOG on the catalog.

Note

Metastore admins can see all catalogs in a metastore using Catalog Explorer—and catalog owners can see all catalogs they own in a metastore—regardless of whether the catalog is assigned to the current workspace. Catalogs that are not assigned to the workspace appear grayed out, and no child objects are visible or queryable.

  1. Log in to a workspace that is linked to the metastore.

  2. Click Catalog icon Catalog.

  3. In the Catalog pane, on the left, click the catalog name.

    The main Catalog Explorer pane defaults to the Catalogs list. You can also select the catalog there.

  4. On the Workspaces tab, clear the All workspaces have access checkbox.

    If your catalog is already bound to one or more workspaces, this checkbox is already cleared.

  5. Click Assign to workspaces and enter or find the workspaces you want to assign.

  6. (Optional) Limit workspace access to read-only.

    On the Manage Access Level menu, select Change access to read-only.

    You can reverse this selection at any time by editing the catalog and selecting Change access to read & write.

To revoke access, go to the Workspaces tab, select the workspace, and click Revoke.

There are two Databricks CLI command groups and two steps required to assign a catalog to a workspace.

In the following examples, replace <profile-name> with the name of your Databricks authentication configuration profile. It should include the value of a personal access token, in addition to the workspace instance name and workspace ID of the workspace where you generated the personal access token. See Databricks personal access token authentication.

  1. Use the catalogs command group’s update command to set the catalog’s isolation mode to ISOLATED:

    databricks catalogs update <my-catalog> \
--isolation-mode ISOLATED \
--profile <profile-name>

    The default isolation-mode is OPEN to all workspaces attached to the metastore.

  2. Use the workspace-bindings command group’s update-bindings command to assign the workspaces to the catalog:

    databricks workspace-bindings update-bindings catalog <my-catalog> \
--json '{
  "add": [{"workspace_id": <workspace-id>, "binding_type": <binding-type>}...],
  "remove": [{"workspace_id": <workspace-id>, "binding_type": "<binding-type>}...]
}' --profile <profile-name>

    Use the "add" and "remove" properties to add or remove workspace bindings. The <binding-type> can be either “BINDING_TYPE_READ_WRITE” (default) or “BINDING_TYPE_READ_ONLY”.

To list all workspace assignments for a catalog, use the workspace-bindings command group’s get-bindings command:

databricks workspace-bindings get-bindings catalog <my-catalog> \
--profile <profile-name>

Unbind a catalog from a workspace

Instructions for revoking workspace access to a catalog using Catalog Explorer or the workspace-bindings CLI command group are included in Bind a catalog to one or more workspaces.

Important

If your workspace was enabled for Unity Catalog automatically and you have a workspace catalog, workspace admins own that catalog and have all permissions on that catalog in the workspace only. If you unbind that catalog or bind it to other catalogs, you must grant any required permissions manually to the members of the workspace admins group as individual users or using account-level groups, because the workspace admins group is a workspace-local group. For more information about account groups vs workspace-local groups, see Types of groups in Databricks.