Transactions

class couchbase.transactions.transactions.AttemptContext(impl: AttemptContextInterface)

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: Collection, key: str, options: TransactionGetOptions | None = None, **kwargs: Unpack[TransactionGetOptionsKwargs]) → TransactionGetResult

Get a document within this transaction.

Parameters:
Returns:

Document in collection, in a form useful for passing

to other transaction operations.

Return type:

couchbase.transactions.TransactionGetResult

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

Get multiple documents within this transaction.

Parameters:
Returns:

Collection of results from the operation.

Return type:

TransactionGetMultiResult

Raises:

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]) → 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: Collection, key: str, options: TransactionGetReplicaFromPreferredServerGroupOptions | None = None, **kwargs: Unpack[TransactionGetReplicaFromPreferredServerGroupOptionsKwargs]) → 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: Collection, key: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], options: TransactionInsertOptions | None = None, **kwargs: Unpack[TransactionInsertOptionsKwargs]) → 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:

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) → TransactionQueryResults

Perform a query within a transaction.

Parameters:
Returns:

TransactionQueryResults

Raises:
remove(txn_get_result: TransactionGetResult) → None

Remove a document in a transaction.

Parameters:

txn_get_result (couchbase.transactions.TransactionGetResult) – Document to delete.

Returns:

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]) → 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:

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 couchbase.transactions.transactions.Transactions(impl: TransactionsInterface)

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.

run(txn_logic: Callable[[AttemptContext], None], *, per_txn_config: TransactionOptions) → TransactionResult
run(txn_logic: Callable[[AttemptContext], None], transaction_options: TransactionOptions | None = None) → TransactionResult

Run a set of operations within a transaction.

Parameters:
  • txn_logic (Callable[AttemptContext]) – 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:

Examples

Transactional update of 2 documents, using couchbase.options.TransactionConfig in the cluster:

doc1_id = "doc1-key"
doc2_id = "doc2-key"
coll = cluster.bucket("default").default_collection()

def txn_logic(ctx):
    doc1 = ctx.get(coll, doc1_id)
    doc2 = ctx.get(coll, doc2_id)
    ctx.replace(doc1, {"some_key": f"I'm in {doc1_id}, and updated"})
    ctx.replace(doc2, {"some_key": f"I'm in {doc2_id}, and updated"})

cluster.transactions.run(txn_logic)