Databricks SQL Connector Core

4.2.6 verified Mon Apr 27 auth: no python

The core library for connecting Python to Databricks SQL, providing a DB-API 2.0 interface. Currently at version 4.2.6, released frequently (multiple releases per month). Supports Python 3.8 to 3.14. Built on Thrift and Arrow for efficient data transfer.

pip install databricks-sql-connector-core

Common errors

error ModuleNotFoundError: No module named 'databricks' ↓

cause Installed 'databricks-sql-connector-core' but importing incorrectly such as 'import databricks_sql_connector_core'.

fix

Install the package and use 'from databricks import sql'.

error pyarrow.lib.ArrowTypeError: Expected a string or bytes, got a 'NoneType' ↓

cause Passing None for server_hostname or http_path in connect().

fix

Set environment variables or pass non-None strings: server_hostname='abc.cloud.databricks.com', http_path='/sql/1.0/warehouses/...'.

error thrift.transport.TTransport.TTransportException: Could not connect to... ↓

cause Invalid server_hostname or network connectivity issue, or wrong port (default 443 but custom allowed).

fix

Verify server_hostname is correct (e.g., 'adb-...azuredatabricks.net') and that your network can reach the Databricks workspace. Check firewall/proxy settings.

Warnings

breaking Thrift dependency upgrade in 4.x: The library switched from thrift 0.16.0 to 0.19.0. Code that directly imports thrift or uses custom thrift transports may break. ↓

fix Update any custom thrift code to be compatible with thrift 0.19.0. If you encounter 'thrift.protocol.TProtocolException', check your thrift version.

deprecated fetchall_arrow() and fetchmany_arrow() are deprecated in favor of fetchall() and fetchmany() which return Arrow-backed results by default in v4. ↓

fix Replace cursor.fetchall_arrow() with cursor.fetchall(). The returned type is now pyarrow.Table.

gotcha Connection string format: 'databricks-sql-connector-core' does not support connection strings like 'databricks+pyodbc://...'. Use the programmatic connect() method with server_hostname, http_path, and access_token. ↓

fix Do not use SQLAlchemy connection strings directly; use databricks-sql-connector with SQLAlchemy dialect for that.

Install

pip install databricks-sql-connector

Imports

connect
wrong
```
from databricks_sql_connector_core import connect
```
correct
```
from databricks import sql
```
The main package is 'databricks.sql', not the internal core module.

Quickstart

Connect to Databricks SQL with personal access token and run a query.

import os
from databricks import sql

connection = sql.connect(
    server_hostname=os.environ.get('DATABRICKS_SERVER_HOSTNAME', ''),
    http_path=os.environ.get('DATABRICKS_HTTP_PATH', ''),
    access_token=os.environ.get('DATABRICKS_TOKEN', ''),
)
with connection.cursor() as cursor:
    cursor.execute("SELECT 1 as col")
    result = cursor.fetchall()
    print(result)
connection.close()