Share via

Configure a connection to Databricks using the Databricks JDBC Driver (OSS)

  • Article

This article shows you how to configure a connection to Databricks using the Databricks JDBC Driver (OSS).

Configure the connection

To connect to your Azure Databricks workspace using the JDBC driver, you need to specify various connection settings such as your Azure Databricks workspace's server hostname, the compute resource settings, and authentication credentials to connect to the workspace.

You can set the value of these properties on the JDBC connection URL, set and pass them to the DriverManager.getConnection method, or a combination of both. See the provider's documentation for how best to connect using your specific app, client, SDK, API, or SQL tool.

The JDBC connection URL must be in the following format. Properties are case insensitive.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Alternatively, specify the settings using the java.util.Properties class or a combination:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Connection URL elements are described in the following table.

For information about additional properties, including authentication properties, SQL configuration properties, and logging properties, see Supported connection properties.

Note

URL elements and properties are case insensitive.

URL element or property Description
<server-hostname> The Azure Databricks compute resource's server hostname value.
<port> The Azure Databricks compute resource's port value. The default value is 443.
<schema> The name of the schema. Alternatively you can set the ConnSchema property. See Supported connection properties.
httpPath The Azure Databricks compute resource's HTTP path value. The connector forms the HTTP address to connect to by appending the httpPath value to the host and port specified in the connection URL. For example, to connect to the HTTP address http://localhost:10002/cliservice, you would use the following connection URL: jdbc:databricks://localhost:10002;httpPath=cliservice

To get the JDBC connection URL for an Azure Databricks cluster:

  1. Log in to your Azure Databricks workspace.
  2. In the sidebar, click Compute, then click the target cluster's name.
  3. On the Configuration tab, expand Advanced options.
  4. Click the JDBC/ODBC tab.
  5. Copy the JDBC URL to use as the JDBC connection URL, or construct the URL from values in the Server hostname, Port, and HTTP Path fields.

To get the JDBC connection URL for a Databricks SQL warehouse:

  1. Log in to your Azure Databricks workspace.
  2. In the sidebar, click SQL Warehouses, then click the target warehouse's name.
  3. Click the Connection details tab.
  4. Copy the JDBC URL to use as the JDBC connection URL, or construct the URL from values in the Server hostname, Port, and HTTP Path fields.

Configure proxy connections

You can configure the connector to connect through a proxy server instead of connecting directly to Databricks. When connecting through a proxy server, the connector supports basic and SPNEGO authentication.

To configure a proxy connection:

  1. Set the UseProxy property to 1.
  2. To configure proxy settings at the system level, set UseSystemProxy property to 1, otherwise set it for the driver in the following way:
    1. Set the ProxyHost property to the IP address or hostname of your proxy server.
    2. Set the ProxyPort property to the port that the proxy server uses to listen for client connections.
    3. Set the ProxyIgnoreList property to a comma separated hostname.
    4. Authenticate with the proxy server:
      • To use basic authentication
        1. Set the ProxyAuth property to 1.
        2. Set the ProxyUID property to your username for accessing the server.
        3. Set the ProxyPWD property to your password for accessing the server.
      • To use SPNEGO authentication:
        1. Authenticate your kerberos principal at the system level.
        2. Set the ProxyAuth property to 2.

To use a different proxy specifically for CloudFetch, follow the steps above with the following properties: UseCFProxy, CFProxyHost, CFProxyPort, CFProxyAuth, CFProxyUID, CFProxyPwd

Configuring SSL

If you are connecting to Databricks that has Secure Sockets Layer (SSL) enabled, you can configure the connector to connect to an SSL-enabled socket. When connecting to a server over SSL, the connector uses one-way authentication to verify the identity of the server.

One-way authentication requires a signed, trusted SSL certificate for verifying the identity of the server. You can configure the connector to access a specific TrustStore that contains the appropriate certificate. If you do not specify a TrustStore, then the connector uses the default Java TrustStore named jssecacerts. If jssecacerts is not available, then the connector uses cacerts instead.

