Azure Cosmos DB SDK for Rust Is Generally Available: What Changes for Developers, DevOps and Architects

On this page

Microsoft made the Azure Cosmos DB SDK for Rust generally available at Ignite on 17 November 2026. The crate behind it, azure_data_cosmos 1.0.0, has been on crates.io since 8 October, with a minimum supported Rust version of 1.88. Until now, running Rust against Cosmos DB in production meant a preview SDK with no support commitment, or a hand-rolled REST client that had to reimplement retries, session tokens and regional routing. Both reasons to stay away are gone.

The release is more than a version bump. Microsoft’s announcement makes the point that the production settings other SDKs make you opt into are on by default here: Gateway v2, binary encoding on the wire, per-partition failover handling and a per-partition circuit breaker. OpenAI moved production traffic onto the SDK between preview and GA, and the fixes that came out of it, for very high partition counts, contended documents and poor networks, are in 1.0. This article goes through what that means for the people who write the code, the people who run it and the people who decide whether it belongs in the architecture.

Default behaviour in 1.0

Azure Cosmos DB SDK for Rust 1.0: Gateway v2, binary encoding, safe retries, per-partition circuit breaker and point-read hedging on by default, and the decisions that stay with the team
The defaults handle transient faults and partition-level outages. Account configuration, identity, time budgets and data modelling are still yours.
BehaviourDefault in 1.0.0What it means in practice
Gateway v2On when the account advertises itRequests go through a regional, performance-optimised gateway. There is no direct-mode connection management in your process.
Cosmos binary encodingOn for item operations and queriesSmaller payloads and less serialisation work. The Linux vNext emulator does not accept it yet, so turn it off there.
RetriesOn where safeThrottling (429), RetryWith (449) and regional retries are handled. Stored procedure execution and patches that are not retry-safe are not retried.
Per-partition circuit breakerOnAfter repeated failures for one partition in one region (defaults: 10 reads or 5 writes), that partition is routed to another region and probed for failback.
Per-partition automatic failoverFollowed when the account has itThe SDK follows partitions that the service has failed over. The account must have PPAF enabled.
Point-read hedgingOn for multi-region accountsA slow point read gets a second request to another region after min(1 s, request timeout / 2). Writes and queries are not hedged.

Two of these deserve a closer look. Microsoft’s post describes request hedging as optional, but in the 1.0.0 source a point read is hedged by default once the account has two or more read regions, and it can be switched off per operation or with AZURE_COSMOS_HEDGING_ENABLED=false. And per-partition automatic failover (PPAF) is an account feature: the SDK being ready for it does nothing until the account is configured for it.

For developers

Cargo features and versions

cargo add azure_data_cosmos gives the data plane with Entra ID authentication over rustls. Everything else is opt-in through features, and the names tell you what is stable:

  • key_auth: account-key authentication. Avoid it in services; use Entra ID.
  • control_plane: creating and deleting databases and containers and changing throughput. In 1.0.0 these calls need key authentication, which is a strong hint to leave them to infrastructure code.
  • fault_injection: rules that make the transport fail on purpose, for resilience tests.
  • unstable_patch, unstable_opentelemetry, unstable_dtx: partial updates, OpenTelemetry metrics and traces, and distributed transactions. The prefix means what it says: not covered by the GA promise.

Pin the crate in Cargo.toml and commit Cargo.lock. At the time of writing a 1.1 beta line already exists, and a service should not pick up a beta through a loose version requirement.

Client setup

A CosmosClient holds the regional endpoints, the partition topology cache, the circuit breaker state and connection pools. Build one per process and share it. The one decision the builder forces on you is the routing strategy: RoutingStrategy::ProximityTo orders the account’s regions by distance from the region your code runs in, and PreferenceOrder takes an explicit list. Resolving a container client loads the full partition topology by default, so a wrong container name or a missing role assignment fails at start-up rather than on the first customer request.

Rust56 lines
//! Builds one long-lived `CosmosClient` per process.

use std::sync::Arc;

