Async db

The async_db package enables asynchronous API calls to a Firebolt database, allowing client-side processes to continue to run while waiting for API responses.

connect

async firebolt.async_db.connection.connect(auth: Auth | None = None, account_name: str | None = None, database: str | None = None, engine_name: str | None = None, engine_url: str | None = None, api_endpoint: str = 'api.app.firebolt.io', disable_cache: bool = False, additional_parameters: Dict[str, Any] = {}) → Connection

Connection

Note

Do not use connection directly. Instead, use connect as shown above.

class firebolt.async_db.connection.Connection(engine_url: str, database: str | None, client: AsyncClient, cursor_type: Type[Cursor], api_endpoint: str, init_parameters: Dict[str, Any] | None = None)

Bases: BaseConnection

Firebolt asynchronous database connection class. Implements PEP 249.

Parameters:

  • engine_url – Firebolt database engine REST API url

  • database – Firebolt database name

  • username – Firebolt account username

  • password – Firebolt account password

  • api_endpoint – Optional. Firebolt API endpoint used for authentication

  • connector_versions – Optional. Tuple of connector name and version, or a list of tuples of your connector stack. Useful for tracking custom connector usage.

Note

Firebolt does not support transactions, so commit and rollback methods are not implemented.

async aclose() → None

Close connection and all underlying cursors.

api_endpoint
async cancel_async_query(token: str) → None

Cancel an async query.

Parameters:

token – Async query token. Can be obtained from Cursor.async_query_token.

client_class: type
property closed: bool

True if connection is closed; False otherwise.

commit() → None

Does nothing since Firebolt doesn’t have transactions.

cursor(**kwargs: Any) → Cursor
cursor_type: Type[Cursor]
database
engine_url
async is_async_query_running(token: str) → bool

Check if an async query is still running.

Parameters:

token – Async query token. Can be obtained from Cursor.async_query_token.

Returns:

True if async query is still running, False otherwise

Return type:

bool

async is_async_query_successful(token: str) → bool | None

Check if an async query has finished and was successful.

Parameters:

token – Async query token. Can be obtained from Cursor.async_query_token.

Returns:

None if the query is still running, True if successful,

False otherwise

Return type:

bool

async firebolt.async_db.connection.connect_v1(auth: Auth, user_agent_header: str, database: str | None = None, account_name: str | None = None, engine_name: str | None = None, engine_url: str | None = None, api_endpoint: str = 'api.app.firebolt.io') → Connection
async firebolt.async_db.connection.connect_v2(auth: Auth, user_agent_header: str, account_name: str | None = None, database: str | None = None, engine_name: str | None = None, api_endpoint: str = 'api.app.firebolt.io') → Connection

Connect to Firebolt.

Parameters:

  • auth (Auth)

  • database (str) – Name of the database to connect

  • engine_name (Optional[str]) – Name of the engine to connect to

  • account_name (Optional[str]) – For customers with multiple accounts; if none, default is used

  • api_endpoint (str) – Firebolt API endpoint. Used for authentication

  • additional_parameters (Optional[Dict]) – Dictionary of less widely-used arguments for connection

Cursor

class firebolt.async_db.cursor.Cursor(*args: Any, client: AsyncClient, connection: Connection, **kwargs: Any)

Bases: BaseCursor

Class, responsible for executing queries to Firebolt Database. Should not be created directly, use connection.cursor

Parameters:

  • description – Information about a single result row

  • rowcount – The number of rows produced by last query

  • closed – True if connection is closed, False otherwise

  • arraysize – Read/Write, specifies the number of rows to fetch at a time with the fetchmany() method

connection
engine_url
execute(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False, timeout_seconds: float | None = None) → int | str

Prepare and execute a database query.

Supported features:
Parameterized queries: placeholder characters (‘?’) are substituted

with values provided in parameters. Values are formatted to be properly recognized by database and to exclude SQL injection.

