Transfer ownership of Databricks SQL objects

This article shows how to transfer ownership of a SQL warehouse, query, dashboard, or alert using the workspace UI, Databricks CLI version 0.205 or above, or the Permissions REST API.

• The Databricks CLI is a command-line tool for sending and receiving Databricks REST API requests and responses. If you choose to use Databricks CLI version 0.205 or above, it must be configured for authenticating with your Databricks workspace. See Install or update the Databricks CLI and Authentication for the Databricks CLI.

  • curl is a command-line tool for sending and receiving REST API requests and responses. See also Install curl. Alternatively, you can adapt this article’s curl examples for use with similar tools such as Postman or HTTPie.

    Note

    As a security best practice when you authenticate with automated tools, systems, scripts, and apps, Databricks recommends that you use OAuth tokens or personal access tokens belonging to service principals instead of workspace users. To create tokens for service principals, see Manage tokens for a service principal.

    Warning

    Databricks strongly discourages hard-coding information into your scripts, as this sensitive information can be exposed in plain text through version control systems. Databricks recommends that you use approaches such as environment variables that you set on your development machine instead. Removing such hard-coded information from your scripts helps to make those scripts more portable as well.

Transfer ownership using the workspace UI

Important

You must be a workspace admin to transfer ownership of a SQL warehouse, query, dashboard, or alert.

Transfer ownership of a SQL warehouse using the UI

Note

Service principals cannot be assigned ownership of a SQL warehouse.

1. As a workspace admin, log in to your Databricks workspace.

2. Click SQL Warehouses in the sidebar.

3. Click a SQL warehouse.

4. Click the Permissions button at the top right. The Manage Permissions dialog appears.

5. Click on the gear icon at the top right and click Assign new owner.

6. Select the user to assign ownership to and click Confirm.

Important

The user you transfer ownership of a SQL warehouse to must have the Allow cluster creation entitlement. If a workspace admin attempts to make a user the warehouse owner and that user lacks that entitlement, the operation fails. See Configure cluster creation entitlement.

Transfer ownership of a query, dashboard, or alert using the UI

1. As a workspace admin, log in to your Databricks workspace.

2. Select the query, dashboard, or alert you wish to transfer ownership of.

3. Click the Share button at the top right. The Sharing dialog appears.

4. Click on the gear icon at the top right and click Assign new owner.

   

5. Select the user or service principal to assign ownership to and click Confirm.

Transfer ownership using the Databricks CLI

Important

You must be a workspace admin to transfer ownership of a SQL warehouse, query, dashboard, or alert.

The following scripts show you how to change the ownership of a SQL warehouse, and then optionally great permissions to the new owner to all queries, dashboards, and alerts. To run these scripts, replace <warehouse-uuid> with the name of your SQL warehouse and replace <new-owner> with the name of the new SQL warehouse owner.

1. Changes ownership of the specified SQL warehouse to the specified new owner.

     databricks permissions set warehouses <warehouse-uuid> --json '{"access_control_list":
       [
          {"user_name": "<new-owner>", "permission_level": "IS_OWNER"}
       ]
     }'
   

2. Assigns permissions to all queries to the specified new owner.

     databricks api post /api/2.0/preview/sql/permissions/query/<query-id>/transfer --json '{"new_owner": "<new-owner>"}'
   

3. Assigns permissions to all dashboards to the specified new owner.

     databricks api post /api/2.0/preview/sql/permissions/dashboard/<dashboard-id>/transfer --json '{"new_owner": "<new-owner>"}'
   

4. Assigns permissions to all alerts to the specified new owner.

     databricks api post /api/2.0/preview/sql/permissions/alert/<alert-id>/transfer --json '{"new_owner": "<new-owner>"}'    ```
   

Transfer ownership using Permissions Rest API

To manage SQL warehouse permissions using the API, invoke methods on the /2.0/permissions/sql/ REST endpoint. For a complete API reference, see the Permissions API.

Important

You must be a workspace admin to transfer ownership of a SQL warehouse, query, dashboard, or alert.

Transfer ownership of a SQL warehouse

Important

The user you transfer ownership of a SQL warehouse to must have the Allow cluster creation entitlement. If a workspace admin attempts to make a user the warehouse owner and that user lacks that entitlement, the operation fails. See Configure cluster creation entitlement.

Service principals cannot be assigned ownership of a SQL warehouse.

curl --request PUT \
  --url https://<databricks-instance>/api/2.0/preview/permissions/sql/warehouses/<warehouse-uuid> \
  --header 'Authorization: Bearer <personal-access-token>' \
  --data '{"access_control_list": [{"user_name": "<new-owner>", "permission_level": "IS_OWNER"}]}'

Replace the following placeholders:

• <databricks-instance> is the workspace URL of your Databricks deployment.

• <warehouse-uuid>: the unique ID of the warehouse. To find the warehouse’s ID, open warehouse details page and copy the ID from the “Name” field.

• <new-owner>: the email address of the new owner.

• <personal-access-token> is a personal access token.

Note

This API uses a PUT method, which replaces all the existing permissions of the warehouse with the supplied permissions. Because of this, requests should additionally provide the full list of existing permissions with the data argument if they only want to append the IS_OWNER permission.

There are two important caveats for using this API:

• PUT requests without a warehouse owner will NOT overwrite, but keep the existing owner of the warehouse. If a new owner is provided in the request, the old owner permissions will be overwritten. This is to ensure there is always one owner present so cluster startup/stop continues to work.

• PATCH requests containing a warehouse owner will be rejected with a NOT_IMPLEMENTED error. Updating the warehouse owner MUST only be done using PUT calls. PATCH semantics of updating existing permissions cannot properly guarantee the constraint of having only one owner, which is currently required for all warehouses.

Transfer ownership of a query

curl --request POST \
  --url https://<databricks-instance>/api/2.0/preview/sql/permissions/query/<query-id>/transfer \
  --header 'Authorization: Bearer <personal-access-token>' \
  --data '{"new_owner": "<new-owner>"}'

Replace the following placeholders:

• <databricks-instance> is the workspace URL of your Databricks deployment.

• <query-id>: the unique ID of the query. To find the query’s ID, open the query in the SQL editor and copy the value after /queries/ and before o=.

• <new-owner>: the email address or application ID of the new owner.

• <personal-access-token> is a personal access token.

Transfer ownership of a dashboard

curl --request POST \
  --url https://<databricks-instance>/api/2.0/preview/sql/permissions/dashboard/<dashboard-id>/transfer \
  --header 'Authorization: Bearer <personal-access-token>' \
  --data '{"new_owner": "<new-owner>"}'

Replace the following placeholders:

• <databricks-instance> is the workspace URL of your Databricks deployment.

• <dashboard-id>: the unique ID of the dashboard. To find the dashboard’s ID, open the dashboard and copy the value after /dashboards/ and before o=.

• <new-owner>: the email address or application ID of the new owner.

• <personal-access-token> is a personal access token.

Transfer ownership of an alert

curl --request POST \
  --url https://<databricks-instance>/api/2.0/preview/sql/permissions/alert/<alert-id>/transfer \
  --header 'Authorization: Bearer <personal-access-token>' \
  --data '{"new_owner": "<new-owner>"}'

Replace the placeholders as follows:

• <databricks-instance> is the workspace URL of your Databricks deployment.

• <alert-id>: the unique ID of the alert. To find the alert’s ID, open the alert and copy the value after /alerts/ and before o=.

• <new-owner>: the email address or application ID of the new owner. The new owner must be a workspace administrator.

• <personal-access-token> is a personal access token.