transactions-rust

name	transactions-rust
summary	Distributed ACID transactions are not supported by the Couchbase Rust SDK 1.x — alternatives and workarounds
description	Distributed ACID transactions are not supported by the Couchbase Rust SDK 1.x — alternatives and workarounds
compatibility	Rust SDK 1.x. Distributed transactions not supported.
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user asks about transactions in a supported language","skill":"transactions-python"},{"condition":"user asks about connection setup or SDK configuration","skill":"server-connection-rust"}]}

Distributed Transactions — Rust

Rust SDK 1.x does not support distributed ACID transactions. There is no Transactions API.

Basic Transaction

Not available. See Alternatives below for single-document atomicity (CAS) and multi-document saga patterns.

SQL++ in Transactions

Not applicable — transactions are not supported. Use cluster.query() for SQL++ queries. See server-querying-rust.

Error Handling

Since there is no transaction API, there are no TransactionFailed or TransactionExpired errors. Handle CAS conflicts with CasMismatch retries (see Alternatives below).

Design Rules

• Keep writes to a single document where possible — use sub-document ops for atomicity.
• For multi-document workflows, use the saga pattern with compensating writes.
• Make saga steps idempotent so they can be safely retried.

Alternatives

Option 1 — Optimistic concurrency with CAS:

For single-document atomicity, use Compare-And-Swap (CAS) to detect and retry conflicting writes.

use couchbase::error::ErrorKind;

let max_retries = 5;
for _ in 0..max_retries {
    let result = collection.get("account::alice", None).await?;
    let cas = result.cas();
    let mut doc: serde_json::Value = result.content_as()?;

    doc["balance"] = serde_json::json!(doc["balance"].as_i64().unwrap() - 100);

    match collection.replace(
        "account::alice",
        doc,
        ReplaceOptions::new().cas(cas),
    ).await {
        Ok(_) => break,
        Err(e) if matches!(e.kind(), ErrorKind::CasMismatch) => continue,
        Err(e) => return Err(e.into()),
    }
}

Option 2 — Sub-document atomic operations:

For incrementing counters or appending to arrays atomically within a single document:

use couchbase::MutateInSpec;

// Atomic decrement — no CAS needed
collection.mutate_in(
    "account::alice",
    &[
        MutateInSpec::decrement("balance", 100, None)?,
    ],
    None,
).await?;

Option 3 — Application-level saga pattern:

For multi-document workflows, implement a saga: write each step with a status field (pending → committed → complete), and use a background task to detect and compensate for incomplete sagas.

Option 4 — Use a supported SDK:

If distributed ACID transactions are a hard requirement, Python, Java, Go, .NET, Node.js, PHP, and Scala SDKs all support them. See the transactions-python skill as a starting point.

When Transaction Support Is Added

Monitor the Couchbase Rust SDK release notes for transaction support in future versions.