use azure_core::credentials::TokenCredential;
use azure_data_cosmos::{
    clients::ContainerClient, options::RoutingStrategy, AccountEndpoint, AccountReference,
    CosmosClient,
};
use azure_identity::{
    DeveloperToolsCredential, ManagedIdentityCredential, ManagedIdentityCredentialOptions,
    UserAssignedId,
};

use crate::config::{CredentialSource, Settings};

pub fn credential(source: &CredentialSource) -> azure_core::Result<Arc<dyn TokenCredential>> {
    Ok(match source {
        CredentialSource::DeveloperTools => DeveloperToolsCredential::new(None)?,
        CredentialSource::ManagedIdentity { client_id: None } => {
            ManagedIdentityCredential::new(None)?
        }
        CredentialSource::ManagedIdentity {
            client_id: Some(id),
        } => ManagedIdentityCredential::new(Some(ManagedIdentityCredentialOptions {
            user_assigned_id: Some(UserAssignedId::ClientId(id.clone())),
            ..Default::default()
        }))?,
    })
}

/// Gateway v2, binary encoding, per-partition failover handling, the
/// per-partition circuit breaker and point-read hedging are all defaults in
/// 1.0.0, so nothing here switches them on. The routing strategy is the one
/// required decision: it orders the account's regions by proximity to where
/// this process runs.
pub async fn connect(
    settings: &Settings,
) -> Result<(CosmosClient, ContainerClient), Box<dyn std::error::Error + Send + Sync>> {
    let endpoint: AccountEndpoint = settings.endpoint.parse()?;
    let account = AccountReference::with_credential(endpoint, credential(&settings.credential)?);
    let client = CosmosClient::builder()
        .build(
            account,
            RoutingStrategy::ProximityTo(settings.app_region.clone().into()),
        )
        .await?;
    // Resolving the container loads the partition topology eagerly (the 1.0
    // default), so a misconfigured name or missing permission fails at start-up
    // rather than on the first customer request.
    let container = client
        .database_client(settings.database.as_str())
        .container_client(settings.container.as_str(), None)
        .await?;
    Ok((client, container))
}
💡
PARTITION KEYS FROM &STR MUST BE STATIC

In 1.0.0, a partition key value converts from &'static str, String or &String. Passing a borrowed &str from a request fails to compile with a lifetime error that points at the async call rather than the key. Pass tenant_id.to_owned() or a &String.

Error handling

By the time an error reaches your code, the SDK has already retried what it can safely retry. What remains needs a decision, and CosmosError::status() has the helpers to make it: is_not_found, is_conflict, is_precondition_failed, is_throttled and is_transient. A 408 with sub-status 20008 is the SDK’s own end-to-end timeout. Map these once, at the boundary of the data layer, instead of matching on status numbers throughout the code.

Rust137 lines
//! Maps SDK errors to what the application does next.
//!
//! The SDK has already retried what is safe to retry (throttling, 449 RetryWith,
//! regional failover, per-partition circuit breaking) by the time an error
//! reaches this code. What is left needs an application decision.

use azure_data_cosmos::error::CosmosError;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum StoreError {
    #[error("not found")]
    NotFound,
    #[error("already exists")]
    Conflict,
    /// The item changed since it was read (ETag mismatch). Re-read and re-apply.
    #[error("item was modified concurrently")]
    Concurrency,
    /// Still throttled after the SDK's own retries: shed load or raise throughput.
    #[error("throttled after retries")]
    Throttled,
    /// Timed out or unavailable after retries and failover: safe for the caller
    /// to retry later only if the operation is idempotent.
    #[error("temporarily unavailable ({status})")]
    Unavailable {
        status: u16,
        sub_status: Option<u32>,
    },
    /// Bad request, auth or permission problems: a bug or a configuration
    /// error, never retried.
    #[error("request rejected ({status})")]
    Rejected {
        status: u16,
        sub_status: Option<u32>,
    },
    #[error("invalid state transition")]
    InvalidTransition,
}

