Supported connection properties
This article describes the connection properties supported by the Databricks JDBC Driver (OSS).
Authentication And Proxy Properties
The following authentication and proxy properties are supported by the Databricks JDBC Driver (OSS). Properties are case insensitive.
Property | Default value | Description |
---|---|---|
|
| The time in milliseconds between each poll for the asynchronous query execution status. Asynchronous refers to the fact that the RPC call used to execute a query against Spark is asynchronous. It does not mean that JDBC asynchronous operations are supported. |
|
| The OAuth2 authentication flow for the driver connection. This property is required if |
|
| The path to the private key file (PEM format) for JWT authentication. |
|
| The algorithm for private key JWT authentication. The supported algorithms are: RSA: RS256, RS384, RS512, PS256, PS384, PS512 and EC: ES256, ES384, ES512 |
|
| The passphrase for decrypting an encrypted private key. |
|
| The Key Identifier (KID) required for JWT authentication. This is mandatory when using private key JWT. |
| Required | The authentication mechanism, where |
|
| If set to |
|
| A string that represents the name of the proxy host to use when |
|
| An integer that represents the number of the proxy port to use when |
|
| A string that represents the username to use for proxy authentication when |
|
| A string that represents the password to use for proxy authentication when |
|
| The name of the default catalog to use. |
|
| The name of the default schema to use. This can be specified either by replacing |
|
| Enables authentication using a Google service account. |
|
| The path to the JSON key file for Google Service account authentication. |
|
| If set to |
|
| The OpenID Connect discovery URL for retrieving the OIDC configuration. |
|
| The OAuth2 refresh token used to retrieve a new access token. |
|
| The authorization endpoint URL used in an OAuth2 flow. |
|
| The token endpoint URL for the OAuth2 flow. |
|
| If set to |
|
| A string that represents the name of the proxy host to use when |
|
| An integer that represents the number of the proxy port to use when |
|
| A string that represents the password to use for proxy authentication when |
|
| A string that represents the username to use for proxy authentication when |
|
| If set to |
|
| If set to |
|
| If set to |
|
| Enables private key JWT authentication for M2M use cases where client secret authentication is restricted. |
SSL Trust Store Configuration Properties
The following SSL trust store configuration properties are supported by the Databricks JDBC Driver (OSS). Properties are case insensitive.
Property | Default value | Description |
---|---|---|
|
| If set to |
|
| If set to |
|
| Whether the connector communicates with the Spark server through an SSL-enabled socket. |
|
| The path to the trust store file for SSL certificate validation. |
|
| The password for the trust store file, if it is password-protected. |
|
| The type of the trust store, for example, JKS or PKCS12. If not specified, the driver defaults to JKS trust store. Valid types are |
|
| If set to |
Trust store types
The JDBC driver supports the following SSL modes and trust store types.
Self-signed certificate mode
To use self-signed certificate mode, set the connection property AllowSelfSignedCerts=1
. This mode uses a trust-all socket factory that accepts any certificate.
Custom trust store
To use a custom trust store, specify a custom trust store file in the SSLTrustStore
connection property. This trust store is loaded directly from the specified path and uses the certificates for SSL certificate validation. It can be in JKS, PKCS12, or other supported formats.
You must specify the following additional connection properties:
SSLTrustStore
: Path to the trust store fileSSLTrustStorePassword
: Password for the trust store (if needed)SSLTrustStoreType
: Type of trust store (optional, defaults to JKS if not specified)
Java system property trust store
To use the system property trust store, set UseSystemTrustStore=1
and make sure that you do not specify a custom trust store. Instead, specify a trust store using the Java system property javax.net.ssl.trustStore
. This property is set at the JVM level using the -D
flag, for example:
java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...
The JDBC driver first checks for the Java system property javax.net.ssl.trustStore
. If it is set, it uses this trust store file instead of the JDK's default. If no system property is set, uses the JDK's default trust store (cacerts), which is ocated at $JAVA_HOME/lib/security/cacerts
or similar path.
JDK default trust store (cacerts)
The JDK comes with a built-in trust store called cacerts which contains certificates from well-known Certificate Authorities, which allows verification of certificates issued by those CAs. This trust store is typically located at $JAVA_HOME/lib/security/cacerts
with a default password "changeit" or "changeme".
To use the JDK default trust store, set UseSystemTrustStore=1
and make sure that you do not specify a custom trust store or a Java system property trust store. If a trust store is also specified using the Java system property javax.net.ssl.trustStore
, it is ignored, which ensures the driver only uses certificates from the default JDK trust store.
Trust store order of precedence
The driver uses the following order of precedence to determine which trust store to use:
- The custom trust store specified in the
SSLTrustStore
connection property - The trust store specified in the Java system property
javax.net.ssl.trustStore
(whenUseSystemTrustStore=1
) - The JDK's default trust store (cacerts)
Security recommendations
To keep your connection secure, Databricks recommends the following:
-
For production environments:
- Do not use self-signed certificate mode (
AllowSelfSignedCerts=1
). - Use official CA-signed certificates.
- Use
UseSystemTrustStore=1
unless you need a custom trust store.
- Do not use self-signed certificate mode (
-
For custom trust stores:
- Use when connecting to servers with certificates not in the default trust store.
- Ensure the trust store contains the complete certificate chain.
- Protect trust store files with appropriate permissions.
SQL Configuration Properties
The following SQL configuration properties are supported by the Databricks JDBC Driver (OSS). These are also described in Configuration parameters. Properties are case insensitive.
Property | Default value | Description |
---|---|---|
|
| Whether to enable strict ANSI SQL behavior for certain functions and casting rules. |
|
| Whether to enable the Photon vectorized query engine. |
|
| The methods used to parse and format dates and timestamps. Valid values are |
|
| The maximum number of bytes to pack into a single partition when reading from file based sources. The setting can be any positive integer and optionally include a measure such as |
|
| Controls whether an external metastore is treated as read-only. |
|
| Sets a SQL statement timeout between 0 and 172800 seconds. |
|
| Set the local timezone. Region IDs in the form |
|
| Whether Databricks SQL caches and reuses results whenever possible. |
Logging Properties
The following logging properties are supported by the Databricks JDBC Driver (OSS). Properties are case insensitive.
Property | Default value | Description |
---|---|---|
|
| The logging level, which is a value 0 through 6:
Use this property to enable or disable logging in the connector and to specify the amount of detail included in log files. |
| To determine the default path for logs, the driver uses the value set for these system properties, in this priority order:
| The full path to the folder where the connector saves log files when logging is enabled, as a string. To ensure that the connection URL is compatible with all JDBC applications, escape the backslashes ( If the |
| No maximum | The maximum allowed log file size, specified in MB |
| No maximum | The maximum number of allowed log files |
Enable and configure logging
The JDBC driver supports the Simple Logging Facade for Java (SLF4J) and java.util.logging (JUL) frameworks. The driver uses the JUL logging framework by default.
To enable and configure logging for the JDBC driver:
-
Enable the logging framework that you want to use:
- For SLF4J logging, set the system property
-Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER
and provide the SLF4J binding implementation (compatible with SLF4J version 2.0.13 and above) and corresponding configuration file in the classpath. - For JUL logging, set the system property
-Dcom.databricks.jdbc.loggerImpl=JDKLOGGER
. This is the default.
- For SLF4J logging, set the system property
-
Set the
LogLevel
property on the connection string to the desired level of information to include in log files. -
Set the
LogPath
property on the connection string to the full path to the folder where you want to save log files.For example, the following connection URL enables logging level 6 and saves the log files to the C:temp folder:
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
-
Restart your JDBC application and reconnect to the server to apply the settings.
Other Feature Properties
The following properties enable features in the Databricks JDBC Driver (OSS). Properties are case insensitive.
Property | Default value | Description |
---|---|---|
|
| If set to |
|
| If set to |
|
| The User-Agent entry to be included in the HTTP request. This value is in the following format: |
|
| Whether the JDBC driver should use the Thrift client or Statement Execution APIs. |
| `` | The comma separated list of allowed local paths for downloading and uploading of UC Volume Ingestion files. The paths include sub-directories as well. See Manage files using volumes. |
|
| The comma separated list of retryable HTTP codes for Unity Catalog volume ingestion. |
|
| The retry timeout in minutes for Unity Catalog volume ingestion HTTP requests. |
Telemetry Collection
Telemetry enables Databricks to streamline debugging and provide timely troubleshooting by collecting:
- Client environment details (driver version, runtime, OS details)
- JDBC connection configurations (excludes any PII data)
- Operation latency measurements
- Execution result format (inline JSON, Arrow, etc.)
- Operation types (execution query, metadata query, volume operations)
- Error classification data
- Retry counts
Databricks maintains strict privacy standards ensuring no collection of query content, results, or personally identifiable information (PII).