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:
Returns:

Document in collection, in a form useful for passing to other transaction operations.

Return type:

Awaitable[couchbase.transactions.TransactionGetResult]

Raises:
get_multi(specs: list[TransactionGetMultiSpec] | tuple[TransactionGetMultiSpec, ...], options: TransactionGetMultiOptions | None = None, **kwargs: Unpack[TransactionGetMultiOptionsKwargs]) → Awaitable[TransactionGetMultiResult]

Get multiple documents within this transaction.

Parameters:
Returns:

Collection of results from the operation.

Return type:

TransactionGetMultiResult

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:
Returns:

Collection of results from the operation.

Return type:

TransactionGetMultiReplicasFromPreferredServerGroupResult

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:
Returns:

Document in collection, in a form useful for passing

to other transaction operations.

Return type:

couchbase.transactions.TransactionGetResult

Raises:
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:
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:
Returns:

Awaitable[TransactionQueryResults]

Raises:
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:
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 transactions property.

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 the TransactionConfig for this transaction only.

  • **kwargs –

    Accepts per_txn_config, the same as transaction_options. Any other keyword is ignored.

    Deprecated since version 4.1.0: Pass transaction_options instead.

Returns:

Results of the transaction.

Return type:

TransactionResult

Raises: