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. For executing queries asynchronously server-side see Server-side asynchronous query execution.

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', 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], system_engine_connection: Connection | None, api_endpoint: str)

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
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 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: HttpxAsyncClient, 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

cancel(query_id: str) None

Cancel a server-side async query.

connection
property database: str | None
execute(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False, async_execution: bool | None = False) 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

  • async_execution (bool) – flag to determine if query should be asynchronous

Returns:

Query row count.

Return type:

int

executemany(query: str, parameters_seq: Sequence[Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes]], async_execution: bool | None = False) 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.

  • async_execution (bool) – flag to determine if query should be asynchronous

Returns:

Query row count for synchronous execution of queries, query ID string for asynchronous execution.

Return type:

int|str

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.

get_status(query_id: str) QueryStatus

Get status of a server-side async query. Return the state of the query.

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
parameters: Dict[str, str]
class firebolt.async_db.cursor.CursorV2(*args: Any, client: AsyncClientV2, connection: Connection, **kwargs: Any)

Bases: Cursor

connection
parameters: Dict[str, str]

Util