impl StoreError {
    /// HTTP status an API in front of the store would return.
    pub fn http_status(&self) -> u16 {
        match self {
            StoreError::NotFound => 404,
            StoreError::Conflict | StoreError::Concurrency | StoreError::InvalidTransition => 409,
            StoreError::Throttled => 429,
            StoreError::Unavailable { .. } => 503,
            StoreError::Rejected { .. } => 500,
        }
    }
}

impl From<CosmosError> for StoreError {
    fn from(e: CosmosError) -> Self {
        let s = e.status();
        let status = u16::from(s.status_code());
        let sub_status = s.sub_status().map(|x| u32::from(x.value()));
        if s.is_not_found() {
            StoreError::NotFound
        } else if s.is_conflict() {
            StoreError::Conflict
        } else if s.is_precondition_failed() {
            StoreError::Concurrency
        } else if s.is_throttled() {
            StoreError::Throttled
        } else if s.is_transient() {
            StoreError::Unavailable { status, sub_status }
        } else {
            StoreError::Rejected { status, sub_status }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use azure_core::http::StatusCode;
    use azure_data_cosmos::error::CosmosStatus;

    fn err(code: u16, sub: Option<u16>) -> CosmosError {
        let mut st = CosmosStatus::new(StatusCode::from(code));
        if let Some(sub) = sub {
            st = st.with_sub_status(sub);
        }
        CosmosError::builder()
            .with_status(st)
            .with_message("test")
            .build()
    }

    #[test]
    fn maps_statuses_to_actions() {
        assert!(matches!(
            StoreError::from(err(404, None)),
            StoreError::NotFound
        ));
        assert!(matches!(
            StoreError::from(err(409, None)),
            StoreError::Conflict
        ));
        assert!(matches!(
            StoreError::from(err(412, None)),
            StoreError::Concurrency
        ));
        assert!(matches!(
            StoreError::from(err(429, Some(3200))),
            StoreError::Throttled
        ));
        assert!(matches!(
            StoreError::from(err(503, None)),
            StoreError::Unavailable { status: 503, .. }
        ));
        // 408 with sub-status 20008 is the SDK's own end-to-end timeout.
        assert!(matches!(
            StoreError::from(err(408, Some(20008))),
            StoreError::Unavailable {
                status: 408,
                sub_status: Some(20008)
            }
        ));
        assert!(matches!(
            StoreError::from(err(403, None)),
            StoreError::Rejected { status: 403, .. }
        ));
        assert!(matches!(
            StoreError::from(err(400, None)),
            StoreError::Rejected { status: 400, .. }
        ));
    }

    #[test]
    fn http_mapping() {
        assert_eq!(StoreError::Concurrency.http_status(), 409);
        assert_eq!(StoreError::Throttled.http_status(), 429);
        assert_eq!(StoreError::from(err(403, None)).http_status(), 500);
    }
}

Concurrency and queries

The repository below uses the patterns that matter at scale. A create that returns 409 is checked against the stored item, because that is what a client retry after a lost response looks like. Status changes use an If-Match precondition on the ETag from the read, with a small bounded retry when another writer got there first. Every operation carries an end-to-end latency policy, which bounds retries, failover and hedging together. Queries are scoped to one partition key, so they never fan out.

Rust179 lines
//! Order storage on Azure Cosmos DB for NoSQL with the Rust SDK 1.0.
//!
//! Partition key values built from `&str` must be `'static` in 1.0.0; values
//! known only at run time are passed as `String` (or `&String`).

use std::time::Duration;

use azure_data_cosmos::{
    clients::ContainerClient,
    feed::FeedScope,
    options::{
        EndToEndOperationLatencyPolicy, ItemReadOptions, ItemWriteOptions, OperationOptions,
        Precondition, QueryOptions,
    },
    Query,
};
use futures::TryStreamExt;
use tracing::{debug, warn};

use crate::errors::StoreError;
use crate::model::{Order, OrderStatus};

/// An order together with the ETag it was read at, for optimistic concurrency.
#[derive(Debug, Clone)]
pub struct Versioned<T> {
    pub value: T,
    pub etag: String,
}

pub struct OrderRepository {
    container: ContainerClient,
    timeout: Duration,
}

impl OrderRepository {
    pub fn new(container: ContainerClient, timeout: Duration) -> Self {
        Self { container, timeout }
    }

    /// One budget for the whole operation: retries, failover and hedging
    /// included. Without it a request can keep retrying long after the caller
    /// has given up.
    fn operation(&self) -> OperationOptions {
        let mut op = OperationOptions::default();
        op.end_to_end_latency_policy = Some(EndToEndOperationLatencyPolicy::new(self.timeout));
        op
    }

    fn write_options(&self) -> ItemWriteOptions {
        ItemWriteOptions::default().with_operation_options(self.operation())
    }

    /// Creates an order. A 409 means the id already exists in this tenant, which
    /// is what a client retry after a lost response looks like, so the caller
    /// gets the stored order back instead of an error when it matches.
    pub async fn place(&self, order: &Order) -> Result<Versioned<Order>, StoreError> {
        match self
            .container
            .create_item(
                &order.tenant_id,
                &order.id,
                order,
                Some(self.write_options()),
            )
            .await
        {
            Ok(resp) => {
                let charge = resp.headers().request_charge().map(|c| c.to_string());
                debug!(order_id = %order.id, ru = ?charge, "order created");
                let etag = resp
                    .headers()
                    .etag()
                    .map(|e| e.to_string())
                    .unwrap_or_default();
                Ok(Versioned {
                    value: order.clone(),
                    etag,
                })
            }
            Err(e) => match StoreError::from(e) {
                StoreError::Conflict => {
                    let existing = self.get(&order.tenant_id, &order.id).await?;
                    if existing.value.lines == order.lines
                        && existing.value.currency == order.currency
                    {
                        Ok(existing)
                    } else {
                        Err(StoreError::Conflict)
                    }
                }
                other => Err(other),
            },
        }
    }

    pub async fn get(&self, tenant_id: &str, id: &str) -> Result<Versioned<Order>, StoreError> {
        let options = ItemReadOptions::default().with_operation_options(self.operation());
        let resp = self
            .container
            .read_item(tenant_id.to_owned(), id, Some(options))
            .await?;
        let etag = resp
            .headers()
            .etag()
            .map(|e| e.to_string())
            .unwrap_or_default();
        Ok(Versioned {
            value: resp.into_model::<Order>()?,
            etag,
        })
    }

    /// Moves an order to a new status with an If-Match precondition, retrying a
    /// small number of times when another writer got there first.
    pub async fn transition(
        &self,
        tenant_id: &str,
        id: &str,
        next: OrderStatus,
    ) -> Result<Order, StoreError> {
        for attempt in 1..=3 {
            let current = self.get(tenant_id, id).await?;
            if current.value.status == next {
                return Ok(current.value); // already applied: idempotent
            }
            if !current.value.status.can_move_to(next) {
                return Err(StoreError::InvalidTransition);
            }
            let mut updated = current.value.clone();
            updated.status = next;
            let mut options = self.write_options();
            options.precondition = Some(Precondition::IfMatch(current.etag.clone().into()));
            match self
                .container
                .replace_item(tenant_id.to_owned(), id, &updated, Some(options))
                .await
            {
                Ok(_) => return Ok(updated),
                Err(e) => match StoreError::from(e) {
                    StoreError::Concurrency => {
                        warn!(order_id = id, attempt, "etag mismatch, re-reading");
                        continue;
                    }
                    other => return Err(other),
                },
            }
        }
        Err(StoreError::Concurrency)
    }

    /// Lists a tenant's orders in one status. Scoped to one partition key, so it
    /// is a single-partition query: no fan-out across physical partitions.
    pub async fn by_status(
        &self,
        tenant_id: &str,
        status: OrderStatus,
        limit: u32,
    ) -> Result<Vec<Order>, StoreError> {
        let query =
            Query::from("SELECT TOP @limit * FROM c WHERE c.status = @status ORDER BY c._ts DESC")
                .with_parameter("@limit", limit)
                .and_then(|q| q.with_parameter("@status", status))
                .map_err(StoreError::from)?;
        let options = QueryOptions::default().with_operation_options(self.operation());
        let mut items = self
            .container
            .query_items::<Order>(
                query,
                FeedScope::partition(tenant_id.to_owned()),
                Some(options),
            )
            .await?;
        let mut out = Vec::new();
        while let Some(order) = items.try_next().await? {
            out.push(order);
        }
        Ok(out)
    }
}

Cross-partition queries are supported in 1.0, with limits worth knowing before you design around them. A fresh cross-partition query or change feed read fails if it would fan out to more than 100 physical partitions, unless you raise FeedOptions::max_fan_out. Unordered cross-partition DISTINCT and non-streaming ORDER BY need a finite TOP or LIMIT, and most DISTINCT shapes cannot be resumed from a continuation token. The change feed is available in pull mode, including all versions and deletes. Earlier dataa.dev posts on hierarchical partition keys cover how to keep queries inside one partition in the first place.

For DevOps and SRE

Identity and provisioning

Run services under a managed identity with a Cosmos DB data-plane role such as Cosmos DB Built-in Data Contributor, scoped as narrowly as the workload allows. Create databases and containers, set throughput and enable PPAF in Bicep or Terraform, not from application code: the SDK’s control-plane calls are behind a feature flag and need account keys, which the data plane does not. With keys out of the application, you can disable key-based access on the account. PPAF itself is switched on per account under Settings, Features in the Azure portal; Microsoft says the Azure CLI and PowerShell can do the same. Rehearse it before you rely on it: Microsoft provides a fault simulation script for a partition-level failover, and during the drill the Total Requests metric by region and the PartitionWriteGlobalStatus metric show writes moving to the secondary region.

Incident switches

Most of the new defaults have an environment variable, and several have an _OVERRIDE form that wins over code. Put these in your runbook before you need them:

VariableEffect
AZURE_COSMOS_HEDGING_ENABLED and _OVERRIDETurn point-read hedging on or off; the override wins over per-request settings.
AZURE_COSMOS_PPCB_ENABLED_OVERRIDEForce the per-partition circuit breaker on or off process-wide.
AZURE_COSMOS_PPCB_READ_FAILURE_THRESHOLD, _WRITE_FAILURE_THRESHOLDFailures before a partition is routed away (defaults 10 and 5).
AZURE_COSMOS_CONNECTION_POOL_GATEWAY_V2_DISABLED and _OVERRIDEFall back from Gateway v2 to the standard gateway.
AZURE_COSMOS_BINARY_ENCODING_ENABLEDSend text JSON instead of binary, for example against the Linux emulator.
AZURE_COSMOS_DIAGNOSTICS_DEFAULT_VERBOSITYDiagnostics detail; the default is a size-bounded summary grouped by region.
⚠️
THE LINUX EMULATOR NEEDS BINARY ENCODING OFF

The Linux vNext emulator does not yet accept Cosmos binary encoding, which 1.0 enables by default. CI jobs that run integration tests against it must set AZURE_COSMOS_BINARY_ENCODING_ENABLED=false or disable it on the builder. The Windows emulator is not affected.

Diagnostics

Every response and error carries a diagnostics context with the regions tried, retries, hedges and request charge. The SDK can emit it through a DiagnosticsHandler, with a sampling handler that logs only operations that fail or breach latency or RU thresholds, and rate-limits the output so an error storm does not flood your log pipeline. OpenTelemetry metrics and traces exist but sit behind unstable_opentelemetry; until that stabilises, log request charge and diagnostics for slow and failed operations, and alert on sustained 429s and on circuit-breaker trips.

CI and resilience testing

The sample includes a pipeline that checks formatting, runs Clippy with warnings as errors and runs the tests on Rust 1.88 and stable, with cargo audit for published advisories. For resilience tests, the fault_injection feature lets a test build a client whose transport returns chosen errors or delays for chosen regions and operations, so you can prove the timeout and error mapping behave before a real outage does it for you.

YAML27 lines
# Copy to .github/workflows/cosmos-orders.yml in your own repository.
name: cosmos-orders
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # 1.88 is azure_data_cosmos 1.0.0's minimum supported Rust version.
        toolchain: ["1.88", stable]
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ matrix.toolchain }}
          components: clippy, rustfmt
      - uses: Swatinem/rust-cache@v2
      - run: cargo fmt --check
      - run: cargo clippy --all-targets --locked -- -D warnings
      - run: cargo test --locked
      # Fails the build if a dependency has a published security advisory.
      - run: cargo install cargo-audit --locked && cargo audit

