Move from a standalone deployment to a cluster

It is possible to move from a standalone deployment with a single system database to a cluster with multiple system primaries. In essence, this is done by dumping the system database from the standalone server and loading it into the other servers that are to form the cluster. The following example shows how to move from a standalone server with a single system primary to a cluster with three system primaries.

Another deployment with a single system database is an analytics cluster with a single system primary. If desired to move to a cluster with multiple system primaries, the following example is applicable with the addition that the secondaries are discarded (this is done in the first step when the neo4j.conf file is modified). See Deploy an analytics cluster for more information on analytics clusters.

Example 1. Move from a single system database to a cluster with three system primaries

In this example, a standalone server named server01 is running and two additional servers, server02 and server03, are to be added to form a cluster. The two additional servers are configured according to Configure a cluster with three servers and are not running. Neo4j Enterprise Edition is installed on all three servers.

Start by stopping the standalone server. Once it is stopped, edit the neo4j.conf file to include the discovery endpoints of itself and the servers that will form the cluster.

Starting with Neo4j 5.23, it is recommended to use v2 of the discovery service. For more details on discovery services, see Cluster server discovery.

To use the discovery service v2:

You have to set the configuration of dbms.cluster.discovery.version to V2_ONLY.
Instead of dbms.cluster.discovery.endpoints, use dbms.cluster.discovery.v2.endpoints.

The example below uses dbms.cluster.discovery.resolver_type=LIST.

neo4j.conf on server01.example.com:

server.default_listen_address=0.0.0.0
server.default_advertised_address=server01.example.com
dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
dbms.cluster.discovery.version=V2_ONLY
initial.dbms.default_primaries_count=3

(The neo4j.conf file looks identical except for the server.default_advertised_address on all three servers. Please refer to Configure a cluster with three servers for more information.)

On server01 (the standalone server) dump the system database using the neo4j-admin database dump command.

bin/neo4j-admin database dump system --to-path=/full/path/to/dumps/

See Back up an offline database for more information on the dump command.

Use the neo4j-admin database load command to load the system database dump from server01 to server02 and server03.

bin/neo4j-admin database load --from-path=/full-path/data/dumps system

See Restore a database dump for more information on the load command.

Once the system database has been loaded on server02 and server03, start all servers. The newly added servers should be in the Free state (server02 and server03) and this can be verified using SHOW SERVERS.

SHOW SERVERS;

+-----------------------------------------------------------------------------------------------------------+
| name                                   | address         | state     | health      | hosting              |
+-----------------------------------------------------------------------------------------------------------+
| "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"]  |
| "e56b49ea-243f-11ed-861d-0242ac120002" | "server02:7687" | "Free"    | "Available" | ["system"]           |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Free"    | "Available" | ["system"]           |
+-----------------------------------------------------------------------------------------------------------+

On server01 (the previously standalone server) verify that all user databases are still running using SHOW DATABASES.

The last step is to enable the Free servers using ENABLE SERVER (see Managing servers in a cluster for more information on server states).

Once all servers are enabled, you can scale up user databases using ALTER DATABASE, if desired.

Start by stopping the standalone server and once it is stopped, edit the neo4j.conf file to include the discovery endpoints of itself and the servers that will form the cluster.