Manage storage credentials

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

Databricks recommends that you grant only CREATE EXTERNAL LOCATION and no other privileges on storage credentials.

This article describes how to manage storage credentials using Catalog Explorer and SQL commands. 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.

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Sort the credentials by Purpose (STORAGE or SERVICE).

SQL

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.

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Click the name of a storage credential to see its properties.

SQL

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 or username contains a space or @ symbol, use back-ticks around it (not apostrophes). For example finance team .

Grant permissions to create external locations

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

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Click the name of a storage credential to open the details page.
  4. Click Permissions.
  5. To grant permission to users or groups, select each identity, then click Grant.
  6. To revoke permissions from users or groups, select each identity, then click Revoke.

SQL

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 or username contains a space or @ symbol, use back-ticks around it (not apostrophes). For example finance team .

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, you can use Catalog Explorer or a SQL command.

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Click the name of a storage credential to open the edit dialog.
  4. Click Edit icon next to Owner.
  5. Type to search for a principal and select it.
  6. Click Save.

SQL

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 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.

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Click the name of a storage credential to open the edit dialog.
  4. Rename the storage credential and save it.

SQL

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.

Catalog Explorer

  1. In the sidebar, click Catalog icon Catalog.
  2. On the Quick access page, click the External data > button and go to the Credentials tab.
  3. Click the name of a storage credential to open the edit dialog.
  4. Click the Delete button.

SQL

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>;