ALTER SYSTEM

ALTER SYSTEM Manages FE, BE, CN, Broker nodes, and metadata snapshots in a cluster.

NOTE

Only the cluster_admin role has the privilege to perform this operation.

Syntax and parameters

FE

• Add a Follower FE.

  ALTER SYSTEM ADD FOLLOWER "<fe_host>:<edit_log_port>"[, ...]
  

  You can check the status of the new Follower FE by executing SHOW PROC '/frontends'\G.

• Drop a Follower FE.

  ALTER SYSTEM DROP FOLLOWER "<fe_host>:<edit_log_port>"[, ...]
  

• Add an Observer FE.

  ALTER SYSTEM ADD OBSERVER "<fe_host>:<edit_log_port>"[, ...]
  

  You can check the status of the new Observer FE by executing SHOW PROC '/frontends'\G.

• Drop an Observer FE.

  ALTER SYSTEM DROP OBSERVER "<fe_host>:<edit_log_port>"[, ...]
  

• Transfer the Leader role to another Follower FE (graceful in-place handoff).

  ALTER SYSTEM TRANSFER LEADER TO "<fe_host>:<edit_log_port>" [FORCE]
  

  The target must be an alive Follower FE. This statement runs on the current Leader FE and hands the Leader role to the target Follower; the previous Leader then transitions to a Follower in place instead of restarting. Check the new Leader with SHOW PROC '/frontends'\G. With FORCE, the statement supersedes a Leader transfer that is already in progress at the BDBJE layer; without FORCE, it fails if such a transfer is in progress. Concurrent TRANSFER LEADER statements are serialized on the Leader: a queued statement waits for the previous one to finish, and returns an error if this FE is no longer the Leader when it gets its turn (it does not trigger a second transfer).

  Failure semantics: if the transfer itself fails (for example, the target cannot catch up within the internal 30-second window, or its cluster membership is not fully acknowledged yet), the statement returns an error and the current Leader stays unchanged - a safe outcome you can simply retry. If the transfer succeeds but the old Leader cannot drain its in-flight work within leader_demotion_drain_timeout_sec, the old Leader process exits and restarts as a Follower; the new Leader is unaffected.

  This statement is not supported in shared-data clusters and returns an error there; to transfer leadership in shared-data mode, restart the current Leader FE to trigger an election.

Parameter	Required	Description
fe_host	Yes	The host name or IP address of the FE instance. Use the value of configuration item priority_networks if your instance has multiple IP addresses.
edit_log_port	Yes	BDB JE communication port of the FE node. Default: 9010.
FORCE	No	Supersede a Leader transfer that is already in progress at the BDBJE layer. Without it, the statement fails if such a transfer is in progress. Concurrent TRANSFER LEADER statements are serialized and do not need FORCE.

BE

• Add a BE node.

  ALTER SYSTEM ADD BACKEND "<be_host>:<heartbeat_service_port>"[, ...]
  

  You can check the status of the new BE by executing SHOW BACKENDS.

• Drop a BE node.

  NOTE

  You cannot drop the BE node that stores the tablets of single-replica tables.

  ALTER SYSTEM DROP BACKEND "<be_host>:<heartbeat_service_port>"[, ...]
  

• Decommission a BE node.

  ALTER SYSTEM DECOMMISSION BACKEND "<be_host>:<heartbeat_service_port>"[, ...]
  

  Unlike dropping a BE node, which is removing it forcibly from the cluster, decommissioning a BE means removing it safely. It is an asynchronous operation. When a BE is decommissioned, the data on the BE is first migrated to other BEs, and then the BE is removed from the cluster. Data loading and query will not be affected during the data migration. You can check whether the operation is successful using SHOW BACKENDS. If the operation is successful, the decommissioned BE will not be returned. If the operation fails, the BE will still be online. You can manually cancel the operation using CANCEL DECOMMISSION.

Parameter	Required	Description
be_host	Yes	The host name or IP address of the BE instance. Use the value of configuration item priority_networks if your instance has multiple IP addresses.
heartbeat_service_port	Yes	BE heartbeat service port. BE uses this port to receive heartbeat from FE. Default: 9050.

CN

• Add a CN node.

  ALTER SYSTEM ADD COMPUTE NODE "<cn_host>:<heartbeat_service_port>"[, ...]
  

  You can check the status of the new CN by executing SHOW COMPUTE NODES.

