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 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 for a causal cluster, scheme bolt+routing should be chosen.

The initial Uri directs the driver to a server in the cluster where the driver could inquire a routing table. A routing table carries the information of the inquired server's understanding of the current cluster structure and the addresses to find them. Based on the routing table returned, a connection pool for pooling connections to the cluster is then created. Note: The cluster server that could accept the inquiration of routing table are only the Core members (a.k.a. routers).

The routing table contains information of routers (where a routing table could be inquired), readers (where read statements could be executed) and writers (where write statements could be executed) inside the cluster. After the first routing table is received, the driver will use the newly returned routers to update routing tables afterwards.

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 for a new routing table.

Note: this driver currently dose NOT support resolving DNS to IP addresses.

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, modify retry logic, reconfigure the pool and so on. Read the API doc for Config class 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 (readers or writers) 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