Deploy a basic cluster
Enterprise Edition

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
Setting 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.endpoints

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

dbms.cluster.minimum_initial_system_primaries_count

Minimum number of machines initially required to form a clustered DBMS. The cluster is considered formed when at least this many members have discovered each other, bound together, and bootstrapped a highly available system database. The default value is 3. As a result, at least this many of the cluster’s initial machines must have server.cluster.system_database_mode set to PRIMARY.

server.cluster.system_database_mode

Users must manually specify the mode for the system database on each server. The default value is PRIMARY.

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.

initial.server.mode_constraint

Specifies the server mode - whether it can host only primary databases, only secondary databases, or both types. Initialized at the first DBMS startup. When a new server is added to the cluster, the setting is used as the default input for the ENABLE SERVER command; can be overriden when the command is executed.

initial.server.allowed_databases

List of database names allowed on this server; all others are denied. When a new server is added to the cluster, the setting is used as the default input for the ENABLE SERVER command; can be overriden when the command is executed.

initial.server.denied_databases

List of database names not allowed on this server. Empty means nothing is denied. When a new server is added to the cluster, the setting is used as the default input for the ENABLE SERVER command; can be overriden when the command is executed.

initial.server.tags

A list of server tag names used by the database allocation and when configuring load balancing and replication policies. Initialized at the first DBMS startup and/or when a newly added server is enabled. The setting is used as the default input for the ENABLE SERVER command; can be overriden when the command is executed.

Points to consider:

  • Any setting with the initial prefix is effective on the first startup of the DBMS and/or when a new server joins the cluster and has to be explicitly ENABLED.

  • 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.

Configure a cluster with three servers hosting databases 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.

Besides, in the example below, the dbms.cluster.minimum_initial_system_primaries_count setting is not configured, as it defaults to three, and a cluster of three servers is being deployed. However, in case of setting up a cluster with only two servers, the setting dbms.cluster.minimum_initial_system_primaries_count must be set to 2 on all servers.

  1. Prepare neo4j.conf files on each server.

    neo4j.conf on server01.example.com:
    server.default_listen_address=0.0.0.0
server.default_advertised_address=server01.example.com
dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
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.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
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.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
initial.dbms.default_primaries_count=3

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

  2. 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"] |
+-----------------------------------------------------------------------------------------------------------+

    Note that initialized servers are ENABLED automatically at the first DBMS startup.

    Their values are taken from the initial settings.

    If you need to change the server’s options, use the ALTER SERVER command.

  3. 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.

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 1. 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 2. 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.