Configure a connection to Databricks using the Databricks JDBC Driver

This page shows you how to configure a connection to Databricks using the Databricks JDBC Driver, version 3 and above.

Configure the connection

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

Set these properties on the JDBC connection URL, pass them to the DriverManager.getConnection method, or use 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.

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 query tags

Attach key-value tags to SQL queries for tracking and analytics purposes. Tags appear in the system.query.history table for query identification and analysis.

To add query tags to your connection, include the query_tags property in your JDBC URL:

jdbc:databricks://<server-hostname>:<port>/<schema>;query_tags=key1:value1,key2:value2

Query tags use a comma-separated key:value pair format:

• query_tags=key:value (single tag)
• query_tags=key1:value1,key2:value2,key3:value3 (multiple tags)

Configure proxy connections

Configure the connector to connect through a proxy server instead of connecting directly to Databricks. The connector supports basic and SPNEGO authentication when connecting through a proxy server. See Supported connection properties.

To use system-level proxy settings, set UseProxy=1 and UseSystemProxy=1.

To configure proxy settings manually:

1. Set UseProxy=1.
2. Set ProxyHost, ProxyPort, and ProxyIgnoreList.
3. To authenticate with the proxy server, choose one method:
   • Basic: Set ProxyAuth=1, ProxyUID, and ProxyPWD.
   • SPNEGO (Kerberos environments): Authenticate your Kerberos principal at the system level, then set ProxyAuth=2.

Configure a proxy for Cloud Fetch

Cloud Fetch requires a separate proxy configuration from the main driver connection. Use the UseCFProxy, CFProxyHost, CFProxyPort, CFProxyAuth, CFProxyUID, and CFProxyPwd connection properties to route Cloud Fetch traffic through a proxy. See Supported connection properties.

If your network is private, allow *.blob.core.windows.net and *.store.core.windows.net and add the required certificate downloads and revocations to your allow list.

Troubleshooting

If you can't resolve proxy issues, set EnableQueryResultDownload=0 to disable Cloud Fetch and fall back to direct download.

To diagnose performance issues, set LogLevel=4 to enable INFO-level logging. The driver logs download speed per chunk, so large result sets generate multiple log lines:

CloudFetch download speed: 21.24 MB/s
CloudFetch download speed: 20.60 MB/s

The driver logs a warning when download speed falls below approximately 1 MB/s. The log component is com.databricks.client.spark.jdbc.ResultFileDownloadHandler. If downloads are slow or stalled, increase CloudFetchThreadPoolSize to download more file chunks in parallel.

Configuring SSL

If you're connecting to a Databricks workspace with SSL enabled, configure the connector to connect to an SSL-enabled socket. The connector uses one-way authentication to verify the server's identity.

One-way authentication requires a signed, trusted SSL certificate. Configure the connector to access a specific TrustStore. If you don't specify a TrustStore, the connector uses the default Java TrustStore (jssecacerts), or cacerts if jssecacerts isn't available.

To configure SSL:

1. Set SSL=1.
2. If you're not using a default Java TrustStore, configure a custom one:
   • Create a TrustStore containing your signed, trusted server certificate.
   • Set SSLTrustStore to the full path of the TrustStore.
   • Set SSLTrustStorePwd to the TrustStore password.
   • If the TrustStore isn't a JKS TrustStore, set SSLTrustStoreType to either BCFKS (BouncyCastle FIPS Keystore) or PKCS12.

To change the certificate revocation strategy, set the following properties:

• CheckCertRevocation: Set to 0 to accept revoked certificates. The default is 1.
• AcceptUndeterminedRevocation: Set to 1 to accept certificates with undetermined revocation status (for example, when CRLDP is unreachable or times out). The default is 0.

Authenticate the driver

For information about configuring authentication for the JDBC driver, see Authentication settings for the Databricks JDBC Driver.