Managing servers in a cluster

Enterprise Edition

When a server is discovered by the discovery service (see Setting up a cluster → Cluster server discovery for more information), it is created in the free state. Servers in this state have a unique automatically generated ID, but are otherwise unconfigured. These free servers are not yet part of the cluster and cannot be allocated to host any databases.

When you deploy a cluster for the first time, at least the minimum number of servers included in the initial deployment are automatically enabled. For details, refer to the example on how to Configure a cluster with three servers.

If you add a new server after the cluster is already running, the server is added in the Free state. A server in the Free state needs to be explicitly enabled in order to be considered an active member of the cluster.

To transition a server into the enabled state, use the command ENABLE SERVER:

The server’s initial name is its ID. If the server is already enabled and the command is executed with the same options, nothing is changed.

The possible options when enabling a server are:

Another way to enable servers is to configure the DBMS automatically enable free servers. You can do this in one of two ways:

Once enabled, the server may be allocated databases to host.

If you need to change some of the server’s values, use the ALTER SERVER command.

A server in a cordoned state cannot be assigned to host any newly created databases; however, the server retains the databases it already hosts.

This state is primarily used for error handling.

To transition a server from the enabled to the cordoned state, run the dbms.cluster.cordonServer() procedure. Keep in mind that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.

A server in the cordoned state can be transitioned to deallocating state or back to enabled. To re-enable a server, run the ENABLE SERVER command. In Cypher 5, you can also use the dbms.cluster.uncordonServer() procedure.

A deallocating state means a server can no longer host databases. It may be that the server is no longer needed and you want to remove it from the cluster.

To transition servers to the deallocating state, run the following command:

The command reallocates all user databases hosted by the server to other servers in the cluster. This state is irreversible. Once a server is in a deallocating state, it subsequently cannot have any further databases allocated to it.

However, you can deallocate databases from a server in a reversible manner by running one of the following procedures:

For details, see Managing databases in a cluster → Deallocate databases.

The deallocated state means that a server no longer hosts any databases besides the system database and can be removed from the cluster. Additionally, deallocated servers cannot have any further databases allocated to them.

Note that there is a known situation in which a previously deallocated offline server can transiently show as deallocating when restarting, it will, however, eventually return to the deallocated state without intervention.

The dropped state means a server has been removed from the cluster but remains visible to the other cluster members.

Once a server is in the deallocated state and is only hosting the system database, it is safe to remove it. Use the command DROP SERVER 'server name' to remove the server from the cluster.

However, as long as the server’s Neo4j process is running, it is still visible to the other cluster members in the dropped state. When the Neo4j process is stopped, the server finally disappears. Once dropped, a server cannot rejoin a cluster.

In preparation for removing a server from the cluster, set it to not host any databases with the DEALLOCATE DATABASES FROM SERVER 'name' command.

See deallocating state for more information.

Either the server ID or its name can be used with the DEALLOCATE DATABASES command:

When deallocating databases from servers, it is important to be mindful of the topology for each database to ensure that there are sufficient servers left in the cluster to satisfy the topologies of each database. Attempting to deallocate database(s) from a server that would result in less available servers than required fails with an error and no changes are made.

For example, if the cluster contains five servers and a database foo has a topology requiring three primary copies and two secondary copies, then it is not possible to deallocate any of the original five servers, without first adding and enabling new unconstrained servers, or altering the desired topology of foo to require fewer servers overall.

The command can be used with DRYRUN to get a view of how the databases would be moved from the deallocated server(s).

Once the command has been executed, the server changes state to Deallocating and it cannot readily be enabled again. See dropped state for more information.

Once DEALLOCATE DATABASES is executed against a server, its databases begin being moved. It is important not to attempt the next step before SHOW SERVERS reports that the deallocating server is in the deallocated state.

For example, do not drop the server 135ad202-5405-4d3c-9822-df39f59b823c given the following output:

The deallocation process may take some time, as foo must be successfully copied and started on a new server before it is stopped on 135ad202-5405-4d3c-9822-df39f59b823c in order to preserve the availability and fault tolerance of foo.

Once SHOW SERVERS reflects that the server is Deallocated and thus no longer hosts foo, the server may be dropped. Either the server ID or its name can be used:

Once this command has been executed successfully, the Neo4j process on the server in question may be stopped.

A running server can have its options modified using the ALTER SERVER 'name' SET OPTIONS { option: value } command. Either the ID or the name of the server can be used.

For example, to prevent a server from hosting databases in PRIMARY, execute the following:

Altering servers may cause databases to be moved, and should be performed with care. For example, if the server 25a7efc7-d063-44b8-bdee-f23357f89f01 hosts database foo in primary mode when the above command is executed, then another server must begin hosting foo in primary mode.

Likewise, if ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {allowedDatabases:['bar','baz']}; is executed, then foo is forced to move.

The possible options when altering a server are:

As with the DEALLOCATE DATABASES FROM SERVER …​ command, if the alteration of a server’s options renders it impossible for the cluster to satisfy one or more of the databases' topologies, then the command fails and no changes are made.

When first discovered, a server’s name defaults to the value of its generated server ID. However, as long as the server is enabled, this can be changed later using the following command:

This only affects the name of the server; the ID of the server remains fixed as 25a7efc7-d063-44b8-bdee-f23357f89f01. Keep in mind that the name of the server must be unique among existing servers.