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.
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.
403 read_only and advertises the current primary. Clients can follow that automatically.Why this is better than a database per region
| Need | NonoDB feature | Business result |
|---|---|---|
| Local reads in every office | Read replicas | The same catalog, search index, and dashboards close to users. |
| One source of truth | Primary → replica replication | No regional copies drifting apart or nightly sync jobs. |
| Read scaling | Add replicas | More regions or read-heavy screens without adding write capacity. |
| Disaster recovery | Hot standby | A prepared node can take over after a controlled failover. |
| Same features everywhere | Indexes and collection settings replicate | Search, TTL, history, and events behave the same on every node. |
| Simpler clients | Write URL discovery | Apps read locally and route writes to the current primary. |
| Failover visibility | Cluster GUI and metrics | See role, lag, acks, and promotion readiness from one console. |
| Secure links | TLS 1.3 and mTLS | Replication can cross providers without exposing plaintext traffic. |
- Customers and staff read from a nearby node instead of crossing an ocean for every page.
- There is one catalog, one customer record, and one audit history — not one copy per office.
- Adding a region is another replica, not another migration and sync project.
- Search indexes, TTL rules, history settings, and event definitions replicate with the data.
- A standby gives operations a tested path to recovery instead of a theoretical DR plan.
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.
| Collection | Purpose | Useful fields |
|---|---|---|
| products | Shared catalog and pricing. | sku, name, description, price, status, category_id, search_text, tenant_id |
| customers | One customer view across regions. | name, email, region, owner_id, tenant_id |
| orders | Writes routed to the primary. | customer_id, region, items, total, status, created_at, tenant_id |
| activities | Local read of the customer timeline. | contact_id, type, subject, body, created_at, tenant_id |
| _events | Outbox 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:7878nonodb-cli replication add-replica us-east-read defaultStart 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 statusRead 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 primarynonodb_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_totalFor 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.
- Keep at least three voters if you want automatic failover to survive one voter failure.
- Use a standby for planned maintenance and regional evacuation, not as a write target.
- Back up the primary and copy backup artifacts to shared storage or object storage; backups are not replicated.
- Monitor lag, ack age, transport errors, apply errors, and certificate expiry.
When another deployment model fits better
- You need active-active writes to the same document in several regions.
- You need synchronous cross-region writes with zero acknowledged-write loss for every operation.
- You need a globally consistent read-after-write guarantee from an asynchronous replica.
- You need payments with quorum semantics that are outside the current replication slice.
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.