For architects

Failover model

Who handles throttling, transient errors, a failing partition, a write region outage and a slow read region: the SDK, the account configuration or the application code
The SDK covers more than before, but a write region outage still depends on how the account is set up.

The SDK’s defaults are client-side behaviour. Whether writes survive a regional outage depends on the account. Microsoft’s reliability guidance compares the options for a single-write-region account: with PPAF enabled, individual partitions fail over and writes typically resume in about three minutes, with no action needed. With service-managed failover alone, the whole account fails over and that can take an hour or more. A multi-write account needs no failover but brings conflict resolution. The Rust SDK makes PPAF accounts behave well. It does not make a single-region account highly available.

Microsoft’s PPAF documentation sets the conditions. The account must use the NoSQL API, have a single write region and at least one read region, and use provisioned throughput, not serverless. Consistency must be Strong, Session, Consistent Prefix or Eventual; Bounded Staleness is not supported yet. Partition-level failover is quoted at under three minutes at P99. With Strong consistency nothing is lost; at other levels the most recent committed replica is promoted, and writes that diverged are reconciled with last-writer-wins on failback. PPAF is part of the Business Critical service tier and charged accordingly, and while it is enabled you cannot use Synapse Link, in-account restore, partition merge or taking a region offline.

⚠️
EVERY WRITER NEEDS SUPPORT

