Upgrade to privilege inheritance

If you created your Unity Catalog metastore during the public preview (before August 25, 2022), you can upgrade to Privilege Model version 1.0. to take advantage of privilege inheritance. Existing workloads will continue to operate as-is until you upgrade your privilege model. Databricks recommends upgrading to Privilege Model version 1.0 to get the benefits of privilege inheritance and new features.

Differences in Privilege Model Version 1.0

Privilege Model v1.0 in Unity Catalog has the following differences from the public preview privilege model:

  • Privilege inheritance: In Privilege Model v1.0 privileges are inherited on child securable objects. This means that granting a privilege on the catalog automatically grants the privilege to all current and future objects within the catalog. Similarly, privileges granted on a schema are inherited by all current and future objects within that schema. In the preview model, privileges are not inherited on child securable objects. For more information on privilege inheritance, see Inheritance model.

  • ALL PRIVILEGES is evaluated differently: In the public preview privilege model, ALL PRIVILEGES grants the principal all available privileges at the time of the privilege grant. In Privilege Model v1.0, the ALL PRIVILEGES permission expands to all available privileges at the time a permission check is made.

    In Privilege Model v1.0, when ALL PRIVILEGES is revoked only the ALL PRIVILEGES privilege itself is revoked. Users retain any other privileges that were granted to them separately.

  • CREATE TABLE is updated to CREATE EXTERNAL TABLE: The CREATE TABLE permission no longer applies to external locations or storage credentials, which are required to create external tables. In Privilege Model v1.0, you instead grant the CREATE EXTERNAL TABLE privilege on external locations and storage credentials to allow a user to create external tables using that external location or storage credential.

  • CREATE is removed: The CREATE permission is removed and replaced by the following more specific privileges: CREATE CATALOG, CREATE EXTERNAL LOCATION, CREATE FUNCTION, CREATE SCHEMA, CREATE TABLE, CREATE MANAGED STORAGE.

  • USAGE is removed: The USAGE permission is removed and replaced by the following more specific privileges: USE CATALOG and USE SCHEMA.

Upgrade to Privilege Model Version 1.0

Warning

You cannot undo this action.

  1. Upgrade all workloads that reference Unity Catalog to use Databricks Runtime 11.3 LTS or above.

    You must upgrade all clusters to use Databricks Runtime 11.3 LTS or above, and you must restart any running SQL warehouses. If you skip this step, workloads on older versions of Databricks Runtime will be rejected after you complete the upgrade.

  2. As an account admin, log in to the account console.

  3. Click Catalog icon Catalog.

  4. Click the metastore name.

  5. Under Privilege Model click Upgrade

  6. Click Upgrade

If you do not see the option to upgrade, your Unity Catalog metastore is already using Privilege Model 1.0.

Upgrade SQL commands (optional)

Databricks will continue to support grants expressed using the old privilege model and automatically map them to the equivalent grant in Privilege Model v1.0. However, privileges returned via SHOW GRANTS or information_schema data will continue to reference Privilege Model v1.0. Databricks recommends that you upgrade existing code that performs grants to reference the updated privilege model.

  • Replace the CREATE TABLE privilege on external locations or storage credentials with the CREATE EXTERNAL TABLE privilege.

  • Replace the CREATE permission with the specific privilege CREATE CATALOG, CREATE EXTERNAL LOCATION, CREATE FUNCTION, CREATE SCHEMA, or CREATE TABLE.

  • Replace the USAGE permission with the specific privilege USE CATALOG or USE SCHEMA.

For more information about Unity Catalog privilege model see Unity Catalog privileges and securable objects