Skip to main content

Configure a connection

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

Configure the connection URL​

To connect to your Databricks workspace using the JDBC driver, you need to specify a JDBC connection URL that includes various connection settings such as your 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:

Java
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);
Java
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 Databricks compute resource’s server hostname value.

<port>

The 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 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 a Databricks cluster:

  1. Log in to your 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 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.

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

OAuth machine-to-machine (M2M) authentication​

The JDBC driver supports OAuth machine-to-machine (M2M) authentication using a Databricks service principal. This is also known as OAuth 2.0 client credentials authentication. See Authorize unattended access to Databricks resources with a service principal using OAuth.

To configure OAuth M2M or OAuth 2.0 client credentials authentication:

  1. Create a Databricks service principal in your Databricks workspace, and create an OAuth secret for that service principal. See Authorize unattended access to Databricks resources with a service principal using OAuth. Make a note of the service principal’s UUID or Application ID value, and the Secret value for the service principal’s OAuth secret.
  2. Give the service principal access to your cluster or warehouse. See Compute permissions or Manage a SQL warehouse.

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 UUID or Application ID value.

OAuth2Secret

The service principal’s OAuth Secret value.

Databricks personal access token​

To authenticate your JDBC driver connection using a 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 Databricks personal access token value, as a string.

Last updated on