Creating a cluster > Setting up replication > Adding and removing a table from a replication cluster

To join an existing cluster, you must specify at least:

The name of the cluster
The host:port of another node in the cluster you are joining

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

JOIN CLUSTER posts AT '10.12.1.35:9312'

POST /cli -d "
JOIN CLUSTER posts AT '10.12.1.35:9312'
"

$params = [
  'cluster' => 'posts',
  'body' => [
      '10.12.1.35:9312'
  ]
];
$response = $client->cluster->join($params);

utilsApi.sql('JOIN CLUSTER posts AT \'10.12.1.35:9312\'')

await utilsApi.sql('JOIN CLUSTER posts AT \'10.12.1.35:9312\'')

res = await utilsApi.sql('JOIN CLUSTER posts AT \'10.12.1.35:9312\'');

utilsApi.sql("JOIN CLUSTER posts AT '10.12.1.35:9312'");

utilsApi.Sql("JOIN CLUSTER posts AT '10.12.1.35:9312'");

utils_api.sql("JOIN CLUSTER posts AT '10.12.1.35:9312'", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

{u'error': u'', u'total': 0, u'warning': u''}

{"total":0,"error":"","warning":""}

If authentication and authorization is enabled, the effective replication user must have replication permission. You can specify that user in the JOIN CLUSTER statement:

GRANT replication ON 'posts' TO 'repl_user';
JOIN CLUSTER posts AT '10.12.1.35:9312' 'repl_user' AS user;

The joining node and donor nodes must have the same user with matching stored authentication data. Creating the same user name and password independently on each node is not enough, because the stored authentication data can differ.

If no user is specified, the current session user is used for the join operation. After a successful join, the stored cluster user is taken from the donor cluster metadata.

NOTE: When authentication is enabled, a successful JOIN CLUSTER replaces all local authentication data on the joining node with the donor cluster's authentication data. If authentication logging is at info or higher, Manticore writes the previous local auth data to searchd.log.auth as a JSON backup before replacement. This backup includes salts and credential hashes, so keep the auth log private and redact it before sharing. If JOIN CLUSTER cannot fetch the donor user, verify the replication user and matching auth data on donor nodes, and check searchd.log.auth on the donor nodes for API authentication failures.

In most cases, the above is sufficient when there is a single replication cluster. However, if you are creating multiple replication clusters, you must also set the path and ensure that the directory is available.

‹›

SQL
JSON

📋

JOIN CLUSTER c2 at '127.0.0.1:10201' 'c2' as path

A node joins a cluster by obtaining data from a specified node and, if successful, updates the node lists across all other cluster nodes in the same way as if it was done manually through ALTER CLUSTER ... UPDATE nodes. This list is used to re-join nodes to the cluster upon restart.

There are two lists of nodes: 1.cluster_<name>_nodes_set: used to re-join nodes to the cluster upon restart. It is updated across all nodes in the same way as ALTER CLUSTER ... UPDATE nodes does. JOIN CLUSTER command performs this update automatically. The Cluster status displays this list as cluster_<name>_nodes_set. 2. cluster_<name>_nodes_view: this list contains all active nodes used for replication and does not require manual management. ALTER CLUSTER ... UPDATE nodes actually copies this list of nodes to the list of nodes used to re-join upon restart. The Cluster status displays this list as cluster_<name>_nodes_view.

When nodes are located in different network segments or data centers, the nodes option may be set explicitly. This minimizes traffic between nodes and utilizes gateway nodes for intercommunication between data centers. The following code joins an existing cluster using the nodes option.

Note: The cluster cluster_<name>_nodes_set list is not updated automatically when this syntax is used. To update it, use ALTER CLUSTER ... UPDATE nodes.

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

JOIN CLUSTER click_query 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312' as nodes

POST /cli -d "
JOIN CLUSTER click_query 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312' as nodes
"

$params = [
  'cluster' => 'posts',
  'body' => [
      'nodes' => 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312'
  ]
];
$response = $client->cluster->join($params);

utilsApi.sql('JOIN CLUSTER click_query \'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312\' as nodes')

await utilsApi.sql('JOIN CLUSTER click_query \'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312\' as nodes')

res = await utilsApi.sql('JOIN CLUSTER click_query \'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312\' as nodes');

utilsApi.sql("JOIN CLUSTER click_query 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312' as nodes");

utilsApi.Sql("JOIN CLUSTER click_query 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312' as nodes");

utils_api.sql("JOIN CLUSTER click_query 'clicks_mirror1:9312;clicks_mirror2:9312;clicks_mirror3:9312' as nodes", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

{u'error': u'', u'total': 0, u'warning': u''}

{"total":0,"error":"","warning":""}

The JOIN CLUSTER command works synchronously and completes as soon as the node receives all data from the other nodes in the cluster and is in sync with them.

The JOIN CLUSTER operation can fail with an error message indicating a duplicate server_id. This occurs when the joining node has the same server_id as an existing node in the cluster. To resolve this issue, ensure that each node in the replication cluster has a unique server_id. You can change the default server_id in the "searchd" section of your configuration file to a unique value before attempting to join the cluster.

Deleting a replication cluster

Last modified: June 16, 2026

The DELETE CLUSTER statement removes the specified cluster with its name. Once the cluster is deleted, it is removed from all nodes, but its tables remain intact and become active local non-replicated tables.

If you only need to detach the current node and leave the rest of the cluster running, use EXIT CLUSTER instead. See Managing replication nodes.

If authentication and authorization is enabled, DELETE CLUSTER uses the stored cluster user. That user must have matching authentication data on the participating nodes and replication permission on the cluster target.

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

DELETE CLUSTER click_query

POST /cli -d "DELETE CLUSTER click_query"

$params = [
    'cluster' => 'click_query',
    'body' => []
];
$response = $client->cluster()->delete($params);

utilsApi.sql('DELETE CLUSTER click_query')

await utilsApi.sql('DELETE CLUSTER click_query')

res = await utilsApi.sql('DELETE CLUSTER click_query');

utilsApi.sql("DELETE CLUSTER click_query");

utilsApi.Sql("DELETE CLUSTER click_query");

utils_api.Sql("DELETE CLUSTER click_query", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

{u'error': u'', u'total': 0, u'warning': u''}

{"total":0,"error":"","warning":""}

Joining a replication cluster Adding and removing a table from a replication cluster

Last modified: June 16, 2026

ALTER CLUSTER <cluster_name> ADD <table_name>[, <table_name>] adds one or more existing local tables to the cluster. The node that receives the ALTER query sends the table(s) to the other nodes in the cluster. All the local tables with the same name on the other nodes of the cluster are replaced with the new table(s).

Once the tables are replicated, write statements can be performed on any node, but the table names must be prefixed with the cluster name, like INSERT INTO <clusterName>:<table_name>.

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

ALTER CLUSTER click_query ADD clicks_daily_table

POST /cli -d "
ALTER CLUSTER click_query ADD clicks_daily_table
"

$params = [
  'cluster' => 'click_query',
  'body' => [
     'operation' => 'add',
     'table' => 'clicks_daily_table'
  ]
];
$response = $client->cluster()->alter($params);

utilsApi.sql('ALTER CLUSTER click_query ADD clicks_daily_table')

await utilsApi.sql('ALTER CLUSTER click_query ADD clicks_daily_table')

res = await utilsApi.sql('ALTER CLUSTER click_query ADD clicks_daily_table');

utilsApi.sql("ALTER CLUSTER click_query ADD clicks_daily_table");

utilsApi.Sql("ALTER CLUSTER click_query ADD clicks_daily_table");

utils_api.sql("ALTER CLUSTER click_query ADD clicks_daily_table", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

ALTER CLUSTER <cluster_name> DROP <table_name>[, <table_name>] forgets about one or more existing table(s), meaning it does not remove the table(s) files on the nodes, but rather just makes them inactive, non-replicated table(s).

Once a table is removed from a cluster, it becomes a local table, and write statements must use just the table name, like INSERT INTO <table_name>, without the cluster prefix.

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

ALTER CLUSTER posts DROP weekly_index

POST /cli -d "
ALTER CLUSTER posts DROP weekly_index
"

$params = [
  'cluster' => 'posts',
  'body' => [
     'operation' => 'drop',
     'table' => 'weekly_index'
  ]
];
$response = $client->cluster->alter($params);

utilsApi.sql('ALTER CLUSTER posts DROP weekly_index')

await utilsApi.sql('ALTER CLUSTER posts DROP weekly_index')

res = await utilsApi.sql('ALTER CLUSTER posts DROP weekly_index');

utilsApi.sql("ALTER CLUSTER posts DROP weekly_index");

utilsApi.Sql("ALTER CLUSTER posts DROP weekly_index");

utils_api.sql("ALTER CLUSTER posts DROP weekly_index", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

{u'error': u'', u'total': 0, u'warning': u''}

{"total":0,"error":"","warning":""}

Deleting a replication cluster Managing replication nodes

Last modified: June 26, 2026

The ALTER CLUSTER <cluster_name> UPDATE nodes statement updates the node lists on each node within the specified cluster to include all active nodes in the cluster. For more information on node lists, see Joining a cluster.

‹›

SQL
JSON
PHP
Python
Python-asyncio
javascript
Java
C#
Rust

📋

ALTER CLUSTER posts UPDATE nodes

POST /cli -d "
ALTER CLUSTER posts UPDATE nodes
"

$params = [
  'cluster' => 'posts',
  'body' => [
     'operation' => 'update',
  ]
];
$response = $client->cluster()->alter($params);

utilsApi.sql('ALTER CLUSTER posts UPDATE nodes')

await utilsApi.sql('ALTER CLUSTER posts UPDATE nodes')

res = await utilsApi.sql('ALTER CLUSTER posts UPDATE nodes');

utilsApi.sql("ALTER CLUSTER posts UPDATE nodes");

utilsApi.Sql("ALTER CLUSTER posts UPDATE nodes");

utils_api.sql("ALTER CLUSTER posts UPDATE nodes", Some(true)).await;

‹›

Response

{u'error': u'', u'total': 0, u'warning': u''}

{u'error': u'', u'total': 0, u'warning': u''}

{"total":0,"error":"","warning":""}

If authentication and authorization is enabled, ALTER CLUSTER ... UPDATE nodes, ALTER CLUSTER ... ADD, and ALTER CLUSTER ... DROP use the stored cluster user. To change the stored cluster user, grant replication permission to the new user and run:

ALTER CLUSTER posts UPDATE user 'repl_user'

The new stored user must be provisioned with matching authentication data on the nodes that will participate in later cluster operations. Those operations fail if the stored user is missing, has different auth data, or loses replication permission.

For instance, when the cluster was initially established, the list of nodes used to rejoin the cluster was 10.10.0.1:9312,10.10.1.1:9312. Since then, other nodes joined the cluster and now the active nodes are 10.10.0.1:9312,10.10.1.1:9312,10.15.0.1:9312,10.15.0.3:9312.However, the list of nodes used to rejoin the cluster has not been updated.

To rectify this, you can run the ALTER CLUSTER ... UPDATE nodes statement to copy the list of active nodes to the list of nodes used to rejoin the cluster. After this, the list of nodes used to rejoin the cluster will include all the active nodes in the cluster.

Both lists of nodes can be viewed using the Cluster status statement (cluster_post_nodes_set and cluster_post_nodes_view).

To remove a node from the replication cluster, follow these steps:

Stop the node
Remove the information about the cluster from <data_dir>/manticore.json (usually /var/lib/manticore/manticore.json) on the node that has been stopped.
Run ALTER CLUSTER cluster_name UPDATE nodes on any other node.

After these steps, the other nodes will forget about the detached node and the detached node will forget about the cluster. This action will not impact the tables in the cluster or on the detached node.

EXIT CLUSTER <cluster_name> is the online equivalent of the manual detach flow above. It removes the local node from the replication cluster, keeps the local tables intact as regular local tables, saves the local config, and then asks the surviving peers to refresh their persisted node lists using the existing ALTER CLUSTER ... UPDATE nodes machinery.

EXIT CLUSTER posts

Use EXIT CLUSTER when you want to detach only the current node. Use DELETE CLUSTER when you want to remove the cluster from every node.

EXIT CLUSTER is only allowed for a healthy local node in a primary cluster. If the command returns a warning, the local detach already succeeded, but some follow-up may still be required. In that case run ALTER CLUSTER <cluster_name> UPDATE nodes on any surviving node to finish refreshing the remaining cluster metadata.

If the surviving side becomes a clean one-node cluster after EXIT CLUSTER, it remains a replication cluster. After a clean shutdown, that surviving node can be started normally and should return as primary / synced; you do not need --new-cluster for this self-only case.

Adding and removing a table from a replication cluster Replication cluster status

Last modified: June 30, 2026

Joining a replication cluster

Deleting a replication cluster

Adding and removing a table from a replication cluster

Managing replication nodes

Removing node from cluster

EXIT CLUSTER