25.2. Setup and configuration

Neo4j HA can be set up to accommodate differing requirements for load, fault tolerance and available hardware.

In HA mode, Neo4j instances form a cluster. The instances monitor each others' availability to take account of instances joining and leaving the cluster. They elect one instance to be the master, and designate the other instances to be slaves.

For installation instructions of a High Availability cluster see Section 25.6, “High Availability setup tutorial”.

Specifying cluster members

Specify the instances that should form the cluster by supplying ha.initial_hosts, a comma-separated list of URLs. When each instance starts, if it can contact any of the initial hosts, then it will form a cluster with them, otherwise it will start its own cluster.

Note that the parameter is called ha.initial_hosts because it’s only used when instances initially join the cluster. This means that you can extend the cluster without changing the configuration of existing instances.

Server configuration

If you are running Neo4j server, specify org.neo4j.server.database.mode=HA in conf/neo4j-server.properties.

HA server configuration parameters

Parameter Name Description Example value Required?

org.neo4j.server.database.mode

Whether to run as a single server or in HA mode.

single or HA

yes

Database configuration

HA configuration parameters should be supplied alongside general Neo4j parameters in conf/neo4j.properties. There are many configurable parameters. In most cases it isn’t necessary to modify the default values. The only parameters that need to be specified are ha.server_id and ha.initial_hosts.

High Availability configuration settings

NameDescription

ha.branched_data_policy

Policy for how to handle branched data.

ha.com_chunk_size

Max size of the data chunks that flows between master and slaves in HA.

ha.lock_read_timeout

Timeout for taking remote (write) locks on slaves.

ha.max_concurrent_channels_per_slave

Maximum number of connections a slave can have to the master.

ha.pull_interval

Interval of pulling updates from master.

ha.read_timeout

How long a slave will wait for response from master before giving up.

ha.server

Hostname and port to bind the HA server.

ha.slave_only

Whether this instance should only participate as slave in cluster.

ha.state_switch_timeout

Timeout for waiting for instance to become master or slave.

ha.tx_push_factor

The amount of slaves the master will ask to replicate a committed transaction.

ha.tx_push_strategy

Push strategy of a transaction to a slave during commit.

ha.branched_data_policy

Description

Policy for how to handle branched data.

Valid values

ha.branched_data_policy is one of +<<config_keep_all,keep_all>>+, +<<config_keep_last,keep_last>>+, +<<config_keep_none,keep_none>>+.

Default value

keep_all

ha.com_chunk_size

Description

Max size of the data chunks that flows between master and slaves in HA. Bigger size may increase throughput, but may also be more sensitive to variations in bandwidth, whereas lower size increases tolerance for bandwidth variations.

Valid values

ha.com_chunk_size is a byte size (valid multipliers are k, m, g, K, M, G) which is minimum 1024.

Default value

2M

ha.lock_read_timeout

Description

Timeout for taking remote (write) locks on slaves. Defaults to ha.read_timeout.

Valid values

ha.lock_read_timeout is a duration (valid units are ms, s, m).

Default value

20s

ha.max_concurrent_channels_per_slave

Description

Maximum number of connections a slave can have to the master.

Valid values

ha.max_concurrent_channels_per_slave is an integer which is minimum 1.

Default value

20

ha.pull_interval

Description

Interval of pulling updates from master.

Valid values

ha.pull_interval is a duration (valid units are ms, s, m).

Default value

0s

ha.read_timeout

Description

How long a slave will wait for response from master before giving up.

Valid values

ha.read_timeout is a duration (valid units are ms, s, m).

Default value

20s

ha.server

Description

Hostname and port to bind the HA server.

Valid values

ha.server is a hostname and port.

Default value

0.0.0.0:6001-6011

ha.slave_only

Description

Whether this instance should only participate as slave in cluster. If set to true, it will never be elected as master.

Valid values

ha.slave_only is a boolean.

Default value

false

ha.state_switch_timeout

Description

Timeout for waiting for instance to become master or slave.

Valid values

ha.state_switch_timeout is a duration (valid units are ms, s, m).

Default value

120s

ha.tx_push_factor

Description

The amount of slaves the master will ask to replicate a committed transaction.

Valid values

ha.tx_push_factor is an integer which is minimum 0.

Default value

1

ha.tx_push_strategy

Description

Push strategy of a transaction to a slave during commit.

Valid values

ha.tx_push_strategy is one of +<<config_round_robin,round_robin>>+, fixed.

Default value

fixed

Cluster configuration settings

NameDescription

ha.allow_init_cluster

