Async_db

The async_db package enables connecting to a Firebolt database for asynchronous queries.

Async_db.connection

class firebolt.async_db.connection.Connection(engine_url: str, database: str, auth: Auth, api_endpoint: str = 'api.app.firebolt.io', additional_parameters: Dict[str, Any] = {})

Bases: BaseConnection

Firebolt asyncronous 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 list of tuples of your connector stack. Useful for tracking custom connector usage.

Note

Firebolt currenly doesn’t support transactions so commit and rollback methods are not implemented.

async aclose() → None

Close connection and all underlying cursors.

api_endpoint

client_class: type

cursor() → Cursor

cursor_class

alias of Cursor

database

engine_url

class firebolt.async_db.connection.OverriddenHttpBackend

Bases: AutoBackend

This class is a short-term solution for TCP keep-alive issue: https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancers.html#connection-idle-timeout Since httpx creates a connection right before executing a request backend has to be overridden in order to set the socket KEEPALIVE and KEEPIDLE settings.

async connect_tcp(host: str, port: int, timeout: Optional[float] = None, local_address: Optional[str] = None) → AsyncNetworkStream

firebolt.async_db.connection.async_connect_factory(connection_class: Type) → Callable

async firebolt.async_db.connection.connect(database: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, access_token: Optional[str] = None, auth: Optional[Auth] = None, engine_name: Optional[str] = None, engine_url: Optional[str] = None, account_name: Optional[str] = None, api_endpoint: str = 'api.app.firebolt.io', use_token_cache: bool = True, additional_parameters: Dict[str, Any] = {}) → Connection

Connect to Firebolt database.

Parameters

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

• username (Optional[str]) – User name to use for authentication (Deprecated)

• password (Optional[str]) – Password to use for authentication (Deprecated)

• access_token (Optional[str]) – Authentication token to use insead of credentials (Deprecated)

• auth (Auth) –

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

• engine_url (Optional[str]) – The engine endpoint to use

• account_name (Optional[str]) – For customers with multiple accounts; if None uses default.

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

• use_token_cache (bool) – Cached authentication token in filesystem. Default: True

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

Note

Providing both engine_name and engine_url would result in an error.

Async_db.cursor

class firebolt.async_db.cursor.Cursor(*args: Any, **kwargs: Any)

Bases: BaseCursor

Class, responsible for executing asyncio 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

async execute(query: str, parameters: Optional[Sequence[Union[int, float, str, datetime, date, bool, Decimal, Sequence]]] = None, set_parameters: Optional[Dict] = None, skip_parsing: bool = False) → int

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

• set_parameters (Optional[Dict]) – List of set parameters to execute a query with. DEPRECATED: Use SET SQL statements instead

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

Returns

Query row count

Return type

int

async executemany(query: str, parameters_seq: Sequence[Sequence[Union[int, float, str, datetime, date, bool, Decimal, Sequence]]]) → int

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

Returns

Query row count

Return type

int

async fetchall() → List[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]

Fetch all remaining rows of a query result.

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

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

async fetchone() → Optional[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]

Fetch the next row of a query result set.

async nextset() → Optional[bool]

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

class firebolt.async_db.cursor.CursorState(value)

Bases: Enum

An enumeration.

CLOSED = 4

DONE = 3

ERROR = 2

NONE = 1

class firebolt.async_db.cursor.Statistics(*, elapsed: float, rows_read: int, bytes_read: int, time_before_execution: float, time_to_execute: float, scanned_bytes_cache: float = None, scanned_bytes_storage: float = None)

Bases: BaseModel

Class for query execution statistics

bytes_read: int

elapsed: float

rows_read: int

scanned_bytes_cache: Optional[float]

scanned_bytes_storage: Optional[float]

time_before_execution: float

time_to_execute: float

firebolt.async_db.cursor.check_not_closed(func: Callable) → Callable

(Decorator) ensure cursor is not closed before calling method.

firebolt.async_db.cursor.check_query_executed(func: Callable) → Callable

Async_db.util

async firebolt.async_db.util.is_db_available(connection: Connection, database_name: str) → bool

Verify if the database exists

async firebolt.async_db.util.is_engine_running(connection: Connection, engine_url: str) → bool

Verify if the engine is running