Deploy a basic cluster

The first step in setting up a cluster infrastructure is configuring a number of servers to form a cluster that you can host your databases on. The following configuration settings are important to consider when deploying a new cluster. See also Settings reference for more detailed descriptions and examples.

Starting with Neo4j 5.23, you get the option to choose between two discovery services: v1 or v2. They are designed to run independently and in parallel. However, the new version, v2, is recommended for new deployments, as v1 has been considered deprecated since Neo4j 5.23. For more details, see Cluster server discovery.

Table 1. Important settings for clusters
Option name	Description
`server.default_advertised_address`	The address that other machines are told to connect to. In the typical case, this should be set to the fully qualified domain name or the IP address of this server.
`server.default_listen_address`	The address or network interface this machine uses to listen for incoming messages. Setting this value to `0.0.0.0` makes Neo4j bind to all available network interfaces.
`dbms.cluster.discovery.v2.endpoints` Introduced in 5.22	A comma-separated list of endpoints that a server should contact in order to discover other cluster members. Typically, all cluster members, including the current server, must be specified in this list. The setting configures the endpoints for discovery service v2.
`dbms.cluster.discovery.version` Introduced in 5.22	This setting allows you to select which discovery service should be started.
`dbms.cluster.discovery.endpoints` Deprecated in 5.23	The discovery network address for all the members of the cluster, including this server. The setting must be set to the same value on all cluster members. The behavior of this setting can be modified by configuring the setting `dbms.cluster.discovery.resolver_type`. This is described in detail in Cluster server discovery.
`initial.dbms.default_primaries_count`	The number of initial database hostings in primary mode. If not specified, it defaults to one hosting in primary mode.
`initial.dbms.default_secondaries_count`	The number of initial database hostings in secondary mode. If not specified, it defaults to zero hostings in secondary mode.

Any setting with the initial prefix is only effective on the first startup of the DBMS. Changing the default number of primaries and secondaries dynamically can only be done with the dbms.setDefaultAllocationNumbers procedure. See CREATE DATABASE for more information. To view the current default settings, use the dbms.showTopologyGraphConfig procedure.

Configuring any listen address to be something other than localhost, 127.0.0.1, or another loopback address, will expose the Neo4j process to connections from outside of the server that it is running on.

Make sure you understand the security implications and strongly consider setting up encryption.

Configure a cluster with three servers

The following example shows how to set up a basic cluster with three members hosting the default database, neo4j (in addition to the system database), in primary mode, using the method of server addresses list.

Depending on the type of dbms.cluster.discovery.resolver_type currently in use, the discovery service can use a list of server addresses, DNS records, or Kubernetes services to discover other servers in the cluster.

In this case, you set dbms.cluster.discovery.resolver_type=LIST.

Example 1. Configure a cluster with three servers in primary mode

In this example, three servers named server01.example.com, server02.example.com and server03.example.com are configured. Neo4j Enterprise Edition is installed on all three servers. They are configured by preparing neo4j.conf on each server.

Note that they are all identical, except for the configuration of server.default_advertised_address.

To use 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.

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

neo4j.conf on server02.example.com:

server.default_listen_address=0.0.0.0
server.default_advertised_address=server02.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

neo4j.conf on server03.example.com:

server.default_listen_address=0.0.0.0
server.default_advertised_address=server03.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 servers are ready to be started. The startup order does not matter.

After the cluster has started, it is possible to connect to any of the instances and run SHOW SERVERS to check the status of the cluster. This shows information about each member of the cluster:

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" | "Enabled" | "Available" | ["system", "neo4j"] |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
+-----------------------------------------------------------------------------------------------------------+

For more extensive information about each server, use the SHOW SERVERS YIELD * command:

SHOW SERVERS YIELD *;

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

Startup time

The instance may appear unavailable while it is joining the cluster. If you want to follow along with the startup, you can see the messages in neo4j.log.

neo4j.conf on server01.example.com:

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

neo4j.conf on server02.example.com:

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

neo4j.conf on server03.example.com:

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

The Neo4j servers are ready to be started. The startup order does not matter.

After the cluster has started, it is possible to connect to any of the instances and run SHOW SERVERS to check the status of the cluster. This shows information about each member of the cluster:

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" | "Enabled" | "Available" | ["system", "neo4j"] |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
+-----------------------------------------------------------------------------------------------------------+

For more extensive information about each server, use the SHOW SERVERS YIELD * command:

SHOW SERVERS YIELD *;

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

Startup time

The instance may appear unavailable while it is joining the cluster. If you want to follow along with the startup, you can see the messages in neo4j.log.

The setting dbms.cluster.minimum_initial_system_primaries_count must be set to 2 on all servers in case setting up a cluster with only two servers.

Create new databases in a cluster

As mentioned in the Introduction, a server in a cluster can either host a database in primary or secondary mode. For transactional workloads, a database topology with several primaries is preferred for fault tolerance and automatic failover.

The database topology might prioritize secondaries over primaries if the workload is more analytical. Such configuration is optimized for scalability but it is not fault-tolerant and does not provide automatic failover. Both scenarios are covered in the following examples.

Example 2. Create a new database with three primaries

In the system database on one of the servers from the previous example, execute the following Cypher command to create a new database:

CREATE DATABASE foo
TOPOLOGY 3 PRIMARIES

If TOPOLOGY is not specified, the database is created according to initial.dbms.default_primaries_count specified in neo4j.conf. Also, if initial.dbms.default_secondaries_count is specified to any other number than 0, the second line of the command would read TOPOLOGY 3 PRIMARIES 0 SECONDARIES. Thus the number specified with TOPOLOGY overrides both initial.dbms.default_primaries_count and initial.dbms.default_secondaries_count (if applicable) provided that the specified numbers do not exceed the number of available servers.

Example 3. Create a new database with one primary and two secondaries

In the system database on one of the servers from the previous example, execute the following Cypher command to create a new database:

CREATE DATABASE bar
TOPOLOGY 1 PRIMARY 2 SECONDARIES

Note that this operation is possible even without specifying initial.dbms.default_secondaries_count in the initial configuration. Anything specified in the TOPOLOGY part of the Cypher command overrides the initial.dbms.default_secondaries_count setting.

Analytic use cases

To learn more about setting up a cluster specifically for analytic use cases, see Deploy an analytics cluster.