{"id":7227,"library":"firebolt-sdk","title":"Firebolt Python SDK","description":"The Firebolt Python SDK provides a Python Database API Specification (DB-API 2.0) compliant interface for connecting and interacting with Firebolt, a cloud data warehouse. It enables executing SQL queries, managing connections, and fetching results programmatically. The current version is 1.18.5, with frequent patch releases addressing bug fixes and minor improvements, and occasional minor version bumps for new features.","status":"active","version":"1.18.5","language":"en","source_language":"en","source_url":"https://github.com/firebolt-db/firebolt-python-sdk","tags":["database","firebolt","sql","data warehouse","dbapi","analytics"],"install":[{"cmd":"pip install firebolt-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Asynchronous HTTP client for network communication.","package":"aiohttp"},{"reason":"JSON Web Token implementation for authentication.","package":"pyjwt"},{"reason":"HTTP client for synchronous network communication (legacy paths).","package":"requests"},{"reason":"SQL parser for query splitting and formatting.","package":"sqlparse"},{"reason":"Progress bar for iterating, often used in data loading.","package":"tqdm"},{"reason":"HTTP client library, a dependency for 'requests'.","package":"urllib3"},{"reason":"Mozilla's collection of SSL certificates.","package":"certifi"},{"reason":"Mixin for dataclasses to support JSON serialization/deserialization.","package":"dataclasses-json"}],"imports":[{"symbol":"Connection","correct":"from firebolt.db import Connection"},{"symbol":"Cursor","correct":"from firebolt.db import Connection"}],"quickstart":{"code":"import os\nfrom firebolt.db import Connection\nfrom firebolt.db.exceptions import OperationalError\n\n# Ensure these environment variables are set:\n# FIREBOLT_CLIENT_ID, FIREBOLT_CLIENT_SECRET, FIREBOLT_ACCOUNT_NAME\n# FIREBOLT_DATABASE, FIREBOLT_ENGINE_NAME\n\ntry:\n    connection = Connection(\n        database=os.environ.get(\"FIREBOLT_DATABASE\"),\n        engine_name=os.environ.get(\"FIREBOLT_ENGINE_NAME\"),\n        client_id=os.environ.get(\"FIREBOLT_CLIENT_ID\"),\n        client_secret=os.environ.get(\"FIREBOLT_CLIENT_SECRET\"),\n        account_name=os.environ.get(\"FIREBOLT_ACCOUNT_NAME\")\n    )\n\n    with connection.cursor() as cursor:\n        cursor.execute(\"SELECT 1 as one, 'hello' as greeting\")\n        result = cursor.fetchone()\n        print(f\"Query result: {result}\")\n\n        cursor.execute(\"SHOW ENGINES\")\n        engines = cursor.fetchall()\n        print(f\"First 3 engines: {engines[:3]}\")\n\nexcept OperationalError as e:\n    print(f\"Firebolt Operational Error: {e}\")\n    print(\"Please ensure your credentials, database, and engine are correct.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to Firebolt using service account credentials (client ID/secret) and execute a simple query. It relies on environment variables for sensitive information, which is a recommended practice. The DB-API 2.0 compliant `Connection` and `Cursor` objects are used to interact with the database."},"warnings":[{"fix":"Prefer setting `FIREBOLT_CLIENT_ID` and `FIREBOLT_CLIENT_SECRET` environment variables or passing them directly to the `Connection` constructor over `FIREBOLT_USERNAME` and `FIREBOLT_PASSWORD`.","message":"The SDK primarily supports service account authentication (client_id and client_secret). While username and password might still work for some accounts, client_id/secret is the recommended and more robust method, especially for programmatic access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure `FIREBOLT_ENGINE_NAME` and `FIREBOLT_DATABASE` environment variables are set or explicitly pass `engine_name` and `database` parameters to the `Connection` constructor.","message":"It is crucial to specify both `engine_name` and `database` when establishing a connection. Omitting or providing incorrect values for either can lead to connection failures, queries running against unintended databases, or unexpected errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Simplify complex SQL statements where possible. Test queries thoroughly, especially those with intricate syntax. Ensure you are on the latest patch version of the SDK, as `sqlparse` related fixes are often included.","message":"The SDK relies on `sqlparse` for internal query splitting and parameter substitution. Highly complex, malformed, or unusual SQL syntax (e.g., `CASE ... END` within string literals, deeply nested queries, or specific comment styles) may occasionally lead to parsing issues, causing query execution failures or incorrect parameter handling. This has been a source of fixes in recent versions.","severity":"gotcha","affected_versions":"All versions, especially prior to 1.18.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Double-check your Firebolt service account credentials or user credentials. Ensure they are correctly set as environment variables (e.g., `FIREBOLT_CLIENT_ID`, `FIREBOLT_CLIENT_SECRET`) or passed explicitly to the `Connection` constructor.","cause":"Incorrect or expired `client_id` or `client_secret` (or username/password) provided for authentication with Firebolt.","error":"firebolt.client.firebolt_client.FireboltClientError: Failed to refresh token. Credentials are invalid."},{"fix":"Verify the exact database and engine names in your Firebolt account. Confirm that the credentials used have appropriate permissions to access the specified resources.","cause":"The specified `database` or `engine_name` does not exist, is misspelled, or the connected user/service account does not have access to it within the given Firebolt account.","error":"firebolt.db.exceptions.OperationalError: (Error Code: 1000, Message: Database 'my_db' not found or not accessible.)"},{"fix":"Install the library using `pip install firebolt-sdk`. If you are using a virtual environment, ensure it is activated before installation and execution.","cause":"The `firebolt-sdk` library is not installed or not available in the current Python environment where the code is being executed.","error":"ModuleNotFoundError: No module named 'firebolt.db'"},{"fix":"Ensure all necessary parameters are supplied. This can be done by setting corresponding environment variables (e.g., `FIREBOLT_ACCOUNT_NAME`, `FIREBOLT_DATABASE`, `FIREBOLT_ENGINE_NAME`, `FIREBOLT_CLIENT_ID`, `FIREBOLT_CLIENT_SECRET`) or by passing them directly as keyword arguments to `Connection()`.","cause":"One or more of the required connection parameters (account name, database, engine name, and authentication credentials) were not provided to the `Connection` constructor.","error":"ValueError: account_name, database, engine_name, client_id, client_secret (or username/password) must be set."}]}