• Drop a CN node.

  ALTER SYSTEM DROP COMPUTE NODE "<cn_host>:<heartbeat_service_port>"[, ...]
  

NOTE

You cannot decommission a CN node using the ALTER SYSTEM DECOMMISSION command.

Parameter	Required	Description
cn_host	Yes	The host name or IP address of the CN instance. Use the value of configuration item priority_networks if your instance has multiple IP addresses.
heartbeat_service_port	Yes	CN heartbeat service port. CN uses this port to receive heartbeat from FE. Default: 9050.

Broker

• Add Broker nodes. You can use Broker nodes to load data from HDFS or cloud storage into StarRocks. For more information, see Loading.

  ALTER SYSTEM ADD BROKER <broker_name> "<broker_host>:<broker_ipc_port>"[, ...]
  

  You can add multiple Broker nodes with one SQL. Each <broker_host>:<broker_ipc_port> pair represents one Broker node. And they share a common broker_name. You can check the status of the new Broker node by executing SHOW BROKER.

• Drop Broker nodes.

CAUTION

Dropping a Broker node terminates the tasks currently running on it.

• Drop one or multiple Broker nodes with the same broker_name.

  ALTER SYSTEM DROP BROKER <broker_name> "<broker_host>:<broker_ipc_port>"[, ...]
  

• Drop all Broker nodes with the same broker_name.

  ALTER SYSTEM DROP ALL BROKER <broker_name>
  

Parameter	Required	Description
broker_name	Yes	The name of the Broker node(s). Multiple Broker nodes can use the same name.
broker_host	Yes	The host name or IP address of the Broker instance. Use the value of configuration item priority_networks if your instance has multiple IP addresses.
broker_ipc_port	Yes	The thrift server port on the Broker node. The Broker node uses it to receive requests from FE or BE. Default: 8000.

Create image

Create an image file. An image file is a snapshot of the FE metadata.

ALTER SYSTEM CREATE IMAGE

Creating an image is an asynchronous operation on the Leader FE. You can check the start time and end time of the operation in the FE log file fe.log. A log like triggering a new checkpoint manually... indicates that the image creation has started, and a log like finished save image... indicates the image has been created.

Usage notes

• Adding and dropping FE, BE, CN, or Broker nodes are synchronous operations. You cannot cancel the node dropping operations.
• You cannot drop the FE node in a single-FE cluster.
• You cannot directly drop the Leader FE node in a multi-FE cluster. To drop it, you must first restart it. After StarRocks elects a new Leader FE, you can then drop the previous one.
• You cannot drop BE nodes if the number of the remained BE nodes is less than the number of data replicas. For example, if you have three BE nodes in your cluster and you store your data in three replicas, you cannot drop any of the BE nodes. And if you have four BE nodes and three replicas, you can drop one BE node.
• The difference between dropping and decommissioning a BE node is that, when you drop a BE node, StarRocks removes it forcibly from the cluster and make up the dropped tablets after the removal, and when you decommission a BE node, StarRocks first migrates the tablets on the decommissioned BE node to others, and then removes the node.

Examples

Example 1: Add a Follower FE node.

ALTER SYSTEM ADD FOLLOWER "x.x.x.x:9010";

Example 2: Drop two Observer FE nodes simultaneously.

ALTER SYSTEM DROP OBSERVER "x.x.x.x:9010","x.x.x.x:9010";

Example 3: Add a BE node.

ALTER SYSTEM ADD BACKEND "x.x.x.x:9050";

Example 4: Drop two BE nodes simultaneously.

ALTER SYSTEM DROP BACKEND "x.x.x.x:9050", "x.x.x.x:9050";

Example 5: Decommission two BE nodes simultaneously.

ALTER SYSTEM DECOMMISSION BACKEND "x.x.x.x:9050", "x.x.x.x:9050";

Example 6: Add two Broker nodes with the same broker_name - hdfs.

ALTER SYSTEM ADD BROKER hdfs "x.x.x.x:8000", "x.x.x.x:8000";

Example 7: Drop two Broker nodes from amazon_s3.

ALTER SYSTEM DROP BROKER amazon_s3 "x.x.x.x:8000", "x.x.x.x:8000";

Example 8: Drop all Broker nodes in amazon_s3.

ALTER SYSTEM DROP ALL BROKER amazon_s3;

Example 9: Transfer the Leader role to a specific Follower FE.

ALTER SYSTEM TRANSFER LEADER TO "x.x.x.x:9010";