Neo4j High Availability Bolt Javascript Driver

Neo4j cluster session and transparent failover

About

This driver is a wrapper over the official Neo4j bolt driver and adds a layer of High Availability and transparent failovers

How to install

npm i --save neo4j-ha-bolt-driver

Quick example

const servers = [
    ['http://127.0.0.1:7474', 'bolt://127.0.0.1:7687'],
    ['http://127.0.0.1:7475', 'bolt://127.0.0.1:7688']
];

const auth = { user: 'neo4j', pass: 'password' };
const strategy = Neo4jHA.HAStrategies.roundRobin;
const rwConfig = Neo4jHA.HAReadWrite.masterReadWriteSlaveRead;
const checkInterval = 500;

console.log('connecting...');
const driver = new Neo4jHA(servers, { auth, strategy, rwConfig, checkInterval }, () => {
    console.log('ready');
    let session;
  
    // we get a session and we tell the driver that we will berform at least one write
    // the strategy is Round Robin but because we want to write 
    // and the read/write config is set to masterReadWriteSlaveRead (only master can write) 
    // this means that it will get a session to the master 
    session = driver.session(true);
    
    // don't forget to close sessions when you're done with them
    session.close();
    
    // now we request a read-only  session, so all servers are eligible for conenctions
    // the first server in the list is chosen
    session = driver.session(false);
    session.close();
    
    // requesting another read-only session will choose the second server
    // because of the Round Robin 
    session = driver.session();
    session.close();
}

// when you are done with the driver, just close it
driver.close();

Enums

HAStrategies

• random: It will pick a random server from the pool
• roundRobin: It will round robin through the server pool
• nearest: It will pick the server with the lowest latency

HAReadWrite

• masterOnly: Master will be the only queried server
• masterWriteOnlySlaveReadOnly: Master is write-only and slaves are read-only
• masterReadWriteSlaveRead: Master is read-write and slaves are read-only
• all: All servers are read-write
• Custom HAReadWrite Structure

{
        master: { read: Boolean, write: Boolean },
        slave: { read: Boolean, write: Boolean }
}

Status

• error (-2): Server is returning an error in the HA check
• unknown (-1): Server is in an unknown state
• down ( 0): Server is unreachable
• up ( 1): Server is in the cluster

ServerType

• unknown ( 0): Server is in an unknown state
• slave ( 1): Server is a slave
• master ( 2): server is master

Instantiating a driver

const driver = new Neo4jHA(serverList, options, readyCallback);

Where:

• serverList: is an array of
  • [HTTP URL, BOLT URL]
  • {bolt: Bolt URL, url: HTTP URL, auth: {user, pass}}
• options:
  • auth: {user, pass} - for all the connections
  • strategy: HAStrategies
  • rwConfig: HAReadWriteConfig
  • neo4jDriverOptions: options passed on the the raw neo4j bolt driver
  • checkInterval: interval to check servers availability
  • retryOnError: number of times to retry the query until the error is surfaced in callback
  • badConnectionsCountAsErrors: true if a server connection error is counted as an error
• readyCallback: callback when all servers status is known

Usage

const session = driver.session(writeLock[, rwConfig, strategy]);

Where:

• writeLock: Boolean - Tell the driver ifif there will ve any writes in the session
• rwConfig: custom HAReadWriteConfig for that session
• strategy: custom HAStrategies for that session

License

License can be found here