# ALTER NODE

While each node in a cluster resides on a specific host, the host itself can be part of multiple networks, both internal and external, and thus can be addressed by multiple hostnames and/or IP addresses. By extension, each node that resides on this type of host can also be addressed by multiple hostnames and/or IP addresses, both internal and external.

The `ALTER NODE` command can be used to set:

* An external hostname or IP address with which to address a node.
* An external port with which to connect to a node.
* The internal host or port metadata of the leaf node in the cluster.

## Syntax

```sql
ALTER NODE <host>:<port> 
{ SET EXTERNAL_HOST=<external_host>, EXTERNAL_PORT=<external_port> |
  SET [HOST=<internal_host>,] PORT=<internal_port>
}
```

## Arguments

* `<host>`: The node’s host (hostname or IP address).
* `<port>`: The node’s port on the host.
* `<external_host>`: The external host (hostname or IP address) with which to address the node.
* `<external_port>`: The external port with which to connect to the node.
* `<internal_host>`: New internal hostname or IP address for the node.
* `<internal_port>`: New internal port on which the node listens for cluster traffic.

## Remarks

* If only updating the host, `<port>` and `<external_port>` can be the same value.
* If only updating the port, `<host>` and `<external_host>` can be the same value.
* The `ALTER NODE` command is used when the secondary cluster connects to the primary cluster during disaster recovery (DR) replication.

  * DR connections are made from nodes on the secondary cluster to nodes on the primary cluster.
  * The nodes on the secondary cluster use the external host and external port to make these connections.
  * If the host and/or port are not specified, the host and/or port are used that were initially defined when the leaf node was added to the cluster.
