# 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 it does not change the node's process host/port itself. You must update the node's configuration (in the [memsql.cnf](https://docs.singlestore.com/db/v9.1/reference/configuration-reference/cluster-config-files/singlestore-node-config-files.md) file) and restart the node to apply the updates.

Perform the following tasks to update the internal host or port of a node:

1. Detach 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>
   ```

2. Update the host/port configuration in the `memsql.cnf` file of the stopped leaf node.

3. Run the `ALTER NODE` command to update the cluster metadata. For example:
   ```sql
   ALTER NODE '<host>':<port> SET HOST '<new_host>', PORT <new_port>;
   ```

4. Start the leaf node.
   ```shell
   sdb-admin start-node --memsql-id <node_memsql_id>
   ```

5. Attach the leaf node to the cluster, without rebalancing.
   ```sql
   ATTACH LEAF '<new_host>':<new_port> NO REBALANCE;
   ```

6. Perform steps 1 to 5 for each target node to update, and then rebalance all databases.
   ```sql
   REBALANCE ALL DATABASES;
   ```

This workflow keeps all the database partitions on their existing leaves during host/port change and defers the data movement to a single rebalance operation.

## Examples

```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 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: June 11, 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)