# 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.

replication using grpc clients

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.

replicator fetches committed txs via grpc calls and replicate them using in-process method invocations

# 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:

$ ./immuadmin login immudb
Password:
logged in
$ ./immuadmin database create \
    --replication-is-replica \
    --replication-primary-username=immudb \
    --replication-primary-password=immudb \
    --replication-primary-database=defaultdb \
    replicadb
database 'replicadb' {replica: true} successfully created

TIP

Display all database creation flags with:

$ ./immuadmin help database create

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

Start immudb with enabled replication:

$ ./immudb \
    --replication-is-replica \
    --replication-primary-username=immudb \
    --replication-primary-password=immudb \
    --replication-primary-host=127.0.0.1

TIP

Display all replication flags:

$ ./immudb --help

# Multiple replicas

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

multiple replicas of the same primary database

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.

a replica indirectly following the primary

# 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.

a single immudb server can hold multiple primary and replica databases

# 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 (opens new window), part of the immudb tools (opens new window).

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 (opens new window).