{
  "schema_version": 2,
  "id": "develop/clients/failover",
  "title": "Client-side geographic failover",
  "url": "https://redis.io/docs/latest/develop/clients/failover/",
  "summary": "Improve reliability using the failover/failback features of client libraries.",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-09-29T16:29:37+01:00",
  "page_type": "content",
  "content_hash": "5df9685d826ae60d17c235d8380b4acf25310a837db920e0f1d5c65c5a662613",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Some Redis client libraries support\n[Client-side geographic failover](https://en.wikipedia.org/wiki/Failover)\nto improve the availability of connections to Redis databases. Use this page\nto get a general overview of the concepts and then see the documentation for\nyour client library to learn how to configure it for failover and failback."
    },
    {
      "id": "supported-client-libraries",
      "title": "Supported client libraries",
      "role": "compatibility",
      "text": "The table below lists the clients that support client-side geographic failover\nalong with their release state and available features.\n\n| Client | Basic failover | Pub/sub failover | OSS Cluster failover | Failback |\n| :-- | :-- | :-- | :-- | :-- |\n| [Jedis](https://redis.io/docs/latest/develop/clients/jedis/failover) | Yes | No | No | Yes |\n| [redis-py](https://redis.io/docs/latest/develop/clients/redis-py/failover) | Yes  (Preview) | Yes | Yes | Yes |\n| [Lettuce](https://redis.io/docs/latest/develop/clients/lettuce/failover) | Yes (Preview) | Yes | No | Yes |\n| [StackExchange.Redis](https://redis.io/docs/latest/develop/clients/dotnet/failover) | Yes | Yes | Yes | Yes |"
    },
    {
      "id": "concepts",
      "title": "Concepts",
      "role": "content",
      "text": "You may have several [Active-Active databases](https://redis.io/docs/latest/operate/rs/databases/active-active)\nor independent Redis servers that are all suitable to serve your app.\nTypically, you would prefer to use some database endpoints over others for a particular\ninstance of your app (perhaps the ones that are closest geographically to the app server\nto reduce network latency). However, if the best endpoint is not available due\nto a failure, it is generally better to switch to another, suboptimal endpoint\nthan to let the app fail completely.\n\n*Failover* is the technique of actively checking for connection failures or\nunacceptably slow connections and automatically switching to the best available endpoint \nwhen they occur. This requires you to specify a list of endpoints to try, ordered by priority. The diagram below shows this process:\n\n![Failover and client reconnection](https://redis.io/docs/latest/images/failover/failover-client-reconnect.svg)\n\nThe complementary technique of *failback* then involves periodically checking the health\nof all endpoints that have failed. If any endpoints recover, the failback mechanism\nautomatically switches the connection to the one with the highest priority. \nThis could potentially be repeated until the optimal endpoint is available again.\n\n![Failback: client switches back to original server](https://redis.io/docs/latest/images/failover/failover-client-failback.svg)"
    },
    {
      "id": "detecting-connection-problems",
      "title": "Detecting connection problems",
      "role": "content",
      "text": "Redis clients use a [circuit breaker design pattern](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) to detect connection problems.\n\nThe circuit breaker is a software component that tracks the sequence of recent\nRedis connection attempts and commands, recording which ones have succeeded and\nwhich have failed.\n(Note that many command failures are caused by transient errors such as timeouts,\nso before recording a failure, the first response should usually be just to retry\nthe command a few times.)\n\nThe status of the attempted command calls is kept in a \"sliding window\", which\nis simply a buffer where the least recent item is dropped as each new\none is added. The buffer can be configured to have a fixed number of failures and/or a failure ratio (specified as a percentage), both based on a time window.\n\n![Sliding window of recent connection attempts](https://redis.io/docs/latest/images/failover/failover-sliding-window.svg)\n\nWhen the number of failures in the window exceeds a configured\nthreshold, the circuit breaker declares the server to be unhealthy and triggers\na failover."
    },
    {
      "id": "selecting-a-failover-target",
      "title": "Selecting a failover target",
      "role": "content",
      "text": "Since you may have multiple Redis servers available to fail over to, the client\nlets you configure a list of endpoints to try, ordered by priority or\n\"weight\". When a failover is triggered, the client selects the highest-weighted\nendpoint that is still healthy and uses it for the temporary connection."
    },
    {
      "id": "health-checks",
      "title": "Health checks",
      "role": "content",
      "text": "Given that the original endpoint had some geographical or other advantage\nover the failover target, you will generally want to fail back to it as soon\nas it recovers. In the meantime, another server might recover that is\nstill better than the current failover target, so it might be worth\nfailing back to that server even if it is not optimal.\n\nClients periodically run a \"health check\" on each server to see if it has recovered.\nSeveral health check strategies are implemented in all clients:\n\n-   **Ping**: This is the default strategy, which just sends a\n    [`PING`](https://redis.io/docs/latest/commands/ping) command and ensures that it gives the\n    expected response.\n-   **Lag aware** (Redis Software only): This strategy uses the\n    [REST API](https://redis.io/docs/latest/operate/rs/references/rest-api) to check the\n    synchronization lag between a specific database and the others in the Active-Active\n    setup. If the lag is within a specified tolerance, the server is considered healthy.\n-   **Custom**: You can implement your own health check strategy to use information\n    or take action that is specific to your application.\n\nSee the documentation for your client library for more information on how to\nconfigure health checks.\n\nYou can also configure the client to run health checks on the current target\nserver during periods of inactivity, even if no failover has occurred. This can\nhelp to detect problems even if your app is not actively using the server."
    }
  ],
  "examples": []
}