Firebolt Python SDK

1.18.5 · active · verified Thu Apr 16

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.

Common errors

```
firebolt.client.firebolt_client.FireboltClientError: Failed to refresh token. Credentials are invalid.
```
cause Incorrect or expired `client_id` or `client_secret` (or username/password) provided for authentication with Firebolt.

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.
```
firebolt.db.exceptions.OperationalError: (Error Code: 1000, Message: Database 'my_db' not found or not accessible.)
```
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.

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.
```
ModuleNotFoundError: No module named 'firebolt.db'
```
cause The `firebolt-sdk` library is not installed or not available in the current Python environment where the code is being executed.

fix Install the library using `pip install firebolt-sdk`. If you are using a virtual environment, ensure it is activated before installation and execution.
```
ValueError: account_name, database, engine_name, client_id, client_secret (or username/password) must be set.
```
cause One or more of the required connection parameters (account name, database, engine name, and authentication credentials) were not provided to the `Connection` constructor.

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()`.

Warnings

gotcha 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.
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`.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install firebolt-sdk Install latest version

Imports

Connection
```
from firebolt.db import Connection
```
Cursor
```
from firebolt.db import Connection
```

Quickstart

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.

import os
from firebolt.db import Connection
from firebolt.db.exceptions import OperationalError

# Ensure these environment variables are set:
# FIREBOLT_CLIENT_ID, FIREBOLT_CLIENT_SECRET, FIREBOLT_ACCOUNT_NAME
# FIREBOLT_DATABASE, FIREBOLT_ENGINE_NAME

try:
    connection = Connection(
        database=os.environ.get("FIREBOLT_DATABASE"),
        engine_name=os.environ.get("FIREBOLT_ENGINE_NAME"),
        client_id=os.environ.get("FIREBOLT_CLIENT_ID"),
        client_secret=os.environ.get("FIREBOLT_CLIENT_SECRET"),
        account_name=os.environ.get("FIREBOLT_ACCOUNT_NAME")
    )

    with connection.cursor() as cursor:
        cursor.execute("SELECT 1 as one, 'hello' as greeting")
        result = cursor.fetchone()
        print(f"Query result: {result}")

        cursor.execute("SHOW ENGINES")
        engines = cursor.fetchall()
        print(f"First 3 engines: {engines[:3]}")

except OperationalError as e:
    print(f"Firebolt Operational Error: {e}")
    print("Please ensure your credentials, database, and engine are correct.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →