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.

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.endpoints`	This setting contains the network for at least one server in the cluster and 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.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.

The following example shows how to set up a basic cluster with three servers with primary hosting capabilities.

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.

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:

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" | "server001:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "e56b49ea-243f-11ed-861d-0242ac120002" | "server002:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server003: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" | "server001:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | []   | []               | []              | "NONE"         | "5.0.0"     |
| "e56b49ea-243f-11ed-861d-0242ac120002" | "e56b49ea-243f-11ed-861d-0242ac120002" | "server002:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | []   | []               | []              | "NONE"         | "5.0.0"     |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server003: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.

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 cluster with predominantly primaries is preferred for fault tolerance and automatic failover.

The cluster can preferably have more secondaries 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.

Was this page helpful?