Cluster, HA and multi-region

By the end of this page you will know what a ScramDB cluster actually gives you, what it costs, and which of the following pages to read next for your situation.

One engine, config-gated

There is no separate "cluster build" of ScramDB. The exact same binary and the exact same container image run single-node or clustered. A [cluster] section in scramdb.toml turns cluster mode on; its absence is byte-identical to today's single-node engine, with zero distributed overhead. You do not install a different package, and your SQL and PostgreSQL drivers do not change either way.

Licensing, stated up front

Multi-node clustering, including a minimal one-node cluster, is an Enterprise (or Trial) license capability. A node with [cluster] configured checks its license before it binds any port. On Community edition (the default, no license key set), the node refuses to start and exits with a clear error rather than degrading to single-node. Single-node ScramDB (no [cluster] section at all) has no such gate and runs unrestricted on every edition.

If clustering matters to you, read this before investing more time here: see Forming a cluster for the exact error text and how to supply a key.

What you get

• Full serializable transactions across the whole cluster. A transaction that touches data on several nodes is still serializable, exactly as on one node. A conflicting transaction is aborted with PostgreSQL SQLSTATE 40001 and your existing retry-on-serialization-failure logic handles it unmodified.
• Distributed query execution. Scans, joins, and aggregations can run across the nodes that hold the relevant data, not just on the node you happen to be connected to.
• Connect to any node. There is no separate coordinator, router, or proxy process to run. Any node accepts a normal PostgreSQL wire connection and internally forwards or coordinates work against whichever node actually owns or leads the data involved.
• Tested failover with no committed-write loss. When a node holding leadership for some data crashes, the surviving replicas elect a new leader and keep serving; a write already acknowledged as committed is never lost. See Failover for the full contract, including what a connected client actually observes.
• Automatic node addition. Point a new node at the cluster's existing peers and it joins on its own, no admin command required. See Scaling.

What it costs, and what you weigh

• A consensus round trip on every cross-node write. Data is replicated to a set of nodes (the replication factor, 3 by default) and a write needs agreement from a majority of that set before it is acknowledged. That round trip is the price of the consistency guarantee above; it is unavoidable physics, not a tuning miss. See Multi-zone and Multi-region for the concrete numbers.
• Region awareness is opt-in; zone awareness is a label, not a placement input. Label a node with region and placement respects it: a table homed in a region keeps all its voters there, so its transactions commit at region-local quorum latency instead of paying WAN on every write. Leave region unset and placement is byte-identical to a single-region cluster. zone is different, and worth being precise about: it is replicated, advertised, and reported in scram.nodes, but the placement algorithm does not read it. Spreading replicas across availability zones is still a decision you make by choosing where each node runs. See Multi-region and Multi-zone.
• Scale-down is automatic on shutdown, but not yet a statement you can issue. Adding a node is automatic and requires no command. Removing one is now handled for you: a node self-drains its own membership as it shuts down, so a scaled-down replica no longer lingers as a configured voter and cost you quorum on the next scale-down. What is still missing is the on-demand form. An ALTER CLUSTER DRAIN statement is implemented and tested at the engine level, but it is not wired into SQL dispatch, so no client can invoke it today; graceful shutdown is the only path that triggers a drain. See Scaling for the current procedure.
• The shipped demo assets are not auth-hardened out of the box. The published Docker image's default command runs with client authentication disabled, and it is fine for a local demo on a network you control. Turn authentication on before you expose a cluster node's PostgreSQL port anywhere else.

Where to go next

You want to...	Read
Go from one node to a working three-node cluster	Forming a cluster
Point an application at a cluster and retry correctly	Connecting to a cluster
Trade freshness for latency on reads, and see the route a query took	Read freshness and routing
Query the live topology: nodes, shards, replica lag	Inspecting the cluster
Home a table in a region and commit at region-local latency	Multi-region
Survive an availability-zone outage	Multi-zone
Know what happens, and what a client sees, when a node dies	Failover
Add or remove capacity from a running cluster	Scaling
Look up a SQLSTATE your driver just raised	Error codes