Conventions: Load Balance & Failover

  • The ReadBalanceBehavior convention gets or sets the default load-balancing behavior of Read requests from the client to RavenDB cluster.

    The selected method determines which node the client's RequestExecutor would send Read requests to, and which node to failover to in case of issues with the Read request.

  • Write requests are sent to the Preferred Node calculated by the client.

  • The LoadBalanceBehavior convention can determine that the topology would be specified by a client session.

  • In this page:

ReadBalanceBehavior Options

  • None

    • Load-balance
      No load balancing will occur. The client will always select the preferred node.
    • Failover
      The client will failover nodes in the order they appear in the topology nodes list.

      The list can be reordered, see Database Group Actions.

  • RoundRobin

    • Load-balance
      For each Read request, the client will address the next node from the topology nodes list.
    • Failover
      In case of a failure, the client will try the next node in the round robin order.
  • FastestNode

    • Load-balance: Read request will go to the fastest node.
      The fastest node is determined by a Speed Test.
    • Failover
      In case of a failure, a speed test will be triggered again and in the meantime the client will use the preferred node.


Conventions = new DocumentConventions
    ReadBalanceBehavior = ReadBalanceBehavior.FastestNode


The nodes topology used to handle client requests can be selected per-session, using the LoadBalanceBehavior convention.

Conventions = new DocumentConventions
    LoadBalanceBehavior = LoadBalanceBehavior.UseSessionContext

Preferred Node

  • The preferred node is selected by simply going over the topology nodes list and returning the first node that has not had any errors.

  • If all nodes are in a failure state then the first node in the list is returned. The user would get an error or recover if the error was transient.

Session Usage

  • When using RoundRobin or FastestNode it might happen that the next session you open will access a different node.

  • A short delay in replicating changes to all nodes in the cluster is acceptable in most cases.
    If you need to ensure that the next request will be able to immediately read what you just wrote, you need to use Write Assurance.