Managing servers in a cluster

When a server is discovered by the discovery service (see 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.

A server in the free state needs to be explicitly enabled in order to be considered an active member of the cluster. The command ENABLE SERVER server name is used to transition a server into this Enabled state. 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:

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

When a server is no longer needed, it cannot be removed from the cluster while it is still allocated to host any databases. The command DEALLOCATE DATABASE[S] FROM SERVER[S] server[,…​] is used to transition servers to the Deallocating state, reallocating all their hosted databases to other servers in the cluster. Additionally, servers which are deallocating will not have any further databases allocated to them.

The Cordoned state is similar to Deallocating in that servers in this state will not be allocated to host additional databases. Unlike Deallocating however, cordoned servers do not lose the databases they already host. It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.

A server is transitioned from the Enabled state to the Cordoned state by executing the procedure dbms.cluster.cordonServer. A server in the Cordoned state may be transitioned to Deallocating, or back to Enabled.

This state is primarily used for error handling.

Once a server is in state Deallocating and is only hosting the system database, it is safe to drop it. The command DROP SERVER server name logically removes 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. Once the Neo4j process is stopped, the server finally disappears. Once dropped, a server cannot rejoin a cluster.

Once enabled, a server does not automatically host databases unless:

The command REALLOCATE DATABASE[S] can be used to rebalance database allocations across the cluster, adding some to the newly added server(s), see Reallocate databases for more information.

In preparation for removing a server from the cluster, set it to not host any databases with DEALLOCATE DATABASES FROM SERVER 'name' (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 5 servers and a database foo has a topology requiring 3 primaries and 2 secondaries, then it is not possible to deallocate any of the original 5 servers, without first enabling a 6th, 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 for 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.