Microsoft’s guidance is to run a PPAF-capable SDK on every application instance that writes to the account, because an unsupported client can fail writes during a partition-level failover. The PPAF documentation was last updated before the Rust GA and lists .NET 3.62.0, Java 4.79.0, Python 4.16.0 and Node.js 4.7.0 or later; Rust support comes from the GA announcement. Before enabling PPAF, list every service, function and script that writes to the account, and upgrade the ones that fall short.

%%{init: {'theme': 'base', 'themeVariables': {'signalColor': '#0078D4', 'signalTextColor': '#0F172A', 'actorBkg': '#EAF4FD', 'actorBorder': '#0078D4', 'actorTextColor': '#0F2B46', 'noteBkgColor': '#F3F9FF', 'noteBorderColor': '#0078D4', 'noteTextColor': '#0F2B46', 'lineColor': '#243A5E'}}}%%
sequenceDiagram
    participant App as Order service
    participant SDK as Rust SDK 1.0
    participant WE as West Europe
    participant NE as North Europe
    App->>SDK: replace_item with If-Match
    SDK->>WE: Write for partition P7
    WE-->>SDK: Write fails for P7
    Note over SDK: Marks P7 unavailable in West Europe<br/>other partitions keep writing there
    SDK->>NE: Same write for P7
    NE-->>SDK: 200 with new ETag
    SDK-->>App: Ok
    Note over SDK,WE: Background sweep probes West Europe<br/>and fails P7 back when healthy

