{"id":5501,"library":"sqlalchemy-databricks","title":"SQLAlchemy Dialect for Databricks","description":"SQLAlchemy-Databricks is a SQLAlchemy dialect for connecting to Databricks. It enables Python applications to interact with Databricks SQL Endpoints and Unity Catalog using the familiar SQLAlchemy ORM or Core API. The current version is 0.2.0, supporting Python 3.8 and above. The release cadence appears to be infrequent, with two major releases to date.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/crflynn/sqlalchemy-databricks","tags":["sqlalchemy","databricks","database","sql","dialect","data-lakehouse"],"install":[{"cmd":"pip install sqlalchemy-databricks","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency as it's a SQLAlchemy dialect.","package":"sqlalchemy"},{"reason":"Underlying Python connector for Databricks SQL Endpoints.","package":"databricks-sql-connector"}],"imports":[{"note":"The `sqlalchemy-databricks` package registers the 'databricks://' dialect automatically upon import, making it available for `create_engine`.","symbol":"create_engine","correct":"from sqlalchemy import create_engine"},{"note":"Used for executing raw SQL queries with SQLAlchemy Core.","symbol":"text","correct":"from sqlalchemy import text"}],"quickstart":{"code":"from sqlalchemy import create_engine, text\nimport os\n\n# Databricks connection details\n# These are typically found in the Databricks SQL Endpoint connection details.\n# server_hostname is like 'dbc-xxxxxxxx-yyyy.cloud.databricks.com'\n# http_path is like '/sql/1.0/endpoints/zzzzzzzzzzzzzzzz'\n# token is a Databricks Personal Access Token or Azure AD Token\n\nDATABRICKS_SERVER_HOSTNAME = os.environ.get('DATABRICKS_SERVER_HOSTNAME', 'your_databricks_hostname')\nDATABRICKS_HTTP_PATH = os.environ.get('DATABRICKS_HTTP_PATH', 'your_http_path')\nDATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN', 'your_databricks_token')\n\n# Construct the connection string\nconnection_string = f\"databricks://token:{DATABRICKS_TOKEN}@{DATABRICKS_SERVER_HOSTNAME}/{DATABRICKS_HTTP_PATH}\"\n\n# Create the engine\ntry:\n    engine = create_engine(connection_string)\n\n    # Establish a connection and execute a simple query\n    with engine.connect() as connection:\n        result = connection.execute(text(\"SELECT 1\")) # Simple test query\n        print(\"Connection successful! Query result:\", result.scalar())\n\n    print(\"\\nSuccessfully connected to Databricks and executed a query.\")\n\nexcept Exception as e:\n    print(f\"Error connecting to Databricks: {e}\")\n    print(\"Please ensure DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN environment variables are set correctly.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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/`.","message":"Incorrect `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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`.","message":"Version 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.","severity":"gotcha","affected_versions":"Upgrading from 0.1.0 to 0.2.0"},{"fix":"If 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.","message":"While `sqlalchemy-databricks` pins a compatible range, breaking changes or specific issues in the underlying `databricks-sql-connector` can impact connections or query execution.","severity":"gotcha","affected_versions":"All versions of `sqlalchemy-databricks` relying on the connector."},{"fix":"Verify the status of your Databricks SQL Endpoint in the Databricks workspace UI and ensure it is in a 'Running' state before attempting to connect.","message":"Connections will fail if the target Databricks SQL Endpoint is not running. This is an external dependency issue.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}