Use case · Multi-region

One database. Three regions. Local reads.

A retail chain, a distributed team, or a SaaS product with offices in several countries does not need a separate database per region. Keep one primary for writes, put read replicas close to users, and keep a standby ready for failover.

Read replicasHot standbyFailoverLocal latencyOne source of truth

The scenario

A store chain has headquarters in Frankfurt, a store platform in Virginia, and a support team in Singapore. Product content and prices are managed centrally. Storefronts need local catalog reads. Support needs the same customer timeline everywhere. A standby in Amsterdam protects the primary.

Frankfurt — primary

All product, customer, order, and configuration writes land here.

Virginia — read replica

Local storefront and dashboard reads, including search indexes.

Singapore — read replica

Local support and operations reads without a cross-region round trip.

Amsterdam — standby

A hot standby that can become primary after a controlled failover.

What the topology looks like

Replication is pull-based. Each replica connects outbound to the primary, so you do not need inbound access to every office or provider. Only the primary accepts client writes.

Application writes
Primary · Frankfurtwrites enabled · source of truth
Read replica · Virginialocal reads · async pull
Read replica · Singaporelocal reads · async pull
▲ writes · TLS / mTLS ▼ replicated changes
Standby · Amsterdampromotion ready · failover target
Local appsread · search · dashboards
Local workersevents · webhooks · reports
Not active-active writes. Replicas are read-only. A write sent to a replica returns 403 read_only and advertises the current primary. Clients can follow that automatically.

Why this is better than a database per region

NeedNonoDB featureBusiness result
Local reads in every officeRead replicasThe same catalog, search index, and dashboards close to users.
One source of truthPrimary → replica replicationNo regional copies drifting apart or nightly sync jobs.
Read scalingAdd replicasMore regions or read-heavy screens without adding write capacity.
Disaster recoveryHot standbyA prepared node can take over after a controlled failover.
Same features everywhereIndexes and collection settings replicateSearch, TTL, history, and events behave the same on every node.
Simpler clientsWrite URL discoveryApps read locally and route writes to the current primary.
Failover visibilityCluster GUI and metricsSee role, lag, acks, and promotion readiness from one console.
Secure linksTLS 1.3 and mTLSReplication can cross providers without exposing plaintext traffic.

The data model does not change

Replication is a deployment concern, not a new schema. Write the same documents and indexes you would use on a single node. Add aregion field only when the business needs it for reporting or ownership.

CollectionPurposeUseful fields
productsShared catalog and pricing.sku, name, description, price, status, category_id, search_text, tenant_id
customersOne customer view across regions.name, email, region, owner_id, tenant_id
ordersWrites routed to the primary.customer_id, region, items, total, status, created_at, tenant_id
activitiesLocal read of the customer timeline.contact_id, type, subject, body, created_at, tenant_id
_eventsOutbox consumed by regional workers.type, doc_id, payload, created_at

Configure the primary and one replica

Start the primary with replication logging and a stable origin. Then create a one-time pairing code for the replica.

NONODB_REPLICATION_ENABLED=1
NONODB_REPLICATION_ROLE=primary
NONODB_REPLICATION_ORIGIN=eu-primary
NONODB_REPLICATION_NODE_ID=eu-primary
NONODB_REPLICATION_ADVERTISE_URL=https://db-eu.example.com:7878
nonodb-cli replication add-replica us-east-read default

Start the replica with its own data directory and role, then redeem the code. Repeat this for Singapore as a read replica and Amsterdam as a standby. The replica pulls an initial snapshot when it is fresh.

NONODB_REPLICATION_ROLE=replica
NONODB_REPLICATION_NODE_ID=us-east-read
NONODB_REPLICATION_ADVERTISE_URL=https://db-us.example.com:7878

# After the daemon is listening:
nonodb-cli replication join https://db-eu.example.com:7878 <pairing-code>
nonodb-cli replication status
Use TLS/mTLS between locations. Replication crosses untrusted networks. Configure node certificates and keep clocks synchronized so lag, leases, and subscription expiry behave correctly.

Read locally. Write centrally.

Official clients can keep reads on the local replica and send writes to the primary. With auto_primary, the client discovers the current write URL from the replica and retries once only after an explicitread_only rejection.

from nonodb import NonoDB

db = NonoDB(
    "https://db-us.example.com:7878",   # local reads
    token="nodb_...",
    auto_primary=True,                  # writes follow /readyz/write
)

products = db.collection("products")
products.find({"status": "active"}, limit=20)
products.update(
    {"_id": "p_123"},
    {"$set": {"price": 199.0}},
)

Read from a replica

Catalog pages, search, dashboards, support timelines, and reports where a small lag is acceptable.

Write to the primary

Prices, stock changes, orders, approvals, and anything that needs read-after-write consistency.

Operate it like a cluster

Watch lag and acknowledgements, not just “is the process up”. The same GUI and metrics work on every node.

nonodb-cli replication status
nonodb-cli replication acks
nonodb-cli replication primary
nonodb_replication_lag{database="default",origin="eu-primary"}
nonodb_replication_applied{database="default",origin="eu-primary"}
nonodb_replication_ack_nodes{database="default",origin="eu-primary"}
nonodb_replication_apply_errors_total

For automatic failover, configure voters, a candidate, and a failover timeout. A candidate that has not applied the last observed head is not promoted, which prevents a lagging node from becoming the new source of truth. For a controlled move, demote the old primary, promote the target, verify lag, then update the write endpoint.

When another deployment model fits better

Use the primary for those reads and writes, or keep the critical path in one region. Replication is a strong fit for local reads, read scaling, standby capacity, and disaster recovery — not for pretending the speed of light does not exist.

One source of truth. Many local reads.

Put the database where the work happens.