Multi-statement queries: multiple statements, provided in a single query

and separated by semicolon, are executed separatelly and sequentially. To switch to next statement result, nextset method should be used.

SET statements: to provide additional query execution parameters, execute

SET param=value statement before it. All parameters are stored in cursor object until it’s closed. They can also be removed with flush_parameters method call.

Parameters:

  • query (str) – SQL query to execute

  • parameters (Optional[Sequence[ParameterType]]) – A sequence of substitution parameters. Used to replace ‘?’ placeholders inside a query with actual values

  • skip_parsing (bool) – Flag to disable query parsing. This will disable parameterized, multi-statement and SET queries, while improving performance

  • timeout_seconds (Optional[float]) – Query execution timeout in seconds

Returns:

Query row count.

Return type:

int

abstract async execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) → int

Execute a database query without maintaining a connection.

executemany(query: str, parameters_seq: Sequence[Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes]], timeout_seconds: float | None = None) → int | str

Prepare and execute a database query.

Supports providing multiple substitution parameter sets, executing them as multiple statements sequentially.

Supported features:
Parameterized queries: Placeholder characters (‘?’) are substituted

with values provided in parameters. Values are formatted to be properly recognized by database and to exclude SQL injection.

Multi-statement queries: Multiple statements, provided in a single query

and separated by semicolon, are executed separately and sequentially. To switch to next statement result, use nextset method.

SET statements: To provide additional query execution parameters, execute

SET param=value statement before it. All parameters are stored in cursor object until it’s closed. They can also be removed with flush_parameters method call.

Parameters:

  • query (str) – SQL query to execute.

  • parameters_seq (Sequence[Sequence[ParameterType]]) – A sequence of substitution parameter sets. Used to replace ‘?’ placeholders inside a query with actual values from each set in a sequence. Resulting queries for each subset are executed sequentially.

  • timeout_seconds (Optional[float]) – Query execution timeout in seconds.

Returns:

Query row count.

Return type:

int

async fetchall() → List[List[int | float | str | datetime | date | bool | list | Decimal | None | bytes]]

Fetch all remaining rows of a query result.

async fetchmany(size: int | None = None) → List[List[int | float | str | datetime | date | bool | list | Decimal | None | bytes]]

Fetch the next set of rows of a query result; cursor.arraysize is default size.

async fetchone() → List[int | float | str | datetime | date | bool | list | Decimal | None | bytes] | None

Fetch the next row of a query result set.

async nextset() → bool | None

Skip to the next available set, discarding any remaining rows from the current set. Returns True if operation was successful; None if there are no more sets to retrive.

parameters: Dict[str, str]
class firebolt.async_db.cursor.CursorV1(*args: Any, client: AsyncClientV1, connection: Connection, **kwargs: Any)

Bases: Cursor

connection
engine_url
async execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) → int

Execute a database query without maintaining a connection.

parameters: Dict[str, str]
class firebolt.async_db.cursor.CursorV2(*args: Any, client: AsyncClientV2, connection: Connection, **kwargs: Any)

Bases: Cursor

connection
engine_url
execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) → int

Execute a database query without maintating a connection.

Supported features:
Parameterized queries: placeholder characters (‘?’) are substituted

with values provided in parameters. Values are formatted to be properly recognized by database and to exclude SQL injection.

Not supported:
Multi-statement queries: multiple statements, provided in a single query

and separated by semicolon.

SET statements: to provide additional query execution parameters, execute

SET param=value statement before it. Use execute method to set parameters.

Parameters:

  • query (str) – SQL query to execute

  • parameters (Optional[Sequence[ParameterType]]) – A sequence of substitution parameters. Used to replace ‘?’ placeholders inside a query with actual values

  • skip_parsing (bool) – Flag to disable query parsing. This will disable parameterized queries while potentially improving performance

Returns:

Always returns -1, as async execution does not return row count.

Return type:

int

parameters: Dict[str, str]

Util