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 SERIALIZABLE transaction that touches data on several nodes is still serializable, exactly as on one node, and READ COMMITTED and REPEATABLE READ behave as they do in PostgreSQL: a REPEATABLE READ transaction reads every table at one snapshot, and a session always reads its own committed writes, on whichever nodes they live. 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.
• A snapshot transaction asks every shard group once. A REPEATABLE READ or SERIALIZABLE transaction fixes its snapshot on every shard group at its first statement, so each table it reads later shows exactly what had committed before that statement, as in PostgreSQL. That first statement waits for one round to every shard group, however few tables the transaction goes on to read, but never for a commit in flight; a READ COMMITTED statement asks only the groups it reads. A shard group no replica of which can be reached is left out of that round, and the transaction's reads are then checked at COMMIT, which fails with 40001 if one of them missed a commit.
• 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, and also a statement you can issue. Adding a node is automatic and requires no command. Removing one is 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 costs you quorum on the next scale-down. ALTER CLUSTER DRAIN '<node-name>' runs the same mechanism on demand, from any node, including against a node that is already gone, and converges every affected shard group regardless of which node leads it. See Scaling.
• 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