{"id":9638,"library":"databricks-sql","title":"Databricks SQL","description":"Databricks SQL is a Python framework designed for easy interaction with Databricks SQL Endpoints. It provides a fluent API for building and executing SQL queries, simplifying data operations for Python developers. The library recently reached version 1.0.0, indicating a stable API after rapid initial development.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/bernardocouto/databricks-sql","tags":["databricks","sql","database","data-engineering","etl"],"install":[{"cmd":"pip install databricks-sql","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This library wraps the functionality of databricks-api for underlying communication with Databricks.","package":"databricks-api","optional":false}],"imports":[{"symbol":"DatabricksSQL","correct":"from databricks_sql import DatabricksSQL"}],"quickstart":{"code":"import os\nfrom databricks_sql import DatabricksSQL\n\n# Ensure these environment variables are set for authentication\n# DATABRICKS_SERVER_HOSTNAME (e.g., 'dbc-xxxx.cloud.databricks.com')\n# DATABRICKS_HTTP_PATH (e.g., '/sql/1.0/endpoints/xxxx')\n# DATABRICKS_ACCESS_TOKEN (Databricks personal access token)\n\n# Initialize the DatabricksSQL client\ndb_sql = DatabricksSQL(\n    server_hostname=os.environ.get(\"DATABRICKS_SERVER_HOSTNAME\", \"\"),\n    http_path=os.environ.get(\"DATABRICKS_HTTP_PATH\", \"\"),\n    access_token=os.environ.get(\"DATABRICKS_ACCESS_TOKEN\", \"\")\n)\n\ntry:\n    # Example: Select data from a table named 'users'\n    # Replace 'your_schema.users' with an actual table in your Databricks workspace\n    result = db_sql.select(\"id\", \"name\").from_table(\"your_schema.users\").limit(5).fetch_all()\n    print(\"Fetched data:\")\n    for row in result:\n        print(row)\n\n    # Example: Insert data (if table allows)\n    # db_sql.insert().into_table(\"your_schema.new_users\").columns(\"id\", \"name\").values(1, \"Alice\").execute()\n    # print(\"Data inserted.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your Databricks connection details (server_hostname, http_path, access_token) are correctly configured.\")\n","lang":"python","description":"This quickstart demonstrates how to connect to Databricks SQL using environment variables for authentication and perform a simple SELECT query. Replace `your_schema.users` with an actual table in your Databricks workspace. It highlights the fluent API pattern for query construction."},"warnings":[{"fix":"Ensure all imports are `from databricks_sql import ...`.","message":"The internal module name was changed in version 0.0.1. While unlikely to affect many users given the library's recency, it means any code written for version 0.0.0 would have broken import paths.","severity":"breaking","affected_versions":"0.0.0 to 0.0.1+"},{"fix":"Verify that `DATABRICKS_SERVER_HOSTNAME`, `DATABRICKS_HTTP_PATH`, and `DATABRICKS_ACCESS_TOKEN` environment variables are correctly set, or pass the credentials directly as arguments to `DatabricksSQL()`.","message":"Failing to provide correct Databricks connection parameters (server hostname, HTTP path, access token) will lead to authentication errors from the underlying `databricks-api` library. This is the most common cause of initial connection failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always append an execution method at the end of your query chain, e.g., `db_sql.select(...).from_table(...).fetch_all()`.","message":"The query builder methods (e.g., `select`, `from_table`, `where`) return builder objects. You must call a terminal execution method like `.fetch_all()`, `.fetch_one()`, `.fetch_dataframe()`, or `.execute()` to run the query and retrieve results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When debugging connection or low-level API issues, consider reviewing the `databricks-api` documentation or source code.","message":"This library relies on `databricks-api`. Specific error messages or behaviors related to connectivity, authentication, or underlying API calls might originate from `databricks-api` itself. Consult its documentation for deeper troubleshooting if `databricks-sql` errors are unclear.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install databricks-sql` to install the library.","cause":"The `databricks-sql` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'databricks_sql'"},{"fix":"Ensure your query chain ends with a method that executes the query and retrieves data, for example: `result = db_sql.select(...).from_table(...).fetch_all()`. Then, iterate over `result` to access rows/columns.","cause":"You are attempting to access data attributes directly from a query builder object instead of the query results. This happens when you forget to call an execution method like `.fetch_all()`.","error":"AttributeError: 'SelectCommandBuilder' object has no attribute 'id' (or any column name)"},{"fix":"Double-check the values for `DATABRICKS_SERVER_HOSTNAME`, `DATABRICKS_HTTP_PATH`, and `DATABRICKS_ACCESS_TOKEN` in your environment variables or the `DatabricksSQL` constructor. Ensure the access token is valid and has sufficient permissions.","cause":"The provided Databricks authentication details (server hostname, HTTP path, or access token) are incorrect or missing, preventing a successful connection to the Databricks SQL Endpoint.","error":"databricks_api.auth.auth.DatabricksAuthException: Could not authenticate with Databricks. Please check your credentials."}]}