PooledQldbDriver Reference

class pyqldb.driver.pooled_qldb_driver.PooledQldbDriver(ledger_name, retry_limit=4, read_ahead=0, executor=None, region_name=None, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None, boto3_session=None, pool_limit=0, timeout=30)[source]

Represents a factory for accessing pooled sessions to a specific ledger within QLDB. This class or pyqldb.driver.qldb_driver.QldbDriver should be the main entry points to any interaction with QLDB. pyqldb.driver.pooled_qldb_driver.PooledQldbDriver.get_session() will create a pyqldb.session.pooled_qldb_session.PooledQldbSession to the specified ledger within QLDB as a communication channel. Any acquired sessions must be cleaned up with pyqldb.session.pooled_qldb_session.PooledQldbSession.close() when they are no longer needed in order to return the session to the pool. If this is not done, this driver may become unusable if the pool limit is exceeded.

This factory pools sessions and attempts to return unused but available sessions when getting new sessions. The advantage to using this over the non-pooling driver is that the underlying connection that sessions use to communicate with QLDB can be recycled, minimizing resource usage by preventing unnecessary connections and reducing latency by not making unnecessary requests to start new connections and end reusable, existing, ones.

The pool does not remove stale sessions until a new session is retrieved. The default pool size is the maximum amount of connections the session client allows. pyqldb.driver.pooled_qldb_driver.PooledQldbDriver.close() should be called when this factory is no longer needed in order to clean up resources, ending all sessions in the pool.

Parameters
  • ledger_name (str) – The QLDB ledger name.

  • retry_limit (int) – The number of automatic retries for statement executions using convenience methods on sessions when an OCC conflict or retriable exception occurs. This value must not be negative.

  • read_ahead (int) – The number of read-ahead buffers. Determines the maximum number of statement result pages that can be buffered in memory. This value must be either 0, to disable read-ahead, or a minimum of 2.

  • executor (concurrent.futures.thread.ThreadPoolExecutor) – A specific, optional, executor to be used by the retrieval thread if read-ahead is enabled.

  • region_name (str) – See [1].

  • verify (bool/str) – See [1].

  • endpoint_url (str) – See [1].

  • aws_access_key_id (str) – See [1].

  • aws_secret_access_key (str) – See [1].

  • aws_session_token (str) – See [1].

  • config (botocore.config.Config) – See [2]. Note that parameter user_agent_extra will be overwritten.

  • boto3_session (boto3.session.Session) – The boto3 session to create the client with (see [1]). The boto3 session is expected to be configured correctly.

  • pool_limit (int) – The session pool limit. Set to 0 to use the maximum possible amount allowed by the client configuration. See :param config.

  • timeout (int) – The timeout in seconds while attempting to retrieve a session from the session pool.

Raises
  • TypeError – When config is not an instance of botocore.config.Config. When boto3_session is not an instance of boto3.session.Session.

  • ValueError – When pool_limit exceeds the limit set by the client. When pool_limit or timeout are negative. When read_ahead or retry_limit is not set to the specified allowed values.

[1]: Boto3 Session.client Reference.

[2]: Botocore Config Reference.

close()[source]

Close the driver and any sessions in the pool.

execute_lambda(query_lambda, retry_indicator=<function PooledQldbDriver.<lambda>>)[source]

Execute the lambda function against QLDB within a transaction and retrieve the result.

Parameters
  • query_lambda (function) – The lambda function to execute. A lambda function cannot have any side effects as it may be invoked multiple times, and the result cannot be trusted until the transaction is committed.

  • retry_indicator (function) – Optional function called when the transaction execution is about to be retried due to an OCC conflict or retriable exception.

Return type

pyqldb.cursor.buffered_cursor.BufferedCursor/object

Returns

The return value of the lambda function which could be a pyqldb.cursor.buffered_cursor.BufferedCursor on the result set of a statement within the lambda.

Raises
execute_statement(statement, *parameters, retry_indicator=<function PooledQldbDriver.<lambda>>)[source]

Execute the statement using the specified parameters against QLDB and retrieve the result.

Parameters
  • statement (str) – The statement to execute.

  • parameters (Variable length argument list) –

    Ion values or Python native types that are convertible to Ion for filling in parameters of the statement.

    Details on conversion support and rules.

  • retry_indicator (function) – Optional function called when the transaction execution is about to be retried due to an OCC conflict or retriable exception.

Return type

pyqldb.cursor.buffered_cursor.BufferedCursor

Returns

Fully buffered Cursor on the result set of the statement.

Raises
  • DriverClosedError – When this driver is closed.

  • IllegalStateError – When the commit digest from commit transaction result does not match.

  • ClientError – When there is an error executing against QLDB.

get_session()[source]

This method will attempt to retrieve an active, existing session, or it will start a new session with QLDB if none are available and the session pool limit has not been reached. If the pool limit has been reached, it will attempt to retrieve a session from the pool until the timeout is reached.

Return type

pyqldb.session.pooled_qldb_session.PooledQldbSession

Returns

A PooledQldbSession object.

Raises