ArangoDB Java Driver: Load Balancing for Performance

The newest release 4.3.2 of the official ArangoDB Java driver comes with load balancing for cluster setups and advanced fallback mechanics.

Load balancing strategies

Round robin

There are two different strategies for load balancing that the Java driver provides. The first and most common strategy is the round robin way. Round robin does, what the name already assumes, a round robin load balancing where a list of known coordinators in the cluster is iterated through. Each database operation uses a different coordinator than the one before.

Most of the database operations can be handled by this simple logic. But for AQL queries we need something smarter. We have to stick to a specific coordinator when performing AQL queries where its result is not fully returned in a single response. In this case, ArangoDB creates state in form of a local cursor on the coordinator, the initial query was sent to. Every following request to get more batches of the result has to go to the same coordinator. Different to most simple standalone load balancer the driver is able to take care of that.

ArangoDB arango = new ArangoDB.Builder()
    .host("coordinator-url-1", 8529)
    .host("coordinator-url-2", 8529)
    .host("coordinator-url-3", 8529)
    .loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
    .maxConnections(3)
    .build();

Note: Per default, the driver uses one connection. To make round robin load balancing work properly you need at least as many connections as the number of coordinators in your cluster.

Random

Another way of load balancing offered with the new driver version is – random, meaning picking one random coordinator from a configured list of known coordinators and sticking to that coordinator as long as the driver instance exists. By itself this does not sound like load balancing. But if you take another look at it, it gives you an opportunity to create an application with a sessions management where you can stick one session to one coordinator as long as the session is alive. So instead of assigning one coordinator to every new session, you can work with a globally configured list of all known coordinators; and every new driver instance picks a random coordinator from that global list. In the end you get a better load balancing over all your sessions.

An example in the multi-threaded environment.
Because ArangoDB.Builder is thread-safe, you can use it as your global configuration

ArangoDB.Builder arangoBuilder = new ArangoDB.Builder()
    .host("coordinator-url-1", 8529)
    .host("coordinator-url-2", 8529)
    .host("coordinator-url-3", 8529)
    .loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM); 

and share it between your threads. These threads create their own instance of the driver’s main access point – ArangoDB, and perform database operations on that.

ArangoDB arango = arangoBuilder.build();

Know your coordinators

As I already pointed out, load balancing requires to know which coordinators are part of your cluster. But that is only half true – the driver has to know, but you only have to specify one coordinator it has to connect to. There is another neat feature – the driver can acquire a list of all known coordinators in the cluster by itself. The list will be then updated regularly. In case an additional coordinator gets added to your cluster or vice versa the driver will recognize it automatically.

For you, it is simply as easy as it sounds and it works together with both load balancing strategies.

ArangoDB arango = new ArangoDB.Builder()
    .host("coordinator-url-1", 8529)
    .loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
    .maxConnections(3)
    .acquireHostList(true)
    .build();

Fallback

Ok, the fallback feature is not really new. ArangoDB Java driver already supported fallback – in case one coordinator is not reachable, it simply picks another known coordinator. The new part is that it also works with the new mechanic of acquiring the known coordinators in the cluster. In addition, the fallback for hosts not only works for coordinators in a cluster setup but also for ArangoDBs new feature “active-passive single server” which is introduced with ArangoDB 3.3 Beta Release.