ALTER CONNECTION

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 13.3 LTS and above check marked yes Unity Catalog only

Transfers the ownership of a connection to a new principal, renames a connection, or changes the connection options.

To set a comment on a connection use COMMENT ON CONNECTION.

Important

When you set connection options that carry a credential, such as a password or token, to keep them secure, provide the value using the secret function rather than entering the literal value directly in the OPTIONS clause. This lets you reference a secret stored in the Databricks secret service instead of including the credential value in your statement.

Permissions

  • To change connection options, you must own the connection or have both MANAGE and USE CONNECTION on it. If the options set a service credential, you must also own the service credential or have CREATE CONNECTION on it, and the service credential must be accessible from the current workspace.
  • To rename a connection, you must own the connection or have both MANAGE and USE CONNECTION on it. You must also be a metastore admin or have CREATE CONNECTION on the metastore.
  • To transfer ownership, you must own the connection, be a metastore admin, or have both MANAGE and USE CONNECTION on the connection.

When you transfer ownership of a connection that references Unity Catalog secrets, the new owner must be able to read every referenced secret. This requirement does not apply to workspace secrets read with secret(scope, key).

Syntax

ALTER CONNECTION connection_name
 { [ SET ] OWNER TO principal |
   RENAME TO new_connection_name |
   OPTIONS ( option value [, ...] )

Parameters

  • connection_name

    The name of the connection to be altered.

  • [ SET ] OWNER TO principal

    Transfers ownership of the connection to principal.

  • RENAME TO new_connection_name

    Specifies a new name for the connection. The name must be unique within the Unity Catalog metastore.

  • OPTIONS

    Sets connection_type specific parameters needed to establish the connection.

    Replaces the existing list of options with a new list of options.

    • option

      The property key. The key can consist of one or more identifiers separated by a dot, or a STRING literal.

      Property keys must be unique and are case-sensitive.

    • value

      The value for the property. The value must be a BOOLEAN, STRING, INTEGER, or DECIMAL constant expression.

      For any option that carries a credential, such as a password or token, use the secret function instead of entering the value directly. For example, provide the value for password as secret('secrets.r.us', 'postgresPassword') rather than entering the literal password.

Examples

> ALTER CONNECTION mysql_connection SET OWNER TO `alf@melmak.et`;

> ALTER CONNECTION mysql_connection RENAME TO `other_mysql_connection`;

> ALTER CONNECTION mysql_connection OPTIONS (host 'newmysqlhost.us-west-2.amazonaws.com', port '3306');