* The SingleStore database user must have the [`CLUSTER`](https://docs.singlestore.com/db/v9.1/reference/sql-reference/security-management-commands/grant.md)privilege to run the `ALTER NODE` command.
* The `ALTER NODE` command returns an error if the external host (hostname or IP address) and/or port are already in use.

## Update Internal Host or Port

`SET HOST, PORT` operates on the cluster metadata and updates the internal host and port metadata that the cluster uses to reach an existing leaf node. It does not change the node's process host/port itself.

To update the internal host and/or port of a node, follow the instructions for the relevant process. This workflow keeps all the database partitions on their existing leaves during host and/or port change and defers the data movement to a single rebalance operation.

* *Update the Internal Host and Port*

  1. **Verify cluster topology**: Check whether the target leaf is online and note its current `MemSQL ID`, `Host`, and `Port`.
     ```shell
     sdb-admin list-nodes
     ```
     ```sql
     SHOW LEAVES;
     ```

  2. **Configure hostname resolution**: When you are changing the hostname of a leaf node, ensure that the new hostname resolves correctly from all the hosts in the cluster.

     1. Check the existing host mapping on each host.
        ```shell
        cat /etc/hosts
        ```

     2. Update the host mapping on each host as required.

     3. Verify hostname resolution and connectivity.
        ```shell
        # Verify hostname resolution
        nslookup <new-hostname>

        # Verify connectivity
        ping <new-hostname>
        ```

  3. **Detach and stop the leaf node**: Detach the leaf node from the cluster and then stop the leaf node.

     Run `sdb-admin list-nodes` to get the node's `MemSQL ID`.
     ```sql
     -- Detach the leaf node from the cluster
     DETACH LEAF 'host':port;
     ```
     ```shell
     # Stop the node
     sdb-admin stop-node --memsql-id <node_memsql_id>
     ```

  4. **Update memsql.cnf**: Update the port configuration in the `memsql.cnf` file of the stopped leaf node. Refer to [SingleStore Node Config Files](https://docs.singlestore.com/db/v9.1/reference/configuration-reference/cluster-config-files/singlestore-node-config-files.md) for more information on the typical location of this file.

  5. **Update the internal host and port**: Run the `ALTER NODE` command to update the internal host and port in the cluster metadata, so that other nodes use the new hostname and/or port when connecting to this leaf node.
     ```sql
     ALTER NODE '<host>':<port> SET HOST = '<new_host>', PORT = <new_port>;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `offline` state.
     ```sql
     SHOW LEAVES;
     ```

  6. **Start the leaf node**: Start the leaf node using the `sdb-admin start-node` command.
     ```shell
     sdb-admin start-node --memsql-id <node_memsql_id>
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `detached` state.
     ```sql
     SHOW LEAVES;
     ```

  7. **Attach the leaf node**: Attach the leaf node to the cluster, without rebalancing.
     ```sql
     ATTACH LEAF '<new_host>':<new_port> NO REBALANCE;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `online` state.
     ```sql
     SHOW LEAVES;
     ```

  8. **Rebalance all databases**: Perform the previous steps for each target node to update, and then rebalance all databases.
     ```sql
     REBALANCE ALL DATABASES;
     ```

  9. **Update Toolbox host registration**: Update Toolbox after the cluster-side host change is complete. Remove the old host configuration from the cluster metadata and register the new host.
     ```shell
     # Remove the old host entry
     sdb-toolbox-config unregister-host --host <old-hostname-or-ip>

     # Register the new host 
     sdb-toolbox-config register-host \
       --host <new-hostname> \
       --identity-file <identity-file>
     ```
     Verify that Toolbox now shows the node under the new hostname.
     ```shell
     sdb-admin list-nodes
     ```Verify that the leaf node is online, the updated hostname is displayed correctly, the node is reachable, and all cluster operations have completed successfully.

* *Update the Internal Host*

  1. **Verify cluster topology**: Check whether the target leaf is online and note its current `MemSQL ID`, `Host`, and `Port`.
     ```shell
     sdb-admin list-nodes
     ```
     ```sql
     SHOW LEAVES;
     ```

  2. **Configure hostname resolution**: When you are changing the hostname of a leaf node, ensure that the new hostname resolves correctly from all the hosts in the cluster.

     1. Check the existing host mapping on each host.
        ```shell
        cat /etc/hosts
        ```

     2. Update the host mapping on each host as required.

     3. Verify hostname resolution and connectivity.
        ```shell
        # Verify hostname resolution
        nslookup <new-hostname>

        # Verify connectivity
        ping <new-hostname>
        ```

  3. **Detach and stop the leaf node**: Detach the leaf node from the cluster and then stop the leaf node.

     Run `sdb-admin list-nodes` to get the node's `MemSQL ID`.
     ```sql
     -- Detach the leaf node from the cluster
     DETACH LEAF 'host':port;
     ```
     ```shell
     # Stop the node
     sdb-admin stop-node --memsql-id <node_memsql_id>
     ```

  4. **Update the internal host**: Run the `ALTER NODE` command to update the internal host in the cluster metadata, so that other nodes use the new hostname when connecting to this leaf node.
     ```sql
     ALTER NODE '<host>':<port> SET HOST = '<new_host>', PORT = <current_port>;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `offline` state.
     ```sql
     SHOW LEAVES;
     ```

  5. **Start the leaf node**: Start the leaf node using the `sdb-admin start-node` command.
     ```shell
     sdb-admin start-node --memsql-id <node_memsql_id>
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `detached` state.
     ```sql
     SHOW LEAVES;
     ```

  6. **Attach the leaf node**: Attach the leaf node to the cluster, without rebalancing.
     ```sql
     ATTACH LEAF '<new_host>':<new_port> NO REBALANCE;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `online` state.
     ```sql
     SHOW LEAVES;
     ```

  7. **Rebalance all databases**: Perform the previous steps for each target node to update, and then rebalance all databases.
     ```sql
     REBALANCE ALL DATABASES;
     ```

  8. **Update Toolbox host registration**: Update Toolbox after the cluster-side host change is complete. Remove the old host configuration from the cluster metadata and register the new host.
     ```shell
     # Remove the old host entry
     sdb-toolbox-config unregister-host --host <old-hostname-or-ip>

     # Register the new host 
     sdb-toolbox-config register-host \
       --host <new-hostname> \
       --identity-file <identity-file>
     ```
     Verify that Toolbox now shows the node under the new hostname.
     ```shell
     sdb-admin list-nodes
     ```Verify that the leaf node is online, the updated hostname is displayed correctly, the node is reachable, and all cluster operations have completed successfully.

* *Update the Internal Port*

  1. **Verify cluster topology**: Check whether the target leaf is online and note its current `MemSQL ID`, `Host`, and `Port`.
     ```shell
     sdb-admin list-nodes
     ```
     ```sql
     SHOW LEAVES;
     ```

  2. **Detach and stop the leaf node**: Detach the leaf node from the cluster and then stop the leaf node.

     Run `sdb-admin list-nodes` to get the node's `MemSQL ID`.
     ```sql
     -- Detach the leaf node from the cluster
     DETACH LEAF 'host':port;
     ```
     ```shell
     # Stop the node
     sdb-admin stop-node --memsql-id <node_memsql_id>
     ```

  3. **Update memsql.cnf**: Update the port configuration in the `memsql.cnf` file of the stopped leaf node. Refer to [SingleStore Node Config Files](https://docs.singlestore.com/db/v9.1/reference/configuration-reference/cluster-config-files/singlestore-node-config-files.md) for more information on the typical location of this file.

  4. **Update the internal port**: Run the `ALTER NODE` command to update the internal port in the cluster metadata, so that other nodes use the new port when connecting to this leaf node.
     ```sql
     ALTER NODE '<host>':<port> SET PORT = <new_port>;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `offline` state.
     ```sql
     SHOW LEAVES;
     ```

  5. **Start the leaf node**: Start the leaf node using the `sdb-admin start-node` command.
     ```shell
     sdb-admin start-node --memsql-id <node_memsql_id>
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `detached` state.
     ```sql
     SHOW LEAVES;
     ```

  6. **Attach the leaf node**: Attach the leaf node to the cluster, without rebalancing.
     ```sql
     ATTACH LEAF '<new_host>':<new_port> NO REBALANCE;
     ```
     Run the `SHOW LEAVES` command. The leaf node must appear with the new host/port mapping in the `online` state.
     ```sql
     SHOW LEAVES;
     ```

  7. **Rebalance all databases**: Perform the previous steps for each target node to update, and then rebalance all databases.
     ```sql
     REBALANCE ALL DATABASES;
     ```Verify that the leaf node is online, the updated hostname is displayed correctly, the node is reachable, and all cluster operations have completed successfully.

## Example

To change the external hostname and port of a node:

```SQL
ALTER NODE '127.0.0.1':3306 SET EXTERNAL_HOST='127.0.0.1', EXTERNAL_PORT=3316;

```

```output

Query OK, 0 rows affected (7 ms)
```

To change the internal host and/or port of a node, follow the instructions in [Update Internal Host or Port](https://docs.singlestore.com/#section-id235501503331678.md).

## Related Topic

[REPLICATE DATABASE](https://docs.singlestore.com/db/v9.1/reference/sql-reference/operational-commands/replicate-database.md)

***

Modified at: July 24, 2026

Source: [/db/v9.1/reference/sql-reference/operational-commands/alter-node/](https://docs.singlestore.com/db/v9.1/reference/sql-reference/operational-commands/alter-node/)

(An index of the documentation is available at /llms.txt)