To configure SSL:

  1. Set the SSL property to 1.
  2. If you are not using one of the default Java Trust Stores, then create a Trust Store and configure the connector to use it:
    1. Create a Trust Store containing your signed, trusted server certificate.
    2. Set the SSLTrustStore property to the full path of the TrustStore.
    3. Set the SSLTrustStorePwd property to the password for accessing the TrustStore.
    4. If the TrustStore is not a JKS TrustStore, set the SSLTrustStoreType property to the correct type. The supported types are:
      • SSLTrustStoreType=BCFKS (BouncyCastle FIPS Keystore)
      • SSLTrustStoreType=PKCS12 (Public Key Cryptography Standards #12)

In certain cases, where you want to change the certificate revocation strategy, the connector provides the following parameters:

  • CheckCertRevocation property when set to 0 will accept certificates that are revoked (default value of property is 1)
    • AcceptUndeterminedRevocation property when set to 1 will accept certificates where we are unable to identify the revocation status of the certificates (CRLDP is unreachable/times out etc), the default value of this property is 0

Authenticate the driver

You can authenticate the JDBC driver connection using one of the following authentication mechanisms:

OAuth user-to-machine (U2M) authentication

The JDBC driver supports OAuth user-to-machine (U2M) authentication for real-time human sign in and consent to authenticate the target Databricks user account. This is also known as browser-based OAuth authentication.

Azure Databricks has created the OAuth client ID databricks-sql-jdbc for customers. This is also the default OAuth client ID used in the JDBC driver. To configure OAuth U2M authentication, just add the following properties to your existing JDBC connection URL or java.util.Properties object:

Property Value
AuthMech 11
Auth_Flow 2
TokenCachePassPhrase The passphrase used to encrypt your cached OAuth U2M credentials. This prevents repeated browser-based authentications. To opt out of token caching, set EnableTokenCache to 0.

OAuth machine-to-machine (M2M) authentication

The JDBC driver supports OAuth machine-to-machine (M2M) authentication, also known as OAuth 2.0 client credentials authentication, using one of the following principals or identity. See Authorize unattended access to Azure Databricks resources with a service principal using OAuth.

M2M using Databricks managed service principal

To configure authentication using a Databricks managed service principal:

  1. Create a Databricks managed service-principal and assign it to Databricks accounts and workspaces.
  2. Create a Databricks OAuth secret for the service principal. See OAuth M2M setup guide.
  3. Grant access permissions to clusters and SQL warehouses.
  4. Add the following properties to your existing JDBC connection URL or java.util.Properties object:
Property Value
AuthMech 11
Auth_Flow 1
OAuth2ClientID The service principal's Application (client) ID value.
OAuth2Secret The service principal's Azure Databricks OAuth secret.

M2M using Azure managed service principal

To configure authentication using an Azure managed service principal:

  1. Create a Databricks OAuth secret for the service principal. See OAuth M2M setup guide.
  2. Grant access permissions to clusters and SQL warehouses.
  3. Add the following properties to your existing JDBC connection URL or java.util.Properties object:
Property Value
AuthMech 11
Auth_Flow 1
OAuth2ClientID The service principal's Application (client) ID value.
AzureTenantID The Azure tenant ID found in Azure Active Directory.
OAuth2Secret The service principal's Azure Databricks OAuth secret.

M2M using Azure managed identities

To configure authentication using Azure managed identities:

  1. Configure managed identities for your Azure resources.
  2. Grant access permissions to clusters and SQL warehouses.
  3. Add the following properties to your existing JDBC connection URL or java.util.Properties object:
Property Value
AuthMech 11
Auth_Flow 3
OAuth2ClientID The Client ID of the managed identity. This is a required parameter only if you are using a user assigned managed identity.
Azure_workspace_resource_id Your Databricks workspace's Azure Resource ID

Azure Databricks personal access token

To authenticate your JDBC driver connection using a Azure Databricks personal access token, add the following properties to your JDBC connection URL or java.util.Properties object:

Property Value
AuthMech 3
user The value token, as a string.
PWD or password Your Azure Databricks personal access token value, as a string.