In Neo4j 5.x, causal cluster behavior, and configuration significantly differ from previous Neo4j versions. Core and read replicas are replaced with Primary and Secondary servers respectively.  

This article provides an example of a single primary single secondary cluster in Neo4j 5.x. In previous versions of Neo4j, this would be a core and read replica cluster.

This setup is useful when Graph Data Science GDS is installed. GDS can be installed only on a secondary server. So, this setup can be used for hybrid workloads, both transactional and analytical.

Explaining the Configuration

The primary server's neo4j.conf file specifies the following settings:

server.cluster.system_database_mode set to PRIMARY on the primary server and SECONDARY on the secondary server. 

This enforces a primary and secondary system database. 

initial.server.mode_constraint set to PRIMARY on the primary server and SECONDARY on the secondary server. 

This enforces the type of allocated user database on the server for example, PRIMARY databases will only be hosted on primary servers and SECONDARY databases will only be hosted on secondary servers. 

initial.dbms.default_secondaries_count set to 1.

This ensures that any database created using CREATE DATABASE has one primary and one secondary. This can be omitted if required but when creating a new database the TOPOLOGY must be set to 1 PRIMARY 1 SECONDARY. 

dbms.cluster.minimum_initial_system_primaries_count set to 1. 

This allows a cluster to form with only one primary system database. The default value is 3; as this is a one-primary, one-secondary cluster, there will never be three primary system databases online. 

initial.dbms.automatically_enable_free_servers set to true. 

This ensures that the secondary server is enabled. This can be omitted if required but the secondary server will need to be enabled once both servers are online. 

dbms.cluster.discovery.version set to V2_ONLY.

This enforces V2 discovery, which should be enabled on all new clusters. This is optional. 

Example Configuration

Primary Server (neo4j.conf)

server.cluster.system_database_mode=PRIMARY
initial.server.mode_constraint=PRIMARY
initial.dbms.default_secondaries_count=1   
dbms.cluster.minimum_initial_system_primaries_count=1
initial.dbms.automatically_enable_free_servers=true
## V2 discovery settings
## This assumes the servers are call primary-server and secondary-server
dbms.cluster.discovery.version=V2_ONLY
dbms.cluster.discovery.v2.endpoints=primary-server:6000,secondary-server:6000

In the Secondary server (neo4j.conf):

server.cluster.system_database_mode=SECONDARY
initial.server.mode_constraint=SECONDARY
initial.dbms.default_secondaries_count=1   
dbms.cluster.minimum_initial_system_primaries_count=1
initial.dbms.automatically_enable_free_servers=true
## V2 discovery settings
## This assumes the servers are call primary-server and secondary-server
dbms.cluster.discovery.version=V2_ONLY
dbms.cluster.discovery.v2.endpoints=primary-server:6000,secondary-server:6000

Once the two servers are started, show servers will have the following output

neo4j@neo4j> show servers;
+---------------------------------------------------------------------------------------------------------+
| name                                   | address        | state     | health      | hosting             |
+---------------------------------------------------------------------------------------------------------+
| "49c6e3a7-ed1a-41ee-83e9-407f5d718bbd" | "server2:7687" | "Enabled" | "Available" | ["system"]          |
| "510c6966-60aa-4dec-9d2c-0e995ef9c298" | "server1:7687" | "Enabled" | "Available" | ["neo4j", "system"] |
+---------------------------------------------------------------------------------------------------------+

We can then alter the topology of the neo4j to add a secondary allocation, the below shows the ALTER, SHOW SERVERS, and SHOW DATABASE commands

neo4j@neo4j> alter database neo4j set topology 1 primary 1 secondary;
0 rows
ready to start consuming query after 803 ms, results consumed after another 0 ms
neo4j@neo4j> show servers;
+---------------------------------------------------------------------------------------------------------+
| name                                   | address        | state     | health      | hosting             |
+---------------------------------------------------------------------------------------------------------+
| "60b44407-c24c-47d1-9b36-ff92a3eee0b0" | "server1:7687" | "Enabled" | "Available" | ["neo4j", "system"] |
| "8df0cd89-cf8b-4331-83a3-18fcd1c8af0c" | "server2:7687" | "Enabled" | "Available" | ["neo4j", "system"] |
+---------------------------------------------------------------------------------------------------------+

2 rows
neo4j@neo4j> show database neo4j;
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name    | type       | aliases | access       | address        | role        | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "neo4j" | "standard" | []      | "read-write" | "server1:7687" | "primary"   | TRUE   | "online"        | "online"      | ""            | TRUE    | TRUE | []           |
| "neo4j" | "standard" | []      | "read-write" | "server2:7687" | "secondary" | FALSE  | "online"        | "online"      | ""            | TRUE    | TRUE | []           |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

2 rows
ready to start consuming query after 24 ms, results consumed after another 12 ms

When creating a new database, this will have one primary and one secondary as defined in the configuration of initial.dbms.default_secondaries_count

neo4j@neo4j> create database test;
0 rows
ready to start consuming query after 346 ms, results consumed after another 0 ms
neo4j@neo4j> show database test;
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name   | type       | aliases | access       | address        | role        | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "test" | "standard" | []      | "read-write" | "server2:7687" | "secondary" | FALSE  | "online"        | "online"      | ""            | FALSE   | FALSE | []           |
| "test" | "standard" | []      | "read-write" | "server1:7687" | "primary"   | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []           |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

2 rows
ready to start consuming query after 33 ms, results consumed after another 7 ms