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