Replication

Replication strategy#

immudb includes support for replication by means of a follower approach. A database can be created or configured either to be a primary or a replica of another database.

During replication, primary databases have a passive role. The grpc endpoint ExportTx is used by replicas to fetch unseen committed transactions from the primary.

Replicas are read only and any direct write operation will be rejected. Using replicas allow to distribute query loads.

Replication and users#

As shown in the diagram above, the replicator fetches committed transaction from the primary via grpc calls. Internally, the replicator instantiates an immudb client (using the official golang SDK) and fetches unseen committed transactions from the primary. In order to do so, the replicator requires valid user credentials with admin permissions, otherwise the primary will reject any request.

Creating a replica#

Creating a replica of an existent database using immuadmin is super easy:

 1$ ./immuadmin login immudb
 2Password:
 3logged in
 4$ ./immuadmin database create \
 5    --replication-is-replica \
 6    --replication-primary-username=immudb \
 7    --replication-primary-password=immudb \
 8    --replication-primary-database=defaultdb \
 9    replicadb
10database 'replicadb' {replica: true} successfully created

1$ ./immuadmin help database create 

Creating a second immudb instance to replicate systemdb and defaultdb behaves similarly#

Start immudb with enabled replication:

1$ ./immudb \
2    --replication-is-replica \
3    --replication-primary-username=immudb \
4    --replication-primary-password=immudb \
5    --replication-primary-host=127.0.0.1

1$ ./immudb --help

Multiple replicas#

It’s possible to create multiple replicas of a database. Each replica works independently of the others.

Given the primary database acts in passive mode, there are no special steps needed in order to create more replicas. Thus, by repeating the same steps to create the first replica it’s possible to configure new ones.

Replica of a replica#

In case many replicas are needed or the primary database is under heavy load, it’s possible to delegate the creation of replicas to an existent replica. This way, the primary database is not affected by the total number of replicas being created.

External replicator#

By creating a database as a replica but with disabled replication, no replicator is created for the database and an external process could be used to replicate committed transactions from the primary. The grpc endpoint ReplicateTx may be used to externally replicate a transaction.

Heterogeneous settings#

Replication is configured per database. Thus, the same immudb server may hold several primary and replica databases at the same time.

Replicator tool#

You may need to keep a copy of every database on one immudb instance on another, so that when a new database is created on the main instance, a replicated database is created on the replica.

In that case you can use the replicator tool , part of the immudb tools .

This tool connects to two immudb instances, one main instance and a replica. Periodically, scans the list of databases present on the main instance and it compares that with the list of databases present on the replica. If it finds any new databases that are missing on the replicas, it will recreate it on the replica and it will configure it to start following its counterpart on the main.

If necessary (usually it is) it will also create the replication user on the main instance for the new database(s).

Using this tool you won’t need to manually configure replicated databases on replica instance(s).

You can have more information about this tool on its README page .