pyqldb.session.qldb_session.QldbSession(session, read_ahead, retry_limit, executor)[source]¶A class representing a session to a QLDB ledger for interacting with QLDB. A QldbSession is linked to the specified ledger in the parent driver of the instance of the QldbSession. In any given QldbSession, only one transaction can be active at a time. This object can have only one underlying session to QLDB, and therefore the lifespan of a QldbSession is tied to the underlying session, which is not indefinite, and on expiry this QldbSession will become invalid, and a new QldbSession needs to be created from the parent driver in order to continue usage.
When a QldbSession is no longer needed, pyqldb.session.qldb_session.QldbSession.close() should be invoked
in order to clean up any resources.
See pyqldb.driver.pooled_qldb_driver.PooledQldbDriver for an example of session lifecycle management,
allowing the re-use of sessions when possible. There should only be one thread interacting with a session at any
given time.
There are three methods of execution, ranging from simple to complex; the first two are recommended for inbuilt error handling:
pyqldb.session.qldb_session.QldbSession.execute_statement()allows for a single statement to be executed within a transaction where the transaction is implicitly created and committed, and any recoverable errors are transparently handled.
pyqldb.session.qldb_session.QldbSession.execute_lambda()allows for more complex execution sequences where more than one execution can occur, as well as other method calls. The transaction is implicitly created and committed, and any recoverable errors are transparently handled.
pyqldb.session.qldb_session.QldbSession.start_transaction()allows for full control over when the transaction is committed and leaves the responsibility of OCC conflict handling up to the user. Transactions’ methods cannot be automatically retried, as the state of the transaction is ambiguous in the case of an unexpected error.
session (pyqldb.communication.session_client.SessionClient) – The session object representing a communication channel with QLDB.
read_ahead (int) – The number of pages to read-ahead and buffer when retrieving results.
retry_limit (int) – The limit for retries on execute methods when an OCC conflict or retriable exception occurs.
executor (concurrent.futures.thread.ThreadPoolExecutor) – The executor to be used by the retrieval thread.
execute_lambda(query_lambda, retry_indicator=<function QldbSession.<lambda>>)[source]¶Implicitly start a transaction, execute the lambda function, and commit the transaction, retrying up to the retry limit if an OCC conflict or retriable exception occurs.
If an InvalidSessionException is received, it is considered a retriable exception by starting a new
pyqldb.communication.session_client.SessionClient to use to communicate with QLDB. Thus, as a side
effect, this QldbSession can become valid again despite a previous InvalidSessionException from other method
calls on this instance, any child transactions, or cursors, when this method is invoked.
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.
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.
IllegalStateError – When the commit digest from commit transaction result does not match.
SessionClosedError – When this session is closed.
ClientError – When there is an error executing against QLDB.
LambdaAbortedError – If the lambda function calls pyqldb.execution.executor.Executor.abort.
execute_statement(statement, *parameters, retry_indicator=<function QldbSession.<lambda>>)[source]¶Implicitly start a transaction, execute the statement, and commit the transaction, retrying up to the retry limit if an OCC conflict or retriable exception occurs.
If an InvalidSessionException is received, it is considered a retriable exception by starting a new
pyqldb.communication.session_client.SessionClient to use to communicate with QLDB. Thus, as a side
effect, this QldbSession can become valid again despite a previous InvalidSessionException from other method
calls on this instance, any child transactions, or cursors, when this method is invoked.
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.
retry_indicator (function) – Optional function called when the transaction execution is about to be retried due to an OCC conflict or retriable exception.
Fully buffered Cursor on the result set of the statement.
IllegalStateError – When the commit digest from commit transaction result does not match.
SessionClosedError – When this session is closed.
ClientError – When there is an error executing against QLDB.
TypeError – When conversion of native data type (in parameters) to Ion fails due to an unsupported type.
ledger_name¶The read-only ledger name.
list_tables()[source]¶Get the list of table names in the ledger.
Iterable of table names in amazon.ion.simple_types.IonPyText format found in the ledger.
SessionClosedError – When this session is closed.
session_id¶The read-only session ID.
session_token¶The read-only session token.
start_transaction()[source]¶Start a transaction using an available database session.
A new transaction.
SessionClosedError – When this session is closed.
throw_if_closed()[source]¶Check and throw if this session is closed.
SessionClosedError – When this session is closed.