Transactions
- class acouchbase.transactions.transactions.AttemptContext(impl: AsyncAttemptContextInterface)
The operations a transaction’s logic performs, within one attempt of the transaction.
Transactions.run()passes it to the logic, and runs the logic again with a new attempt when an attempt has to be retried.- get(coll: AsyncCollection, key: str, options: TransactionGetOptions | None = None, **kwargs: Unpack[TransactionGetOptionsKwargs]) Awaitable[TransactionGetResult]
Get a document within this transaction.
- Parameters:
coll (
couchbase.collection.Collection) – Collection to use to find the document.key (str) – document key.
options (
TransactionGetOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionGetOptions
- Returns:
Document in collection, in a form useful for passing to other transaction operations.
- Return type:
Awaitable[
couchbase.transactions.TransactionGetResult]- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
couchbase.exceptions.DocumentNotFoundException – If the document does not exist.
- get_multi(specs: list[TransactionGetMultiSpec] | tuple[TransactionGetMultiSpec, ...], options: TransactionGetMultiOptions | None = None, **kwargs: Unpack[TransactionGetMultiOptionsKwargs]) Awaitable[TransactionGetMultiResult]
Get multiple documents within this transaction.
- Parameters:
specs (list[
TransactionGetMultiSpec] | tuple[TransactionGetMultiSpec]) – The required information for the documents involved for this operation.options (
TransactionGetMultiOptions, optional) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionGetMultiOptions
- Returns:
Collection of results from the operation.
- Return type:
- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
- get_multi_replicas_from_preferred_server_group(specs: list[TransactionGetMultiReplicasFromPreferredServerGroupSpec] | tuple[TransactionGetMultiReplicasFromPreferredServerGroupSpec, ...], options: TransactionGetMultiReplicasFromPreferredServerGroupOptions | None = None, **kwargs: Unpack[TransactionGetMultiReplicasFromPreferredServerGroupOptionsKwargs]) Awaitable[TransactionGetMultiReplicasFromPreferredServerGroupResult]
Get multiple documents within this transaction from replicas in the preferred server group.
- Parameters:
specs (list[
TransactionGetMultiReplicasFromPreferredServerGroupSpec] | tuple[TransactionGetMultiReplicasFromPreferredServerGroupSpec]) – The required information for the documents involved for this operation.options (
TransactionGetMultiReplicasFromPreferredServerGroupOptions, optional) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionGetMultiReplicasFromPreferredServerGroupOptions
- Returns:
Collection of results from the operation.
- Return type:
- Raises:
TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
- get_replica_from_preferred_server_group(coll: AsyncCollection, key: str, options: TransactionGetReplicaFromPreferredServerGroupOptions | None = None, **kwargs: Unpack[TransactionGetReplicaFromPreferredServerGroupOptionsKwargs]) Awaitable[TransactionGetResult]
Get a document within this transaction from a replica in the preferred server group.
The preferred server group is set in
ClusterOptions.- Parameters:
coll (
couchbase.collection.Collection) – Collection to use to find the document.key (str) – document key.
options (
TransactionGetReplicaFromPreferredServerGroupOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionGetReplicaFromPreferredServerGroupOptions
- Returns:
- Document in collection, in a form useful for passing
to other transaction operations.
- Return type:
- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
couchbase.exceptions.DocumentUnretrievableException – If the document could not be retrieved from any replica in the preferred server group. The transaction will not rollback if this exception is caught.
- insert(coll: AsyncCollection, key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], options: TransactionInsertOptions | None = None, **kwargs: Unpack[TransactionInsertOptionsKwargs]) Awaitable[TransactionGetResult]
Insert a new document within a transaction.
- Parameters:
coll (
couchbase.collection.Collection) – Collection to use to find the document.key (str) – document key.
value (JSONType) – Contents of the document.
options (
TransactionInsertOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionInsertOptions
- Returns:
- Document in collection, in a form
useful for passing to other transaction operations.
- Return type:
Awaitable[
couchbase.transactions.TransactionGetResult]- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
- query(query: str, options: TransactionQueryOptions | None = None) Awaitable[TransactionQueryResults]
Perform a query within a transaction.
- Parameters:
query (str) – Query to perform.
options (
TransactionQueryOptions) – Query options to use, if any.
- Returns:
Awaitable[
TransactionQueryResults]- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
couchbase.exceptions.CouchbaseException – If the operation failed, but the transaction will not necessarily be rolled back, a CouchbaseException other than TransactionOperationFailed will be raised. If handled, the transaction will not rollback.
- remove(txn_get_result: TransactionGetResult) Awaitable[None]
Remove a document in a transaction.
- Parameters:
txn_get_result (
couchbase.transactions.TransactionGetResult) – Document to delete.- Returns:
Awaitable[None]
- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
- replace(txn_get_result: TransactionGetResult, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], options: TransactionReplaceOptions | None = None, **kwargs: Unpack[TransactionReplaceOptionsKwargs]) Awaitable[TransactionGetResult]
Replace the contents of a document within a transaction.
- Parameters:
txn_get_result (
couchbase.transactions.TransactionGetResult) – Document to replace, gotten from a previous call to another transaction operation.value (JSONType) – The new contents of the document.
options (
TransactionReplaceOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
TransactionReplaceOptions
- Returns:
- Document in collection, in a form useful
for passing to other transaction operations.
- Return type:
Awaitable[
couchbase.transactions.TransactionGetResult]- Raises:
couchbase.exceptions.TransactionOperationFailed – If the operation failed. In practice, there is no need to handle the exception, as the transaction will rollback regardless.
- class acouchbase.transactions.transactions.Transactions(impl: AsyncTransactionsInterface)
Runs transactions on a cluster.
Get it from the cluster’s
transactionsproperty.- close() None
Close the transactions.
No transactions can be run on this instance afterwards. There is no need to call this, as the transactions close automatically when the transactions object goes out of scope.
- Returns:
None
- async run(txn_logic: Callable[[AttemptContext], Coroutine[Any, Any, None]], *, per_txn_config: TransactionOptions) TransactionResult
- async run(txn_logic: Callable[[AttemptContext], Coroutine[Any, Any, None]], transaction_options: TransactionOptions | None = None) TransactionResult
Run a set of operations within a transaction.
- Parameters:
txn_logic (Callable[
AttemptContext]) – The coroutine function holding the transaction logic to perform.transaction_options (
TransactionOptions) – Options to override those in theTransactionConfigfor this transaction only.**kwargs –
Accepts
per_txn_config, the same astransaction_options. Any other keyword is ignored.Deprecated since version 4.1.0: Pass
transaction_optionsinstead.
- Returns:
Results of the transaction.
- Return type:
- Raises:
TransactionFailed – If the transaction failed.
TransactionExpired – If the transaction expired.
TransactionCommitAmbiguous – If the transaction’s commit was ambiguous. See
TransactionCommitAmbiguousfor a detailed description.