The sequence above is the case the SDK now handles without application code: one partition’s write fails in the primary region, the SDK routes that partition to the next region, and every other partition carries on in the primary. For a .NET view of the same question, what happens to a write you have acknowledged during a regional failure, see Multi-Region Active-Active on Azure for a .NET API.

Cost and capacity

Binary encoding should reduce request charge and bytes on the wire, according to Microsoft. Hedging works the other way: a hedged read is a second request, charged in the second region, so a latency-sensitive read path on a multi-region account will consume somewhat more RU/s than the same traffic without hedging. Measure both on your own workload before resizing. Plan for region loss as well: when a partition or region fails over, the remaining regions take its traffic, so provision with autoscale or headroom rather than for the steady state.

⚖️
ROUTING IS NOT A RESIDENCY CONTROL

A preferred region list in the SDK orders regions; it does not restrict them, and after failover exhausts the list the SDK can use any region on the account. Data residency is decided by which regions the account replicates to. If data must stay in the EU, every region on the account must be in the EU, and that belongs in your data processing records.

Fit and adoption

The case for Rust here is the same as anywhere: predictable latency without a garbage collector, small memory footprints and the compiler’s guarantees around concurrency. That suits high-throughput ingestion, gateways and services where p99 latency is the requirement. With 1.0 the operational gap with the .NET and Java SDKs has largely closed for data-plane work. The remaining gaps are deliberate: control-plane operations with Entra ID, stable OpenTelemetry, and patch and distributed transactions are not in the GA surface yet. OpenAI’s migration is a sensible template for adoption: run the Rust client beside the existing one and shift traffic gradually, with a way back.

