Docs
  • 0.49.1latest
  • 0.48.0
  • 0.47.0
  • 0.46.0
  • 0.45.0
  • 0.44.0
  • 0.43.0
  • 0.42.0
  • 0.41.0
  • 0.40.0
  • 0.39.6
  • 0.39.5
  • 0.39.3
  • 0.39.2
  • 0.39.1
  • 0.39.0
  • 0.38.4
  • 0.38.2
  • 0.38.1
  • 0.37.1
  • 0.37.0
  • 0.36.2
  • 0.36.1
  • 0.36.0
  • 0.35.3
  • 0.35.2
  • 0.35.1
  • 0.35.0
  • 0.34.4
  • 0.34.3-beta
  • 0.34.2-beta
  • 0.34.1-beta
  • 0.34.0-beta
  • 0.33.4-beta
  • 0.33.3-beta
  • 0.33.2-beta
  • 0.33.1-beta
  • 0.33.0-beta
  • 0.32.0-beta

Two regions, one database

A primary region and a DR region over one replication link per database: what is declared where, what the link's lag means for RPO, and the re-pointing ceremony that fails over and back.

A deployment across two regions is two independent clusters and one link per protected database. The primary region runs the write traffic; the DR region holds a copy that is read-only by declaration; and a failover is re-pointing — aiming clients at the other region — not a protocol the store runs. This page is the deployment schema: the shape, the order a deployment comes up in, the lag and what it means for RPO, and the ceremony that fails over and back. The link itself — what it is, what crosses the seam, how the copy stays read-only — lives in Between clusters; this page is about the topology around it.

The shape

Two clusters, one direction of flow per link, no shared anything.

Primary region a shop.orders — writable DR region b shop.orders — read-only link prod_dr clients
Two independent clusters. The link ships the database's log one way; nothing else crosses the seam.

The link is declared on the shipping side with TO and on the receiving side with FROM. The row is cluster-local on each side — the way a peer row is — so the two regions never share membership, election or a coordinator. What crosses the seam is the database's log, at-least-once, applied idempotently by identity; a record the remote has already applied is a no-op, so the stream can catch up from wherever a snapshot ended.

Each protected database gets its own link, and a link has exactly one direction. A third region is the same pattern again — one more FROM at the new region, one more direction of flow.

The statements

-- at the primary: this cluster ships
DEFINE REPLICATION prod_dr TO 'dr-cluster:9080' FOR DATABASE shop.orders;

-- at the DR: another cluster ships here, and this copy is read-only by declaration
DEFINE REPLICATION prod_dr FROM 'primary-cluster:9080' FOR DATABASE shop.orders;

-- a token binds the pair the way a join token binds a member row
CREATE LINK TOKEN FOR REPLICATION prod_dr EXPIRES 10m;

-- operations
ALTER REPLICATION prod_dr PAUSED;
ALTER REPLICATION prod_dr RESUMED;
DROP REPLICATION prod_dr;

-- the report: the declaration and the confirmed position
INFO FOR REPLICATION prod_dr;
INFO FOR REPLICATIONS;

FOR DATABASE takes the fully qualified namespace.database spelling — a replication is a statement about the cluster, and a database named relative to whatever the writing session happened to select would mean different databases in two scripts that read the same. When the remote knows the database under another name, AS carries the remote's spelling.

The token is created at the receiving cluster, on its FROM row. The hex is answered once and carried to the source node's environment as TESSARIDB_LINK_TOKEN_PROD_DR — a secret enters through the environment, never the catalog. The source presents it when it ships; the receiving side verifies the presented token against the digest and expiry on its row before it applies anything. The same statement on a TO row is the surface for the other direction's binding: a source that wants the remote to prove itself before the log is handed over puts the digest on its outbound row.

The receiving copy is read-only from the moment the inbound link applies, and the refusal is the declaration's own: a write into a received database is refused with WritesToAReplica, which names the link. Dropping the inbound link at the DR lifts the read-only — that is the lever the failover ceremony below pulls.

The order a deployment comes up in

  1. Both clusters come up independently. Each is a normal cluster of the shipped kind — founding membership in one transaction, roles, an operator (What a cluster is). Neither names the other in its catalog beyond the replication link.
  2. The protected database exists at the primary and holds its data.
  3. The link is declared both sides — TO at the primary, FROM at the DR — and the token binds the pair: created at the DR, carried to the source's environment, verified on every connection.
  4. The DR catches up from a snapshot when it starts behind. Restore a backup of the source into the DR node, drop the replication rows the snapshot carried, declare the FROM half over the restored database, and let the link converge: positions the snapshot already covers are no-ops on identical bytes, so the stream catches up from wherever the snapshot ended. The first connection does the rest.

The lag, and the RPO stated honestly

The link is asynchronous: the primary can acknowledge a write the link has not yet shipped. The RPO of the deployment is therefore the lag, and the lag is a measurement, not a constant — it shrinks with the link's cadence and grows with the write load, and no page can promise you a number for your deployment.

Measure it two ways:

  • The live bound. INFO FOR REPLICATION at the primary reports the confirmed position — the sequence the remote has durably applied — against the primary's committed tail, under your write load. The distance between them, in records and in seconds, is the bound your deployment actually holds.
  • The rehearsal. Fail the primary over in a drill and count what the DR actually held at the moment of the cut. That count — the acknowledged total minus the records present — is the honest RPO in records, and it is the number to put in the runbook.

The RTO is the ceremony itself: stopping the write traffic, dropping the inbound link, and re-aiming clients is a handful of operator steps, and rehearsing it once is what turns a listed procedure into a known time.

The failover ceremony

Failover is re-pointing. The store is not told; the operator moves the traffic.

  1. Stop the write traffic at the primary. That is the operator's act — a load balancer, a client config. (The case the DR exists for is the primary being gone entirely; the ceremony is the same.)
  2. DROP REPLICATION prod_dr at the DR. This lifts the read-only. The DR's database is writable from that moment, and the survivors of the primary are no longer shipping into it.
  3. Aim clients at the DR. The deployment now runs single-region on the DR cluster.
Primary region gone DR region b shop.orders — writable link dropped clients re-aimed
The drop at the DR lifts the read-only; the clients move. Nothing on the primary needs to agree.

Fail back is the same ceremony with the regions swapped:

  1. The primary comes back empty of authority. Bring it up without the database the DR now owns; it will receive the database back over the wire.
  2. Declare the link from the DR — TO 'primary-cluster:9080' at the DR, FROM at the primary — with a fresh token the same way as the first time.
  3. Let it catch up, watch the confirmed position in INFO FOR REPLICATION reach the DR's committed tail, then DROP REPLICATION at the primary. The copy there is read-only until the drop, exactly as the DR's was.
  4. Aim clients home.

A write that lands at the DR during the single-region period ships back to the primary the same way every other record did — one direction per link, idempotent by identity, no reconciliation step.

What is proven, and what is next

Proven today: the schema above, end to end, with one node in each region — two single nodes, one link, a write at the primary reading at the DR, the copy refusing its own divergent write by name, and both directions of the failover ceremony rehearsed on real processes.

Next: a region that is itself a multi-node cluster — several nodes of one region sharing the received database — is where the engine's cluster work is heading. Until it lands, a region holds its copy on one node. The statements, the token ceremony and the failover are exactly the same the day multi-node regions arrive; only the inside of a region changes.

Meanwhile, protect across regions the way this page describes, and scale inside a region with the ordinary cluster pages — who leads what, when a write is acknowledged and upgrading a cluster.