{
  "schema_version": 2,
  "id": "develop/clients/sch",
  "title": "Smart client handoffs",
  "url": "https://redis.io/docs/latest/develop/clients/sch/",
  "summary": "Learn how to avoid disruptions during Redis server maintenance.",
  "aliases": [
    "/develop/clients/sce/"
  ],
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-10-13T14:53:04+01:00",
  "page_type": "content",
  "content_hash": "4c45ae2f2550b9d57f530c78fa395afac0fa97990e3d8f08313a5d1823adee3f",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "*Smart client handoffs (SCH)* is a feature of Redis Cloud and\nRedis Software servers that lets them actively notify clients\nabout planned server maintenance shortly before it happens. This\nlets a client reconnect or otherwise respond gracefully without significant\ninterruptions in service.\n\nSCH is primarily useful when server software or hardware upgrades\nare required. It provides two main features to help the\nclient avoid disruptions in service during the maintenance period:\n\n-   **Relaxed timeouts**: Upgrades tend to impact the general performance of the server.\n    Advance notification of the upgrade lets a client adjust its command\n    timeouts to take this into account and avoid aborting commands too soon.\n-   **Pre-handoffs**: Upgrades also involve migrating\n    Redis shards to new nodes, which inevitably disconnects clients from\n    existing nodes. However, with some advance warning of the disconnection,\n    a client can buffer commands, connect to a new node, and then resume\n    the buffered commands without aborting any of them. As a result, users\n    see no disruption in service. These transparent reconnections to new endpoints\n    are known as *pre-handoffs*.\n\n> [!NOTE]\n> SCH does not work with blocking connections.\n> These include connections used for blocking operations like\n> [`BLPOP`](https://redis.io/docs/latest/commands/blpop) and also\n> [pub/sub](https://redis.io/docs/latest/develop/pubsub) subscriptions.\n> All non-blocking operations are safe to use with SCH."
    },
    {
      "id": "sch-support-in-redis-client-libraries",
      "title": "SCH support in Redis client libraries",
      "role": "content",
      "text": "SCH is enabled automatically on the client side during connection\nif you select the [RESP3](https://redis.io/docs/latest/develop/reference/protocol-spec#resp-versions)\nprotocol, which is a requirement for SCH. However, you can\nconfigure some parameters, such as the timeouts to use\nduring maintenance.\n\nThe following table lists the Redis client libraries that support SCH,\nand the versions that added support for standard routing and for\n[OSS Cluster API](https://redis.io/docs/latest/operate/rs/databases/configure/oss-cluster-api) connections.\nStandard routing covers any connection that doesn't use the OSS Cluster API.\n\n| Client | Standard routing | OSS Cluster API |\n| :-- | :-- | :-- |\n| [redis-py](https://redis.io/docs/latest/develop/clients/redis-py/connect#connect-using-smart-client-handoffs-sch) | v7.0.0 | v7.2.0 |\n| [node-redis](https://redis.io/docs/latest/develop/clients/nodejs/connect#connect-using-smart-client-handoffs-sch) | v5.9.0 | v5.11.0 |\n| [Lettuce](https://redis.io/docs/latest/develop/clients/lettuce/connect#connect-using-smart-client-handoffs-sch) | v7.0.0 | - |\n| [go-redis](https://redis.io/docs/latest/develop/clients/go/connect#connect-using-smart-client-handoffs-sch) | v9.16.0 | v9.18.0 |\n| [StackExchange.Redis](https://redis.io/docs/latest/develop/clients/dotnet/connect#connect-using-smart-client-handoffs-sch) | v3.3.0 | v3.3.0 |\n\n> [!NOTE]\n> SCH is currently disabled when a client is configured for\n> [Client-side geographic failover](https://redis.io/docs/latest/develop/clients/failover).\n> Integration of the two features is planned for a future release."
    },
    {
      "id": "sch-support-in-redis-server-products",
      "title": "SCH support in Redis server products",
      "role": "content",
      "text": ""
    },
    {
      "id": "redis-cloud",
      "title": "Redis Cloud",
      "role": "content",
      "text": "SCH is fully supported and enabled by default on Redis Cloud, except when you\nare using one of the following options:\n\n- [AWS PrivateLink](https://redis.io/docs/latest/operate/rc/security/aws-privatelink)\n- [Google Cloud Private Service Connect](https://redis.io/docs/latest/operate/rc/security/private-service-connect)\n\nThese services don't currently allow for pre-handoffs, but you still get the\nbenefit of relaxed timeouts during database version upgrades. All other\nconfigurations have full support for both relaxed timeouts and pre-handoffs."
    },
    {
      "id": "redis-software",
      "title": "Redis Software",
      "role": "content",
      "text": "You must enable SCH explicitly on self-managed Redis Software servers by using the\n[v1/cluster](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster)\nREST API request to set the `client_maint_notifications` option to `true`.\nThe example below shows how to do this using the\n[`curl`](https://curl.se/) command line utility:\n\n[code example]\n\nRedis Software uses relaxed timeouts to avoid command failures during\ndatabase version upgrades. SCH is supported for Redis Software from v8.0.2 on,\nand OSS Cloud and OSS Cluster API from v8.0.16 on.\n\nThe degree of support for pre-handoffs depends on\nthe specific upgrade method you use, as detailed in the table below.\n\n| Upgrade method | SCH support | Expected behavior |\n| --- | --- | --- |\n| [Rolling upgrade](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-cluster#rolling-upgrade) | Full | New nodes and old ones removed sequentially. SCH pre-handoffs and relaxed timeouts greatly reduce disruptions during the upgrade. |\n| [In-place upgrade](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-cluster#in-place-upgrade) | Partial | Relaxed timeouts reduce errors but there are no pre-handoffs. Disconnections occur when processes are replaced during the upgrade, so clients should rely on auto-reconnect, which will cause brief lapses in service. |\n| [Maintenance mode](https://redis.io/docs/latest/operate/rs/clusters/maintenance-mode) | Full | SCH is fully supported during hardware or OS patching operations. Pre-handoffs and relaxed timeouts minimize application impact. |"
    },
    {
      "id": "redis-enterprise-for-kubernetes",
      "title": "Redis Enterprise for Kubernetes",
      "role": "content",
      "text": "SCH is not currently supported for [Kubernetes](https://redis.io/docs/latest/operate/kubernetes) clusters."
    },
    {
      "id": "redis-open-source",
      "title": "Redis Open Source",
      "role": "content",
      "text": "SCH is not currently supported for [Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack)."
    }
  ],
  "examples": [
    {
      "id": "redis-software-ex0",
      "language": "bash",
      "code": "curl -k -X PUT -H \"accept: application/json\" \\\n    -H \"content-type: application/json\" \\\n    -u \"test@redis.com:test123\" \\\n    -d '{ \"client_maint_notifications\": true }' \\\n    https://localhost:9443/v1/cluster",
      "section_id": "redis-software"
    }
  ]
}