Skip to main content
Version: Nightly

Manage Read Replicas

This guide explains how to manage Read Replicas (follower regions) in GreptimeDB Enterprise, including how to add and remove read replicas at both the table and region levels, inspect the current regions distribution with the SHOW REGION, and apply placement constraints and recommended best practices for performance.

Adding Read Replicas to a Table​

Adding a Read Replica is as simple as executing one SQL command:

ADMIN ADD_TABLE_FOLLOWER(<table_name>)

Read Replica peers for each region are allocated based on the workload types of the datanodes. For optimal performance, it is strongly recommended to configure Datanode groups to separate read and write workloads into different datanode groups.

This is the function in GreptimeDB for adding read replicas to. The parameters are:

  • table_name: The name of the table to add read replicas to.

Next is an example to illustrate steps to add read replicas to a table.

First start a GreptimeDB Enterprise Cluster with 3 Datanodes. Then create a table:

CREATE TABLE foo (
  ts TIMESTAMP TIME INDEX,
  i INT PRIMARY KEY,
  s STRING,
) PARTITION ON COLUMNS ('i') (
  i <= 0,
  i > 0,
);

Using the SHOW REGION, we can find the regions distribution information:

SHOW REGION FROM foo;

+-------+---------------+------+--------+
| Table | Region        | Peer | Leader |
+-------+---------------+------+--------+
| foo   | 4398046511104 |    0 | Yes    |
| foo   | 4398046511105 |    1 | Yes    |
+-------+---------------+------+--------+

This shows two write replicas (leader regions) on Datanodes 1 and 2.

Then to add read replicas (Follower regions):

ADMIN ADD_TABLE_FOLLOWER('foo');

After the read replicas are added, find the regions distribution information:

SHOW REGION FROM foo;

+-------+---------------+------------+--------+
| Table | Region        | Peer       | Leader |
+-------+---------------+------------+--------+
| foo   | 4398046511104 |          0 | Yes    |
| foo   | 4398046511104 | 4294967296 | No     |
| foo   | 4398046511105 |          1 | Yes    |
| foo   | 4398046511105 | 4294967297 | No     |
+-------+---------------+------------+--------+

Now, read replicas can be found on Datanode 4294967296 and 4294967297.

Removing Read Replicas from a Table​

Removing a Read Replica is as simple as executing one SQL command:

ADMIN REMOVE_TABLE_FOLLOWER(<table_name>)

This is the function in GreptimeDB for removing read replicas from a table. The parameters are:

  • table_name: The name of the table to remove read replicas from.

This command removes the most recently added read replica' peers from each region.

For example, before running the command:

SHOW REGION FROM foo;
+-------+---------------+------------+--------+
| Table | Region        | Peer       | Leader |
+-------+---------------+------------+--------+
| foo   | 4398046511104 |          0 | Yes    |
| foo   | 4398046511104 | 4294967296 | No     |
| foo   | 4398046511104 | 4294967297 | No     |
| foo   | 4398046511105 |          1 | Yes    |
| foo   | 4398046511105 | 4294967296 | No     |
| foo   | 4398046511105 | 4294967297 | No     |
+-------+---------------+------------+--------+

Here, region 4398046511104 has two read replicas on peers (4294967296, 4294967297), and region 4398046511105 also has two read replicas on peers (4294967296, 4294967297). After executing:

ADMIN REMOVE_TABLE_FOLLOWER('foo');
+------------------------------------+
| ADMIN REMOVE_TABLE_FOLLOWER('foo') |
+------------------------------------+
|                                  0 |
+------------------------------------+

The most recently added read replicas' peers of each region are removed:

  • Region 4398046511104: removed read replica on peer 4294967297.
  • Region 4398046511105: removed read replica on peer 4294967296.

Result:

SHOW REGION FROM foo;
+-------+---------------+------------+--------+
| Table | Region        | Peer       | Leader |
+-------+---------------+------------+--------+
| foo   | 4398046511104 |          0 | Yes    |
| foo   | 4398046511104 | 4294967296 | No     |
| foo   | 4398046511105 |          1 | Yes    |
| foo   | 4398046511105 | 4294967297 | No     |
+-------+---------------+------------+--------+

Adding Read Replica to a Region​

ADMIN ADD_REGION_FOLLOWER(<region_id>, <datanode_id>)

This is the function in GreptimeDB for adding read replicas to a region. The parameters are:

  • region_id: The id of the region to add Read Replica to.
  • datanode_id: The id of the datanode to add Read Replica to.

A read replica and a write replica cannot be placed on the same datanode. Additionally, each datanode can host only one read replica per region.

Example:

-- Add a read replica for region 4398046511104 on datanode 2
ADMIN ADD_REGION_FOLLOWER(4398046511104, 2);

If the specified datanode already hosts a read replica for that region, or is the write replica (leader) of that region, the command will be rejected.

Removing Read Replica from a Region​

ADMIN REMOVE_REGION_FOLLOWER(<region_id>, <datanode_id>)

This is the function in GreptimeDB for removing read replicas from a region. The parameters are:

  • region_id: The id of the region to remove read replica from.
  • datanode_id: The id of the datanode to remove read replica from.

Example:

-- Remove the read replica on datanode 2 for region 4398046511104
ADMIN REMOVE_REGION_FOLLOWER(4398046511104, 2);

Next steps​