Namespace Amazon.QLDB.Driver
Classes
AbortException
Exception type representing the abort of a transaction within a lambda execution block. Signals that the lambda should cease to execute and the current transaction should be aborted.
BaseQldbDriverBuilder<TBuilder, TDriver>
Base builder object for creating QLDB driver objects, allowing for configuration of the parameters of construction.
BufferedResult
Implementation of a result which buffers all values in memory, rather than stream them from QLDB during retrieval. This implementation should only be used when the result is to be returned after the parent transaction is to be committed.
PooledQldbDriver
Represents a factory for accessing pooled sessions to a specific ledger within QLDB. This class or QldbDriver should be the main entry points to any interaction with QLDB. GetSession() will create a Amazon.QLDB.Driver.PooledQldbSession to the specified ledger within QLDB as a communication channel. Any acquired sessions must be cleaned up with Amazon.QLDB.Driver.PooledQldbSession.Dispose 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 set in the
PooledQldbDriver.PooledQldbDriverBuilder
Builder object for creating a PooledQldbDriver, allowing for configuration of the parameters of construction.
QldbDriver
Represents a factory for accessing sessions to a specific ledger within QLDB. This class or PooledQldbDriver should be the main entry points to any interaction with QLDB. GetSession() will create a Amazon.QLDB.Driver.QldbSession to the specified ledger within QLDB as a communication channel. Any sessions acquired should be cleaned up with Amazon.QLDB.Driver.QldbSession.Dispose to free up resources.
This factory does not attempt to re-use or manage sessions in any way. It is recommended to use PooledQldbDriver for both less resource usage and lower latency.
QldbDriver.QldbDriverBuilder
Builder object for creating a QldbDriver, allowing for configuration of the parameters of construction.
TransactionExecutor
Transaction object used within lambda executions to provide a reduced view that allows only the operations that are valid within the context of an active managed transaction.
Interfaces
IQldbDriver
Interface for the QLDB driver.
IQldbSession
The top-level interface for a QldbSession object 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. A new IQldbSession needs to be created from the parent driver in order to continue usage.
When a IQldbSession is no longer needed,
See 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 their inbuilt error handling:
- Execute(string) and Execute(string, List) allow 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.
- Execute(Action, Action) and Execute(Func, Action) allow 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.
- Execute(Action) and Execute(Func) are also available, providing the same functionality as the former two functions, but without a lambda function to be invoked upon a retriable error.
- StartTransaction() allows for full control over when the transaction is committed and leaves the responsibility of OCC conflict handling up to the user. Transaction methods cannot be automatically retried, as the state of the transaction is ambiguous in the case of an unexpected error.
IResult
Interface for the result of executing a statement in QLDB. Implements IEnumerable to allow iteration over Ion values within the result.
ITransaction
Interface that represents an active transaction with QLDB.
Every transaction is tied to the parent IQldbSession, meaning that if the parent session is closed or invalidated, the child transaction is automatically closed and cannot be used. Only one transaction can be active at any given time per parent session, and thus every transaction should call Abort() or Commit() when it is no longer needed, or when a new transaction is wanted from the parent session.
Any unexpected errors that occur within a transaction should not be retried using the same transaction, as the state of the transaction is now ambiguous.
When an OCC conflict occurs, the transaction is closed and must be handled manually by creating a new transaction and re-executing the desired queries.
Child Result objects will be closed when the transaction is aborted or committed.