Manage Replicas

This page will walk you through everything you need to know to configure replicas in your existing FaunaDB Enterprise cluster. If you are starting from scratch, please see Set Up A New Cluster.

Creating a Replica

A replica is a named group of nodes in a FaunaDB Enterprise cluster. A replica exists in the cluster as long as there is at least one node in the cluster that declares it belongs to the replica based on its replica_name setting in faunadb.yml.

You do not explicitly create replicas, but rather a replica comes into existence in a cluster when you add a node to it with the new replica name specified in the node’s replica_name configuration setting.

To add more nodes to a replica, keep adding nodes that declare that replica in their replica_name configuration setting.

Removing a Replica

You do not explicitly remove replicas, rather a replica ceases to exist when all its nodes are removed from the cluster.

Replica Types

Every FaunaDB replica has a type describing the level of functionality its nodes will provide. The three types, in increasing order of functionality are named compute, data, and data+log.

1. nodes in compute replicas do not store data, nor do they participate in the distributed transaction log. They can receive queries from clients and execute them, relying on nodes in other replicas for data storage and the transaction log.

2. nodes in data replicas execute queries from clients just as compute replicas do, but in addition they also store data. The full data set is partitioned between nodes in a single replica, and the replica as a whole will contain the full data set.

3. nodes in data+log replicas have all the functionality of a data replica, but in addition they also participate in the distributed transaction log.

Viewing Existing Replicas

Either the status or the show-replication commands will give you information about existing replicas (status gives more verbose overall system information, while show-replication only lists the replicas.)

$ faunadb-admin status


$ faunadb-admin show-replication

Setting the Replica Type

The type of the replica can be set any number of times during its lifetime, as long as the cluster at all times has at least one data+log replica. When the cluster is initialized, the replica of the first node is by default set to be of data+log type, while all additional replicas start out as compute replicas and need to be explicitly set to a different type in order to participate in either the data or log replication.

When a replica type is changed from data (or data+log) to compute, it will immediately discard its full data set and if it is later reclassified as data, it will need to re-acquire data from other replicas, which can take some time. Data replicas that are acquiring data become gradually available for both reads and writes (and are thus useful data members of the cluster) as their data acquisition process progresses.

To change the type of the replica, on any node run:

$ faunadb-admin update-replica »New Replica Type« »Replica Name«

For example, to set replica_3 to compute type:

$ faunadb-admin update-replica compute replica_3

You can also specify multiple replicas in an update-replica command:

$ faunadb-admin update-replica data replica_4 replica_5

Will set both replica_4 and replica_5 to data type.

Use the status admin command to track the progress of replicating data to the new nodes:

$ faunadb-admin status

Replication Considerations for Distributed Transaction Log

We recommend that you configure your cluster to have at least 3 data+log replicas in order to ensure the cluster’s ability to process writes in the event that one replica goes down.

The physical location of the nodes which replicate the transaction log affects write latency. Writes originating closer to the nodes replicating the transaction log will have a lower latency than writes originating from farther away.