Databricks OSS ODBC Driver

Beta

The Databricks OSS ODBC Driver, version 0.5.0, is in Beta. For information about the generally available version 2.x driver, see Databricks ODBC Driver documentation.

To report a problem or request a feature while the driver is in Beta, contact your Databricks account team.

The Databricks OSS ODBC Driver is an ODBC 3.8 driver for Databricks SQL and Lakehouse//RT warehouses. It is designed to be a compatible replacement for Databricks ODBC Driver version 2.x for supported workloads. Existing applications, DSNs, and connection strings that use common 2.x functionality should generally work without changes.

Requirements

The Databricks OSS ODBC Driver and Databricks ODBC Driver version 2.x use the same registered ODBC driver name, package identifiers, installation paths, and library names. Installing one version over the other replaces the existing installation. To switch drivers, reinstall the package for the version that you want to use.

The Databricks OSS ODBC Driver is supported on the following platforms:

Operating system	Package and architecture	Requirement
Windows	MSI for x64 and x86	The driver architecture must match the application architecture.
macOS	Universal .pkg for Intel and Apple silicon	macOS 13.3 or above.
Linux	.deb and .rpm for x86_64, aarch64, and i686	glibc 2.28 or above and a compatible ODBC driver manager.

Operating system	Package and architecture	Requirement
Windows	MSI for x64 and x86	The driver architecture must match the application architecture.
macOS	Universal .pkg for Intel and Apple silicon	macOS 13.3 or above.
Linux	.deb and .rpm for x86_64, aarch64, and i686	glibc 2.28 or above and a compatible ODBC driver manager.

You also need the Server Hostname and HTTP Path for a Databricks SQL or Lakehouse//RT warehouse. See Get connection details for a Databricks compute resource.

Install the Databricks OSS ODBC Driver

1. On the Databricks OSS ODBC Driver archive, download the Databricks OSS ODBC Driver version 0.5.0 for your operating system and architecture.
2. Install the downloaded package:

   • On Windows, extract the download and run the 32-bit or 64-bit MSI. The installer registers Databricks ODBC Driver with the Windows ODBC Driver Manager.

   • On macOS, run DatabricksODBC-<version>-macOS.pkg.

   • On Linux, install the .deb or .rpm package and register the driver with unixODBC:

     Bash

     sudo odbcinst -i -d -f /opt/databricks/databricksodbc/Setup/odbcinst.ini

The driver libraries are installed in the same locations as version 2.x:

• Windows 64-bit: C:\Program Files\Databricks ODBC Driver\lib\databricksodbc64.dll
• Windows 32-bit: C:\Program Files (x86)\Databricks ODBC Driver\lib\databricksodbc32.dll
• macOS: /Library/databricks/databricksodbc/lib/libdatabricksodbc.dylib
• Linux 64-bit: /opt/databricks/databricksodbc/lib/64/libdatabricksodbc64.so
• Linux 32-bit: /opt/databricks/databricksodbc/lib/32/libdatabricksodbc32.so

Configure a connection

Start with your existing 2.x DSN or connection string. Common properties such as Driver, Host, Port, HTTPPath, SSL, Catalog, and Schema are compatible. The driver also accepts common 2.x properties that are not needed on its HTTP transport so that existing DSNs can be reused.

To create a DSN or a DSN-less connection string with these settings, see Create an ODBC DSN for the Databricks ODBC Driver or Create an ODBC DSN-less connection string for the Databricks ODBC Driver.

For a new connection, use the properties in the following example. For a DSN, enter the same key-value pairs using your ODBC driver manager.

The following example uses OAuth user-to-machine (U2M) authentication. Line breaks are included for readability. Do not include them in the connection string:

ini

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
AuthMech=11;
Auth_Flow=2;
Catalog=main;
Schema=default

The following authentication methods are supported:

Authentication method	Properties
OAuth user-to-machine (U2M)	AuthMech=11;Auth_Flow=2. PWD is not required. Persistent token caching is enabled by default. Set EnableTokenCache=0 to disable it, or set TokenCachePassPhrase to use a passphrase when encrypting the cache.
OAuth machine-to-machine (M2M)	AuthMech=11;Auth_Flow=1;Auth_Client_ID=<client-id>;Auth_Client_Secret=<client-secret>.
OAuth token pass-through	AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>.
Databricks personal access token	AuthMech=3;UID=token;PWD=<personal-access-token>.

Authentication method	Properties
OAuth user-to-machine (U2M)	AuthMech=11;Auth_Flow=2. PWD is not required. Persistent token caching is enabled by default. Set EnableTokenCache=0 to disable it, or set TokenCachePassPhrase to use a passphrase when encrypting the cache.
OAuth machine-to-machine (M2M)	AuthMech=11;Auth_Flow=1;Auth_Client_ID=<client-id>;Auth_Client_Secret=<client-secret>.
OAuth token pass-through	AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>.
Databricks personal access token	AuthMech=3;UID=token;PWD=<personal-access-token>.

Migrate from version 2.x

1. Review the known limitations for features used by your application.
2. Record the installed 2.x version and back up your DSNs, connection strings, and driver configuration files.
3. Install the Databricks OSS ODBC Driver.
4. Reuse your existing DSN or connection string.
5. Test connection creation, metadata discovery, prepared statements, parameter binding, cancellation, large result retrieval, and representative application workflows.

The Databricks OSS ODBC Driver can report more specific Databricks type names and declared decimal precision and scale than 2.x. Validate applications that compare metadata values exactly.

To roll back after replacing an installation, reinstall the required 2.x package and restore the backed-up configuration.

Known limitations

The following limitations apply while the driver is in Beta:

• The driver supports Databricks SQL and Lakehouse//RT warehouses. It does not support all-purpose compute.
• SQL is always sent directly to Databricks. The driver does not perform the SQL-92 translation available in 2.x. UseNativeQuery is accepted for compatibility but does not change behavior.
• Asynchronous execution through SQL_ATTR_ASYNC_ENABLE and SQLCompleteAsync is not supported.
• PUT, GET, and REMOVE operations for files in Unity Catalog volumes are not supported.
• Binary input parameters are not supported.
• Parameter arrays, including pyodbc fast_executemany with string and Unicode values, are supported, but the driver sends one execution request per row.
• Large results use Cloud Fetch automatically and cannot be forced inline. Result retrieval supports Databricks SQL data types except FILE and OBJECT. Complex values are returned as text.
• HTTPS proxies support basic authentication, but not Kerberos or SPNEGO authentication.
• Certificate revocation configuration and encrypted mutual TLS private keys are not supported.
• Some advanced 2.x properties are not supported. The driver logs a warning when a property is not applied.