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:
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:
- 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]) 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:
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:
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: 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:
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: 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:
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:
- 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:
query (str) – Query to perform.
options (
TransactionQueryOptions) – Query options to use, if any.
- Returns:
- 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) 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:
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:
- 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
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.
- 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 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.
Examples
Transactional update of 2 documents, using
couchbase.options.TransactionConfigin 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)