firebolt-sdk

library1.18.6pypypi✓ verified 86d ago

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.

database

pip install firebolt-sdk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FIREBOLT-SDK

firebolt-sdk

databasepythonv1.18.6

Install

6.1s avg

Import

1430ms

Disk

56MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.18.6 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.418s · 57.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 6.1s · import 1.441s · 57MB

56MB installed

● package 56MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Connection

✓ from firebolt.db import Connection

Cursor

✓ from firebolt.db import Connection

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}")

Debug

Known issues

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

affects: All versions

gotchaIt 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.

affects: All versions

gotchaThe 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.

affects: All versions, especially prior to 1.18.5

Errors

Common errors & fixes

firebolt.client.firebolt_client.FireboltClientError: Failed to refresh token. Credentials are invalid.

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

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'

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.

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

Upgrade

Version history

1.18.6latest on PyPI · released Apr 16, 2026

Audit

Dependencies

aiohttprequiredAsynchronous HTTP client for network communication.

pyjwtrequiredJSON Web Token implementation for authentication.

requestsrequiredHTTP client for synchronous network communication (legacy paths).

sqlparserequiredSQL parser for query splitting and formatting.

tqdmrequiredProgress bar for iterating, often used in data loading.

urllib3requiredHTTP client library, a dependency for 'requests'.

certifirequiredMozilla's collection of SSL certificates.

dataclasses-jsonrequiredMixin for dataclasses to support JSON serialization/deserialization.

Agent activity

16 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/firebolt-db/firebolt-sdk ↗

packagehttps://pypi.org/project/firebolt-sdk/ ↗

homepagehttps://www.firebolt.io ↗