Manage storage credentials

This article describes how to list, view, update, grant permissions on, and delete storage credentials.

Databricks recommends that the CREATE EXTERNAL LOCATION is the only permission granted on storage credentials.

This article describes how to manage storage credentials using Catalog Explorer and SQL commands in a notebook or Databricks SQL query. For information about using the Databricks CLI or Terraform instead, see the Databricks Terraform documentation and What is the Databricks CLI?.

List storage credentials

To view the list of all storage credentials in a metastore, you can use Catalog Explorer or a SQL command.

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

  2. Click Catalog icon Catalog.

  3. At the bottom of the screen, click Storage Credentials.

Run the following command in a notebook or the Databricks SQL editor.

SHOW STORAGE CREDENTIALS;

View a storage credential

To view the properties of a storage credential, you can use Catalog Explorer or a SQL command.

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

  2. Click Catalog icon Catalog.

  3. At the bottom of the screen, click Storage Credentials.

  4. Click the name of a storage credential to see its properties.

Run the following command in a notebook or the Databricks SQL editor. Replace <credential-name> with the name of the credential.

DESCRIBE STORAGE CREDENTIAL <credential-name>;

Show grants on a storage credential

To show grants on a storage credential, use a command like the following. You can optionally filter the results to show only the grants for the specified principal.

SHOW GRANTS [<principal>] ON STORAGE CREDENTIAL <storage-credential-name>;

Replace the placeholder values:

  • <principal>: The email address of the account-level user or the name of the account level group to whom to grant the permission.

  • <storage-credential-name>: The name of a storage credential.

Note

If a group name contains a space, use back-ticks around it (not apostrophes).

Grant permissions to create external locations

To grant permission to create an external location using a storage credential, complete the following steps:

  1. At the bottom of the screen, click Storage Credentials.

  2. Click the name of a storage credential to open its properties.

  3. Click Permissions.

  4. To grant permission to users or groups, select each identity, then click Grant.

  5. To revoke permissions from users or groups, select each identity, then click Revoke.

Run the following command in a notebook or the SQL query editor:

GRANT CREATE EXTERNAL LOCATION ON STORAGE CREDENTIAL <storage-credential-name> TO <principal>;

Replace the placeholder values:

  • <principal>: The email address of the account-level user or the name of the account level group to whom to grant the permission.

  • <storage-credential-name>: The name of a storage credential.

Note

If a group name contains a space, use back-ticks around it (not apostrophes).

Change the owner of a storage credential

A storage credential’s creator is its initial owner. To change the owner to a different account-level user or group, do the following:

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

  • <credential-name>: The name of the credential.

  • <principal>: The email address of an account-level user or the name of an account-level group.

ALTER STORAGE CREDENTIAL <credential-name> OWNER TO <principal>;

Mark a storage credential as read-only

If you want users to have read-only access to all data managed by a storage credential, you can use Catalog Explorer to mark the storage credential as read-only.

Making storage credentials read-only means that any storage configured with that credential is read-only.

You can mark storage credentials as read-only when you create them.

You can also use Catalog Explorer to change read-only status after creating a storage credential:

  1. In Catalog Explorer, find the storage credential, click the Kebab menu kebab menu (also known as the three-dot menu) on the object row, and select Edit.

  2. On the edit dialog, select the Read only option.

Rename a storage credential

To rename a storage credential, you can use Catalog Explorer or a SQL command.

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

  2. Click Catalog icon Catalog.

  3. At the bottom of the screen, click Storage Credentials.

  4. Click the name of a storage credential to open the edit dialog.

  5. Rename the storage credential and save it.

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

  • <credential-name>: The name of the credential.

  • <new-credential-name>: A new name for the credential.

ALTER STORAGE CREDENTIAL <credential-name> RENAME TO <new-credential-name>;

Delete a storage credential

To delete (drop) a storage credential you must be its owner. To delete a storage credential, you can use Catalog Explorer or a SQL command.

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

  2. Click Catalog icon Catalog.

  3. At the bottom of the screen, click Storage Credentials.

  4. Click the name of a storage credential to open the edit dialog.

  5. Click the Delete button.

Run the following command in a notebook or the Databricks SQL editor. Replace <credential-name> with the name of the credential. Portions of the command that are in brackets are optional. By default, if the credential is used by an external location, it is not deleted. Replace <credential-name> with the name of the credential.

  • IF EXISTS does not return an error if the credential does not exist.

DROP STORAGE CREDENTIAL [IF EXISTS] <credential-name>;