Whether to allow this instance to create a cluster if unable to join.

ha.broadcast_timeout

Timeout for broadcasting values in cluster.

ha.cluster_name

The name of a cluster.

ha.cluster_server

Host and port to bind the cluster management communication.

ha.configuration_timeout

Timeout for waiting for configuration from an existing cluster member during cluster join.

ha.default_timeout

Default timeout used for clustering timeouts.

ha.election_timeout

Timeout for waiting for other members to finish a role election.

ha.heartbeat_interval

How often heartbeat messages should be sent.

ha.heartbeat_timeout

Timeout for heartbeats between cluster members.

ha.initial_hosts

A comma-separated list of other members of the cluster to join.

ha.join_timeout

Timeout for joining a cluster.

ha.learn_timeout

Timeout for learning values.

ha.leave_timeout

Timeout for waiting for cluster leave to finish.

ha.paxos_timeout

Default timeout for all Paxos timeouts.

ha.phase1_timeout

Timeout for Paxos phase 1.

ha.phase2_timeout

Timeout for Paxos phase 2.

ha.server_id

Id for a cluster instance.

ha.allow_init_cluster

Description

Whether to allow this instance to create a cluster if unable to join.

Valid values

ha.allow_init_cluster is a boolean.

Default value

true

ha.broadcast_timeout

Description

Timeout for broadcasting values in cluster. Must consider end-to-end duration of Paxos algorithm. This value is the default value for the ha.join_timeout and ha.leave_timeout settings.

Valid values

ha.broadcast_timeout is a duration (valid units are ms, s, m).

Default value

30s

ha.cluster_name

Description

The name of a cluster.

Valid values

ha.cluster_name is a string which must be a valid cluster name.

Default value

neo4j.ha

ha.cluster_server

Description

Host and port to bind the cluster management communication.

Valid values

ha.cluster_server is a hostname and port.

Default value

0.0.0.0:5001-5099

ha.configuration_timeout

Description

Timeout for waiting for configuration from an existing cluster member during cluster join.

Valid values

ha.configuration_timeout is a duration (valid units are ms, s, m).

Default value

1s

ha.default_timeout

Description

Default timeout used for clustering timeouts. Override specific timeout settings with proper values if necessary. This value is the default value for the ha.heartbeat_interval, ha.paxos_timeout and ha.learn_timeout settings.

Valid values

ha.default_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.election_timeout

Description

Timeout for waiting for other members to finish a role election. Defaults to ha.paxos_timeout.

Valid values

ha.election_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.heartbeat_interval

Description

How often heartbeat messages should be sent. Defaults to ha.default_timeout.

Valid values

ha.heartbeat_interval is a duration (valid units are ms, s, m).

Default value

5s

ha.heartbeat_timeout

Description

Timeout for heartbeats between cluster members. Should be at least twice that of ha.heartbeat_interval.

Valid values

ha.heartbeat_timeout is a duration (valid units are ms, s, m).

Default value

11s

ha.initial_hosts

Description

A comma-separated list of other members of the cluster to join.

Valid values

ha.initial_hosts is a list separated by "," where items are a hostname and port.

Mandatory

The ha.initial_hosts configuration setting is mandatory.

ha.join_timeout

Description

Timeout for joining a cluster. Defaults to ha.broadcast_timeout.

Valid values

ha.join_timeout is a duration (valid units are ms, s, m).

Default value

30s

ha.learn_timeout

Description

Timeout for learning values. Defaults to ha.default_timeout.

Valid values

ha.learn_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.leave_timeout

Description

Timeout for waiting for cluster leave to finish. Defaults to ha.broadcast_timeout.

Valid values

ha.leave_timeout is a duration (valid units are ms, s, m).

Default value

30s

ha.paxos_timeout

Description

Default timeout for all Paxos timeouts. Defaults to ha.default_timeout. This value is the default value for the ha.phase1_timeout, ha.phase2_timeout and ha.election_timeout settings.

Valid values

ha.paxos_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.phase1_timeout

Description

Timeout for Paxos phase 1. Defaults to ha.paxos_timeout.

Valid values

ha.phase1_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.phase2_timeout

Description

Timeout for Paxos phase 2. Defaults to ha.paxos_timeout.

Valid values

ha.phase2_timeout is a duration (valid units are ms, s, m).

Default value

5s

ha.server_id

Description

Id for a cluster instance. Must be unique within the cluster.

Valid values

ha.server_id is an instance id, which has to be a valid integer.

Mandatory

The ha.server_id configuration setting is mandatory.