You are currently browsing legacy 5.3 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    See on GitHub

    Load balancing client requests - Overview

    • A database can have multiple instances, each one residing on a different cluster node.
      Each instance is a complete replica of the database.

    • The database-group-topology is the list of nodes that contain those database replicas.
      The first node in this list is called the preferred node.

    • The client is kept up-to-date with this topology list.
      The client decides which node from this list to access when making requests to the RavenDB cluster.

    • By default, the client will access the preferred node for all Read & Write requests it makes.
      This default behavior can be changed by configuring:

    Keeping the client topology up-to-date

    • Upon Document Store initialization, the client receives the initial topology list,
      after which the client is kept updated at all times for any changes made to it.

    • If the topology list has changed on the server, (or any other client configuration),
      the client will learn about it upon making its next request to the server,
      and will update its configuration accordingly.

    • In addition, every 5 minutes, the client will fetch the current topology from the server
      if no requests were made within that time frame.

    • Any client-configuration settings that are set on the server side override the settings made on the client-side.

    • For more information see Topology in the client.

    Client logic for choosing a node

    The client uses the following logic (from top to bottom) to determine which node to send the request to:

    • Else, if using-session-context is defined, use LoadBalanceBehavior:
      Per session, the client will select a node based on the session context.
      All Read & Write requests made on the session will be directed to that node.
    • Else, if defined, use ReadBalanceBehavior:
      Read requests: The client will select a node based on the read balance options.
      Write requests: All Write requests will be directed to the preferred node.
    • Else, use the preferred node:
      Use the preferred node for both Read & Write requests.

    The preferred node

    • The preferred node is simply the first node in the topology nodes list.
    • By default, when no load balancing strategy is defined,
      the client will send all Read & Write requests to this node.
    • When the preferred node is in a failure state,
      the cluster will update the topology, assigning another node to be the preferred one.
    • Once the preferred node is back up and has caught up with all data,
      it will be placed last in the topology list.
    • If all the nodes in the topology list are in a failure state then the first node in the list will be the 'preferred'.
      The user would get an error, or recover if the error was transient.
    • The preferred node can be explicitly set by:
    • The cluster may assign a different preferred node when removing/adding new nodes to the database-group.

    Single-node session usage

    • When using a single-node session,
      a short delay in replicating changes to all nodes in the cluster is acceptable in most cases.

    • If ReadBalanceBehavior or LoadBalanceBehavior are defined,
      then the next session you open may access a different node.
      So if you need to ensure that the next request will be able to immediately read what you just wrote,
      then use Write Assurance.

    related articlesRelated Articles

    Operations

    Configuration

    Client Configuration in Studio

    Home / Docs / Client Api / Configuration / Load Balance / Overview