Clustered TypeDB
TypeDB server runs either as a single independent server or as a member of a cluster of replicated servers. This section covers everything that is specific to clustered TypeDB.
|
Clustering is released and generally available in TypeDB Enterprise and TypeDB Cloud, starting from TypeDB server version 3.14.1 (released in October 2026). TypeDB drivers and Console support clusters starting from version 3.14.0, so 3.14.0 clients work with 3.14.1 servers. TypeDB Community Edition runs single-server deployments only. |
On TypeDB Cloud, clusters are deployed and operated for you: the dashboard shows all the connection information you need. With TypeDB Enterprise, you deploy and administer the cluster yourself.
What’s different in a clustered deployment?
In a single-server deployment, the data lives on one machine, and clients access it through that one address.
In a clustered deployment, the data is replicated across a group of servers with the Raft consensus algorithm. At any time, one server is the primary and the others are secondaries:
-
the primary serves all client operations: transactions, database and user management, export and import;
-
the secondaries keep durable copies of the data, acknowledge changes, and take over through an automatic election when the primary fails.
A change is committed once a majority of the servers have written it, so a cluster of 2N + 1 servers tolerates the loss of N servers without losing data or availability.
Clients may connect to any server: a request that reaches a secondary is answered with the primary’s address, and TypeDB drivers and Console follow it automatically (see How clients reach the replicas).
How clients reach the replicas
A TypeDB gRPC driver or Console uses the addresses you give it only for first contact.
The server it reaches answers with the advertise address of every replica (server.advertise-address), and from then on the client connects to the replicas, and finds a new primary after a failover, at those advertised addresses.
HTTP clients are redirected in the same way, to the primary’s HTTP advertise address (server.http.advertise-address).
Every client must therefore be able to reach every replica, either at its advertise address or at an address the client maps to it.
There are two ways to achieve this:
| Advertise addresses (server side) | Address translation (client side) | |
|---|---|---|
Configured by |
The operator, once per replica: |
Each client: a map from the address the client reaches each replica at to that replica’s advertise address (the HTTP advertise address for the HTTP driver). |
Use when |
One address per replica works for every client, for example a hostname that resolves on every network the clients are on. |
Clients on different networks reach a replica through different addresses, for example from inside and from outside a private network, or through port forwarding. |
Client connects with |
Any one or more reachable replica addresses; the advertise addresses must be reachable too. |
The translation map, with an entry for every replica. |
Supported by |
All clients: TypeDB gRPC drivers, Console, the TypeScript HTTP driver, and any other client of the HTTP API. |
TypeDB gRPC drivers, Console, and the TypeScript HTTP driver. Other HTTP clients map the primary’s address themselves. |
Prefer advertise addresses, and use address translation only when no single address per replica works for every client. A load balancer in front of the cluster can serve first contact only: the advertise addresses, or the translation map, must still lead to each replica.
See Listen vs. advertise addresses to configure the servers, and drivers or Console to connect.