4.2.12. Causal Clustering settings reference

This section lists the important settings related to running a Neo4j Causal Cluster. Common settings

Parameter name Description Example


This setting configures the operating mode of the database. For Causal Clustering, there are two possible modes: CORE or READ_REPLICA.

dbms.mode=READ_REPLICA will define this server as a Read Replica`.


A hint to the cluster at startup for the intended cluster size. This is necessary for achieving quorum writes to the cluster. This value is the number of instances you intend to have as part of your cluster. The minimum number of instances to form a fault-tolerant cluster is three.

causal_clustering.expected_core_cluster_size=3 will specify that the cluster has three core members.


Machines running Neo4j communicate over the network to ensure consistency of the database between themselves. A common scenario is to deploy Neo4j on many machines. In this case each member of the cluster must be given bootstrap information about the other members that are likely in the cluster. Specifying an instance’s own address is permitted. Do not use any whitespace in this configuration option.

causal_clustering.initial_discovery_members=neo22:5001,neo21:5001,neo20:5001 will attempt to reach Neo4j instances listening on neo22 on port 5001 and neo21 on port 5001 and neo20 also on port 5001.


The address/port setting that specifies where the Neo4j instance advertises to other members of the cluster that it will listen for Raft messages within the Core cluster.

causal_clustering.raft_advertised_address= will listen for for cluster communication in the network interface bound to on port 7000.


The address/port setting that specifies where the instance advertises where it will listen for requests for transactions in the transaction-shipping catchup protocol.

causal_clustering.transaction_advertised_address= will listen for transactions from cluster members on the network interface bound to on port 6001.


The address/port setting for use by the discovery protocol. This is the setting which will be included in the setting causal_clustering.initial_discovery_members which are set in the configuration of the other members of the cluster.

causal_clustering.discovery_listen_address= will listen for cluster membership communication on any network interface at port 5001.


The address/port setting that specifies which network interface and port the Neo4j instance will bind to for cluster communication. This setting must be set in coordination with the address this instance advertises it will listen at in the setting causal_clustering.raft_advertised_address.

causal_clustering.raft_listen_address= will listen for cluster communication on any network interface at port 7000.


The address/port setting that specifies which network interface and port the Neo4j instance will bind to for cluster communication. This setting must be set in coordination with the address this instance advertises it will listen at in the setting causal_clustering.transaction_advertised_address.

causal_clustering.transaction_listen_address= will listen for cluster communication on any network interface at port 7000.


Prevents the current instance from volunteering to become Raft leader if set to true. Defaults to false, and should only be used in exceptional circumstances by expert users, or when advised by Neo4j Professional Services.



Defaults to true so that followers are available for read-only queries in a typical heterogeneous setup. Note: if there are no read replicas in the cluster, followers are made available for read, regardless the value of this setting.

causal_clustering.cluster_allow_reads_on_followers=true Multi-data center settings

Parameter name Description Example


Enables multi-data center features. Requires appropriate licensing.

causal_clustering.multi_dc_license=true will enable the multi-data center features.


A list of group names for the server used when configuring load balancing and replication policies.

causal_clustering.server_groups=us,us-east will add the current instance to the groups us and us-east.


An ordered list in descending preference of the strategy which read replicas use to choose upstream database server from which to pull transactional updates.

causal_clustering.upstream_selection_strategy=connect-randomly-within-server-group,typically-connect-to-random-read-replica will configure the behavior so that the Read Replica will first try to connect to any other instance in the group(s) specified in causal_clustering.server_groups. Should we fail to find any live instances in those groups, then we will connect to a random Read Replica. A value of user_defined will enable custom strategy definitions using the setting causal_clustering.user_defined_upstream_strategy.


Defines the configuration of upstream dependencies. Can only be used if causal_clustering.upstream_selection_strategy is set to user_defined.

causal_clustering.user_defined_upstream_strategy=groups(north2); groups(north); halt() will look for servers in the north2. If none are available it will look in the north server group. Finally, if we cannot resolve any servers in any of the previous groups, then rule chain will be stopped via halt().


The load balancing plugin to use. One pre-defined plugin named server_policies is available by default.

causal_clustering.load_balancing.plugin=server_policies will enable custom policy definitions.


Defines a custom policy under the name <policy-name>. Note that load balancing policies are cluster-global configurations and should be defined the exact same way on all core machines.

causal_clustering.load_balancing.config.server_policies.north1_only=groups(north1)→min(2); halt(); will define a load balancing policy named north1_only. Queries are only sent to servers in the north1 server group, provided there are two of them available. If there aren’t least two servers in north1 then the chain is halted.