Knowledge Base

A demonstration of causal cluster routing

The following will demonstrate how to use cypher-shell to get a better understanding of a Neo4j Causal Cluster instance and its implementation of routing.

The initial scenario is described with local cluster setup with 3 core instances, 1 LEADER and 2 FOLLOWERS. Using dbms.cluster.overview() The output reports

$ ./cypher-shell -a bolt://192.168.0.97:7617
Connected to Neo4j 3.2.2 at bolt://192.168.0.97:7617.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j> call dbms.cluster.overview() yield addresses, role;
+-----------------------------------------------------------------------------------------------+
| addresses                                                                    | role           |
+-----------------------------------------------------------------------------------------------+
| ["bolt://localhost:7617", "http://localhost:7414", "https://localhost:7413"] | "LEADER"       |
| ["bolt://localhost:7627", "http://localhost:7424", "https://localhost:7423"] | "FOLLOWER"     |
| ["bolt://localhost:7637", "http://localhost:7434", "https://localhost:7433"] | "FOLLOWER"     |
+-----------------------------------------------------------------------------------------------+

The above detail is also available through the browser by running :sysinfo

if a connection is made to the 3rd instance (i.e. a FOLLOWER) and the routing attribute is not included, then writes are not possible on the FOLLOWER and this is expected, for example

$ ./cypher-shell -a bolt://192.168.0.97:7637
Connected to Neo4j 3.2.2 at bolt://192.168.0.97:7637.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j> create (m:Person {id:123});
No write operations are allowed directly on this database. Writes must pass through the leader. The role of this server is: FOLLOWER
neo4j> :exit

however if a connection is made to this same FOLLOWER instance and the bolt+routing attribute is included, then Writes are possible, for example

$ ./cypher-shell -a bolt+routing://192.168.0.97:7637
Connected to Neo4j 3.2.2 at bolt://192.168.0.97:7637.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j> create (m:Person {id:123});
0 rows available after 791 ms, consumed after another 3 ms
neo4j> :exit

in this case although cypher-shell was initiated and described to connect to the FOLLOWER on port :7637, as a result of the bolt+routing, the connection was actually redirected to the LEADER, for example

$ ./cypher-shell -a bolt+routing://192.168.0.97:7637
Connected to Neo4j 3.2.2 at bolt+routing://192.168.0.97:7637.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j> call dbms.cluster.role();
+----------+
| role     |
+----------+
| "LEADER" |
+----------+

Finally, if the LEADER fails after the intial cypher-shell connection has been established, and thus re-eleection has resulted in the FOLLOWER from instance 3 being reported as the new LEADER, as evidence

neo4j> call dbms.cluster.overview();
+-------------------------------------------------------------------------------------------------------------------------------------------------+
| id                                     | addresses                                                                    | role           | groups |
+-------------------------------------------------------------------------------------------------------------------------------------------------+
| "0ec70285-5f4a-4a4a-97ce-916592525944" | ["bolt://localhost:7627", "http://localhost:7424", "https://localhost:7423"] | "FOLLOWER"     | []     |
| "06c1399d-ec17-4cf5-a31e-fb0db135f543" | ["bolt://localhost:7637", "http://localhost:7434", "https://localhost:7433"] | "LEADER"       | []     |
+-------------------------------------------------------------------------------------------------------------------------------------------------+

the cypher-shell connection is able to continue, for example

neo4j> create (n:Person {id:456});
0 rows available after 133 ms, consumed after another 1 ms
Added 1 nodes, Set 1 properties, Added 1 labels

In this case the cypher-shell client has been updated with a new routing table and thus sends WRITEs to the NEW leader at :7637.

If connection had not been established with `bolt+routing' then the connection would have gone to the instance defined by its :port and if that Neo4j instance exits, then future submissions via cypher-shell will results in:

SSL Connection terminated while receiving data. This can happen due to network instabilities, or due to restarts of the database.