jdbc:databricks://<server-hostname>:443;httpPath=<http-path>[;<setting1>=<value1>;<setting2>=<value2>;<settingN>=<valueN>]
To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
Replace <setting>=<value> as needed for each of the connection properties as listed in the following sections.
You can also add special or advanced driver capability settings.
Programmatic collections of JDBC connection properties can be used in Java code such as the following example:
package org.example;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;
public class Main {
public static void main(String[] args) throws Exception {
Class.forName("com.databricks.client.jdbc.Driver");
String url = "jdbc:databricks://" + System.getenv("DATABRICKS_SERVER_HOSTNAME") + ":443";
Properties p = new java.util.Properties();
p.put("httpPath", System.getenv("DATABRICKS_HTTP_PATH"));
p.put("<setting1>", "<value1");
p.put("<setting2>", "<value2");
p.put("<settingN>", "<valueN");
try (Connection conn = DriverManager.getConnection(url, p)) {
Statement stmt = conn.createStatement();
try (ResultSet rs = stmt.executeQuery("<query>")) {
ResultSetMetaData md = rs.getMetaData();
String[] columns = new String[md.getColumnCount()];
for (int i = 0; i < columns.length; i++) {
columns[i] = md.getColumnName(i + 1);
while (rs.next()) {
System.out.print("Row " + rs.getRow() + "=[");
for (int i = 0; i < columns.length; i++) {
if (i != 0) {
System.out.print(", ");
System.out.print(columns[i] + "='" + rs.getObject(i + 1) + "'");
System.out.println(")]");
System.exit(0);
Set the DATABRICKS_SERVER_HOSTNAME and DATABRICKS_HTTP_PATH environment values to the target Databricks compute resource’s Server Hostname and HTTP Path values, respectively. To get these values, see Compute settings for the Databricks JDBC Driver. To set environment variables, see your operating system’s documentation.
Replace <setting> and <value> as needed for each of the connection properties as listed in the following sections.
You can also add special or advanced driver capability settings, typically as additional <setting> and <value> pairs.
For this example, replace <query> with a SQL SELECT query string.
Whether you use a connection URL or a collection of connection properties will depend on the requirements of your target app, tool, client, SDK, or API. Examples of JDBC connection URLs and programmatic collections of JDBC connection properties are provided in this article for each supported Databricks authentication type.
The Databricks JDBC Driver supports the following Databricks authentication types:
Databricks personal access token
OAuth 2.0 tokens
OAuth user-to-machine (U2M) authentication
OAuth machine-to-machine (M2M) authentication
Basic authentication using a Databricks username and password reached end of life on July 10, 2024. See End of life for Databricks-managed passwords.
Databricks personal access token
To create a Databricks personal access token, do the following:
In your Databricks workspace, click your Databricks username in the top bar, and then select Settings from the drop down.
Click Developer.
Next to Access tokens, click Manage.
Click Generate new token.
(Optional) Enter a comment that helps you to identify this token in the future, and change the token’s default lifetime of 90 days. To create a token with no lifetime (not recommended), leave the Lifetime (days) box empty (blank).
Click Generate.
Copy the displayed token to a secure location, and then click Done.
Be sure to save the copied token in a secure location. Do not share your copied token with others. If you lose the copied token, you cannot regenerate that exact same token. Instead, you must repeat this procedure to create a new token. If you lose the copied token, or you believe that the token has been compromised, Databricks strongly recommends that you immediately delete that token from your workspace by clicking the trash can (Revoke) icon next to the token on the Access tokens page.
If you are not able to create or use tokens in your workspace, this might be because your workspace administrator has disabled tokens or has not given you permission to create or use tokens. See your workspace administrator or the following topics:
Enable or disable personal access token authentication for the workspace
Personal access token permissions
To authenticate using a Databricks personal access token, set the following configuration.
For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>
For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:
// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
In the preceding URL or Java code, replace <personal-access-token> with the Databricks personal access token for your workspace user.
To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
OAuth 2.0 tokens
JDBC driver 2.6.36 and above supports an OAuth 2.0 token for a Databricks user or service principal. This is also known as OAuth 2.0 token pass-through authentication.
To create an OAuth 2.0 token for token pass-through authentication, do the following:
For a user, you can use the Databricks CLI to generate the OAuth 2.0 token by initiating the OAuth U2M process, and then get the generated OAuth 2.0 token by running the databricks auth token command. See OAuth user-to-machine (U2M) authentication. OAuth 2.0 tokens have a default lifetime of 1 hour. To generate a new OAuth 2.0 token, repeat this process.
For a service principal, see Manually generate and use access tokens for OAuth M2M authentication. Make a note of the service principal’s OAuth access_token value. OAuth 2.0 tokens have a default lifetime of 1 hour. To generate a new OAuth 2.0 token, repeat this process.
To authenticate using OAuth 2.0 token pass-through authentication, set the following configuration.
For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>
For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:
// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
In the preceding URL or Java code, replace <oauth-token> with the OAuth 2.0 token.
To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
For more information, see the Token Pass-through section in the Databricks JDBC Driver Guide.
OAuth user-to-machine (U2M) authentication
JDBC driver 2.6.36 and above supports OAuth user-to-machine (U2M) authentication for a Databricks user. This is also known as OAuth 2.0 browser-based authentication.
JDBC 2.6.40.1071 resolves the issue in older versions that connecting using M2M for private link workspaces was not supported.
OAuth U2M or OAuth 2.0 browser-based authentication has no prerequisites. OAuth 2.0 tokens have a default lifetime of 1 hour. OAuth U2M or OAuth 2.0 browser-based authentication should refresh expired OAuth 2.0 tokens for you automatically.
OAuth U2M or OAuth 2.0 browser-based authentication works only with applications that run locally. It does not work with server-based or cloud-based applications.
To authenticate using OAuth user-to-machine (U2M) or OAuth 2.0 browser-based authentication, set the following configuration.
For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0
For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:
// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2");
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
In the preceding URL or Java code, replace <passphrase> with a passphrase of your choice. The driver uses this key for refresh token encryption.
To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
For more information, see the Using Browser Based Authentication section in the Databricks JDBC Driver Guide.
OAuth machine-to-machine (M2M) authentication
JDBC driver 2.6.36 and above supports OAuth machine-to-machine (M2M) authentication for a Databricks service principal. This is also known as OAuth 2.0 client credentials authentication.
JDBC does not currently connect using M2M for private link workspaces.
To configure OAuth M2M or OAuth 2.0 client credentials authentication, do the following:
Create a Databricks service principal in your Databricks workspace, and create an OAuth secret for that service principal.
To create the service principal and its OAuth secret, see Authenticate access to Databricks with a service principal using OAuth (OAuth M2M). Make a note of the service principal’s UUID or Application ID value, and the Secret value for the service principal’s OAuth secret.
Give the service principal access to your cluster or warehouse. See Compute permissions or Manage a SQL warehouse.
To authenticate using OAuth machine-to-machine (M2M) or OAuth 2.0 client credentials authentication, set the following configuration.
For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>
For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:
// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
In the preceding URL or Java code, replace the following placeholders:
Replace <service-principal-application-id> with the service principal’s UUID/Application ID value.
Replace <service-principal-oauth-secret> with the service principal’s OAuth Secret value.
To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
For more information, see the Using M2M Based Authentication section in the Databricks JDBC Driver Guide.
