Interface 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.
Namespace: Amazon.QLDB.Driver
Assembly: Amazon.QLDB.Driver.dll
Syntax
public interface IQldbSession : IDisposable
Methods
| Improve this Doc View SourceExecute(Action<TransactionExecutor>, Action<Int32>)
Execute the Executor lambda against QLDB within a transaction where no result is expected.
Declaration
void Execute(Action<TransactionExecutor> action, Action<int> retryAction = null)
Parameters
Type | Name | Description |
---|---|---|
Action<TransactionExecutor> | action | A lambda with no return value representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times. |
Action<System.Int32> | retryAction | A lambda that which is invoked when the Executor lambda is about to be retried due to a retriable error. Can be null if not applicable. |
Exceptions
Type | Condition |
---|---|
AbortException | If the Executor lambda calls Abort(). |
Execute(String, List<IIonValue>, Action<Int32>)
Execute the statement against QLDB and retrieve the result.
Declaration
IResult Execute(string statement, List<IIonValue> parameters = null, Action<int> retryAction = null)
Parameters
Type | Name | Description |
---|---|---|
System.String | statement | The PartiQL statement to be executed against QLDB. |
List<IIonValue> | parameters | Parameters to execute. |
Action<System.Int32> | retryAction | A lambda that which is invoked when the Executor lambda is about to be retried due to a retriable error. Can be null if not applicable. |
Returns
Type | Description |
---|---|
IResult | The result of executing the statement. |
Exceptions
Type | Condition |
---|---|
AbortException | If the Executor lambda calls Abort(). |
Execute<T>(Func<TransactionExecutor, T>, Action<Int32>)
Execute the Executor lambda against QLDB and retrieve the result within a transaction.
Declaration
T Execute<T>(Func<TransactionExecutor, T> func, Action<int> retryAction = null)
Parameters
Type | Name | Description |
---|---|---|
Func<TransactionExecutor, T> | func | A lambda representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times, and the result cannot be trusted until the transaction is committed. |
Action<System.Int32> | retryAction | A lambda that which is invoked when the Executor lambda is about to be retried due to a retriable error. Can be null if not applicable. |
Returns
Type | Description |
---|---|
T | The return value of executing the executor. Note that if you directly return a IResult, this will be automatically buffered in memory before the implicit commit to allow reading, as the commit will close any open results. Any other IResult instances created within the executor block will be invalidated, including if the return value is an object which nests said IResult instances within it. |
Type Parameters
Name | Description |
---|---|
T | The return type. |
Exceptions
Type | Condition |
---|---|
AbortException | If the Executor lambda calls Abort(). |
ListTableNames()
Retrieve the table names that are available within the ledger.
Declaration
IEnumerable<string> ListTableNames()
Returns
Type | Description |
---|---|
IEnumerable<System.String> | The Enumerable over the table names in the ledger. |
StartTransaction()
Create a transaction object which allows for granular control over when a transaction is aborted or committed.
Declaration
ITransaction StartTransaction()
Returns
Type | Description |
---|---|
ITransaction | The newly created transaction object. |