Install & Compatibility
Where this runs
tested against v0.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 16.5s · import 0.502s · 358MB
364MB installed
● package 364MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
The `sqlalchemy-databricks` package registers the 'databricks://' dialect automatically upon import, making it available for `create_engine`.
text
✓ from sqlalchemy import text
Used for executing raw SQL queries with SQLAlchemy Core.
This quickstart demonstrates how to establish a connection to a Databricks SQL Endpoint using `sqlalchemy-databricks`. It uses environment variables for sensitive connection details and executes a simple `SELECT 1` query to verify connectivity. Ensure your Databricks SQL Endpoint is running and your token has the necessary permissions.
from sqlalchemy import create_engine, text
import os
# Databricks connection details
# These are typically found in the Databricks SQL Endpoint connection details.
# server_hostname is like 'dbc-xxxxxxxx-yyyy.cloud.databricks.com'
# http_path is like '/sql/1.0/endpoints/zzzzzzzzzzzzzzzz'
# token is a Databricks Personal Access Token or Azure AD Token
DATABRICKS_SERVER_HOSTNAME = os.environ.get('DATABRICKS_SERVER_HOSTNAME', 'your_databricks_hostname')
DATABRICKS_HTTP_PATH = os.environ.get('DATABRICKS_HTTP_PATH', 'your_http_path')
DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN', 'your_databricks_token')
# Construct the connection string
connection_string = f"databricks://token:{DATABRICKS_TOKEN}@{DATABRICKS_SERVER_HOSTNAME}/{DATABRICKS_HTTP_PATH}"
# Create the engine
try:
engine = create_engine(connection_string)
# Establish a connection and execute a simple query
with engine.connect() as connection:
result = connection.execute(text("SELECT 1")) # Simple test query
print("Connection successful! Query result:", result.scalar())
print("\nSuccessfully connected to Databricks and executed a query.")
except Exception as e:
print(f"Error connecting to Databricks: {e}")
print("Please ensure DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN environment variables are set correctly.")
Debug
Known issues
gotchaIncorrect `server_hostname` or `http_path` format in the connection string is a frequent cause of connection failures. The dialect expects these to be correctly extracted from your Databricks SQL Endpoint details.fixAlways double-check the "Connection Details" tab of your Databricks SQL Endpoint for the exact `server_hostname` and `http_path` values. The `http_path` should typically start with `/sql/1.0/endpoints/`.
affects: All versions
gotchaVersion 0.2.0 fixed handling of `server_hostname` and `http_path` in the connection string. Users upgrading from 0.1.0 who had workarounds for previously incorrect parsing might experience connection issues if their connection string no longer aligns with the corrected parsing logic.fixVerify your connection string against the official documentation examples for `0.2.0`, especially the `server_hostname` and `http_path` components, even if it worked in `0.1.0`.
affects: Upgrading from 0.1.0 to 0.2.0
gotchaWhile `sqlalchemy-databricks` pins a compatible range, breaking changes or specific issues in the underlying `databricks-sql-connector` can impact connections or query execution.fixIf encountering low-level connection issues, ensure your `databricks-sql-connector` version is within the compatible range (currently `>=2.0.0`) and check its release notes for any relevant changes. Consider explicitly installing the exact version pinned by `sqlalchemy-databricks` if issues persist.
affects: All versions of `sqlalchemy-databricks` relying on the connector.
gotchaConnections will fail if the target Databricks SQL Endpoint is not running. This is an external dependency issue.fixVerify the status of your Databricks SQL Endpoint in the Databricks workspace UI and ensure it is in a 'Running' state before attempting to connect.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlalchemy_databricks'
The `sqlalchemy-databricks` package is not installed in the Python environment where the code is being executed.
fixInstall the package using pip: `pip install sqlalchemy-databricks`
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:databricks
SQLAlchemy cannot find or load the 'databricks' dialect plugin, often due to an incomplete or corrupted installation of the `sqlalchemy-databricks` package.
fixEnsure the package is correctly installed, potentially by reinstalling it: `pip install --force-reinstall sqlalchemy-databricks`
databricks.sql.exc.DatabricksOperationalError: [databricks-sql-python][Databricks] HTTP Path: /sql/1.0/endpoints/<endpoint_id> not found.
The provided Databricks connection parameters, specifically the `http_path` in the SQLAlchemy URL, are incorrect or refer to an inaccessible Databricks SQL Endpoint.
fixVerify that the `host_name`, `http_path`, and `personal_access_token` in your connection string are accurate and correspond to an active Databricks SQL Endpoint with appropriate permissions.
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:databricks.pyodbc
The `databricks+pyodbc` dialect driver cannot be loaded because either the `pyodbc` Python package or the underlying Databricks ODBC driver is not installed or configured on the system.
fixInstall the `pyodbc` Python package (`pip install pyodbc`) and ensure the Databricks ODBC driver is installed and correctly configured on your operating system.
Upgrade
Version history
0.2.0latest on PyPI · released May 6, 2022
Audit
Dependencies
sqlalchemyrequiredCore dependency as it's a SQLAlchemy dialect.
databricks-sql-connectorrequiredUnderlying Python connector for Databricks SQL Endpoints.