📝
HOW THIS WAS CHECKED

The sample was compiled against azure_data_cosmos 1.0.0, azure_identity 1.0.0 and azure_core 1.1.0 with Rust 1.97, passes cargo clippy --all-targets -- -D warnings, and its 8 unit tests pass (configuration validation, document serialisation and error mapping). The repository code was not run against a live account or the emulator. Defaults, thresholds, environment variables and feature flags were read from the 1.0.0 crate source and changelog. Release details and the OpenAI account are from Microsoft’s announcement; PPAF requirements, limitations and the enablement and drill steps are from Microsoft’s PPAF documentation; the comparison with service-managed failover is from Microsoft’s Cosmos DB reliability guidance.

Key takeaways

  • azure_data_cosmos 1.0.0 is GA and supported; pin it, commit the lock file and keep 1.1 betas out of production.
  • Gateway v2, binary encoding, safe retries, the per-partition circuit breaker and point-read hedging are on by default. Know them before an incident, not during one.
  • PPAF has to be enabled on the account; without it, a write region outage still stops writes until the account fails over.
  • Use managed identity and a data-plane role, and keep databases, containers and throughput in infrastructure code.
  • Give every operation an end-to-end time budget, and handle conflicts and ETag mismatches explicitly.

Are you moving a Cosmos DB workload to Rust, or starting a new one on it? Tell me in the comments what you are building and which default you are least sure about.

Glossary

PPAF
Per-partition automatic failover: individual partitions of a single-write-region account fail over to another region instead of the whole account.
PPCB
Per-partition circuit breaker: client-side routing of one failing partition to another region after repeated failures.
Gateway v2
Cosmos DB’s rewritten regional gateway path, used by the Rust SDK instead of direct mode.
Binary encoding
Cosmos DB’s binary JSON format, used on the wire by default in the 1.0 SDK.
Hedging
Sending a second copy of a slow read to another region and using whichever answers first.
End-to-end latency policy
A time budget for one operation that covers its retries, failover and hedging.
ETag
A version marker on an item, used with If-Match for optimistic concurrency.
Partition key
The item property that decides which logical partition an item lives in.
Fan-out
A query that has to visit several physical partitions.
Change feed
The ordered record of changes to items in a container.
RU
Request unit: Cosmos DB’s unit of throughput and cost.
MSRV
Minimum supported Rust version, 1.88 for this SDK.

References & Further Reading


Discover more from C4: Container, Code, Cloud & Context

Subscribe to get the latest posts sent to your email.

Written by

Nithin Mohan TK

Hello Namaste! 👋🏻 I'm an accomplished Enterprise Solution Architect & Engineering Leader with 20+ years of progressive experience architecting, building, and scaling transformative enterprise solutions. ⚜️ Solution Architect / AI & Cloud 📌 Galway, Ireland

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.