1.2 Driver documentation

About 1.2 driver documentation

This document aims to provide an introduction to how to use the 1.2 driver, as well as some additional information of how the driver internally is implemented. This document will NOT cover how to write Cypher or how to set up this driver in Azura or AWS.

This document is still under heavy construction and it is drafted by a terrible English writer. Have fun reading :)

Supported project version

.NET core and .NET framework 4.6+

Using driver with causal cluster

The main goal of 1.2 driver is to provide a improved user experience with Neo4j Causal Cluster. To achieve this goal, the 1.2 driver provides improved Causal Clustering API. The improved API which

• automates the passing of causal consistency context (bookmark) within Sessions
• hides failures that are caused by cluster leader switch by replay transactions using the strategy defined by retry logic.
• prevents Driver death when the database service is completely unavailable

When reading this section, we assume that you already have some basic knowledge of what is a Neo4j causal cluster, and what is Leader/Core/Read-replica member in a casual cluster.

Creating a driver

var driver = GraphDatabase.Driver( "bolt+routing://localhost:7687" );

A driver is thread-safe. It is recommended to use the driver in a singleton design pattern. The driver maintains a connection pool to the servers that are currently known to the driver. The pool manages connections that could be claimed by sessions and transactions on demands. There is no maximum limitation on how many connections that could be created by the connection pool. While there is a config setting Config. MaxIdleSessionPoolSize (Badly named, it should be MaxIdleConnectionPoolSize) that an application user could modify to decide how many connections with each server that could be buffered in the pool. Setting this config to 0 will turn off pooling of connections with all servers.

Initial Uri

"bolt+routing://localhost:7687"

When creating the driver, an initial Uri is provided to the driver. To create a driver (with build in load balancer) for a causal cluster, scheme bolt+routing should be chosen.

The initial Uri direct the driver to the first router in the cluster where the driver could inquire a routing table. A routing table is the current view of the cluster known to the inquired cluster server. After the routing table is obtained, a connection pool based on the routing table is created. The cluster server that could accept the inquiration are only the Core members (a.k.a. routers to the driver).

The routing table contains information of router, reader and writer servers inside the cluster. After the first routing table is obtained, the driver will start to use the newly returned routers to update routing tables in future.

While if the driver ever runs out of routers (the driver failed to contact any of the router in the routing table) due to some errors inside the cluster (such as restart of the cluster), the driver will fall back to contract the initial Uri server to inquire a new routing table.

Note: this driver currently dose NOT support Uri to IPs mapping, so if you give the driver bolt+routing://google.com, then only one connection pool under the name of google.com will be created no matter how many IPs behinds it :(

Creating a driver with customized config

var driver = GraphDatabase.Driver( "bolt+routing://localhost:7687", myAuthtoken, 
    new Config{EncryptionLevel= EncryptionLevel.None} );

Driver accepts a config where application users could add their own logging, change encryption level, server trust strategy, modify retry logic, modify the pool and so on. Read the API doc for Config class carefully for more information.

Disposing driver disposes all connections

driver.Dispose();

When disposing a driver, all connections (both idle connections in the connection pool and connections used by on going sessions and transactions) will be closed. After the driver disposed, no more connections could be created.

Creating a session

using(var session = driver.Session(defaultAccessMode, bookmark))
{
    session.Run(cypherStatement);
}

In 1.2 driver, session creation accept a defaultAccessMode. This access mode defines which server (Read server or Write server) that will be chosen in to execute the cypher statement in the session methods that do not specify a clear operation type (Read or Write), such as session.Run and session.BeginTransaction.

While the usage of the methods in session that clearly specify the operation type, are not restricted by the default access mode provided at the start of the session. For example, you could have the following code:

using(var session = driver.Session(AccessMode.Read))
{
    session.WriteTransaction((tx)=>tx.Run(cypherStatement));
}

Running cypher statement inside a transaction with build in retries

From 1.2, we introduced new methods ReadTransaction and WriteTransaction, which take an action or a function as input. The action and function expose a transaction tx that could be used to run cypher statements. When executing cypher statements inside the action or function, the statement will be retried using our build-in retry logic if certain specific recoverable errors happens (See more in RetryLogic).

Causal consistency within a session

Bookmark in a session

• bookmark is passed in at session creation.
• bookmark is passed on among transactions.
• failing tx will not change bookmark
• sesison.run will not change bookmark.

session.Run and session.BeginTransaction on Session

Using driver with a stand alone single instance