In the cluster and read/write splitting architectures of Tair (Redis OSS-compatible), proxy nodes handle request forwarding, load balancing, and failover on behalf of your clients. Because the proxy manages cluster topology and traffic distribution transparently, your application connects to a single endpoint without tracking individual shards or handling node failures. This page explains how proxy nodes route requests, manage connections, and cache hot key results—information that helps you design more efficient systems and avoid common pitfalls.
How the proxy works
Each proxy node uses a single-node architecture within a Tair instance. It maintains persistent connections to backend data shards, so connection overhead is aggregated rather than duplicated per client. Load balancing and failover are handled across multiple proxy nodes without consuming resources from the data shards themselves.
The proxy delivers three core capabilities:
Simplified cluster access: Multi-key commands such as
DEL,EXISTS,MGET,MSET,SDIFF, andUNLINKwork across slots, just as they do on a standard (single-node) instance. The proxy splits and forwards them to the appropriate shards transparently. When you outgrow a standard architecture, you can migrate to a cluster architecture with a proxy without changing client code.Read traffic management: In read/write splitting mode, the proxy monitors read-only node health in real time. If a node becomes unhealthy, the proxy reduces its traffic weight and stops forwarding to it. If a node is performing a full synchronization, the proxy suspends its traffic until synchronization completes.
Hot key caching: The Proxy Query Cache feature caches requests for hot keys and their responses at the proxy layer. Repeated reads within the cache validity period are served directly from the proxy without touching backend shards.
The number of proxy nodes does not directly represent processing capacity. Alibaba Cloud ensures that the proxy count for each cluster instance type meets the requirements specified in the instance type description.
Proxy routing rules
For a full list of supported commands, see Command overview.
Cluster architecture
Basic routing
For single-key commands, the proxy routes the request to the shard that owns the key's slot. For multi-key commands where keys span multiple shards, the proxy splits the command and dispatches sub-commands to each relevant shard.
The slot-level split behavior depends on the Redis Open-Source Edition version:
Redis 5.0.1 and later (including 6.0, 7.0+): Commands are split at the slot level, consistent with Redis community behavior.
Redis 4.0, 2.8, and Redis 5.0 earlier than 5.0.1: Commands are split at the shard level. When these instances are upgraded to Redis 5.0 or later, the change in split granularity may cause a temporary increase in queries per second (QPS) and a slight increase in traffic. Because the proxy uses pipelining for delivery, the performance impact is minimal.
Pub/Sub commands
For PUBLISH and SUBSCRIBE commands, the proxy hashes the channel name and routes the command to the corresponding shard. Pub/Sub does not write data to the database, but it does consume memory, CPU, and network bandwidth on the shard that owns the channel—including client connections, subscription state management, and message buffers.
To monitor Pub/Sub traffic per shard, go to the Performance Monitoring page in the console, select Data node, and set the custom monitoring item to Pub/Sub Monitoring Group.
Alibaba Cloud proprietary commands
For commands such as IINFO and ISCAN, use the idx parameter to route the command to a specific shard. For details, see Self-developed Proxy commands.
Read/write splitting architecture
Basic routing
Write requests: Forwarded directly to the primary node.
Read requests: Distributed evenly across the primary node and all read-only nodes. Custom weight configuration is not supported. For example, in an instance with three read-only nodes, the read weight for the primary node and each read-only node is 25%.
SLOWLOG and DBSIZE are treated as read commands and distributed accordingly.
SCAN commands
For HSCAN, SSCAN, and ZSCAN, the proxy calculates the key's slot and then uses a modulo operation to distribute requests evenly across the primary node and read-only nodes.
Alibaba Cloud proprietary commands
For commands such as RIINFO and RIMONITOR, use the ro_slave_idx parameter to route to a specific read-only node, or the idx parameter to route to a specific shard. For details, see Proxy commands developed in-house by Alibaba Cloud.
Commands routed to the primary node only
Transaction commands (MULTI, EXEC), Lua script commands (EVAL, EVALSHA), SCAN, INFO, and Pub/Sub commands (PUBLISH, SUBSCRIBE) are always forwarded to the primary node.
Multiple databases in cluster mode
Native Redis cluster clients use only the default database 0 and do not support the SELECT command. By connecting through a proxy, your cluster instance supports multiple databases and SELECT. A cluster instance provides 256 databases by default.
If you use the StackExchange.Redis client, upgrade to version 2.7.20 or later. Earlier versions produce an error with multi-database access. See the StackExchange.Redis Upgrade Announcement for details.
Proxy Query Cache
The Proxy Query Cache caches requests for hot keys and their results at the proxy layer. When the same request arrives within the cache validity period, the proxy returns the cached result directly without querying backend shards. This reduces access skew caused by heavy read traffic on hot keys.
How hot keys are identified
Hot key identification uses the same logic as the Top Key Statistics feature: the database kernel identifies hot keys by sorting and statistical algorithms. A key is considered hot when its QPS exceeds 5,000 by default. Adjust this threshold with the bigkey-threshold parameter.
The proxy caches the request and its result, not the key-value pair itself. If a hot key is modified during its cache validity period, cached results are not updated—clients may read stale data until the cache expires. Shorten the query_cache_expire value if your workload cannot tolerate stale reads.
Use cases
This feature suits workloads that can tolerate eventual consistency, such as top search lists, popular user profiles, and game announcements.
Supported architectures and instance types
Proxy Query Cache is available only on Tair memory-optimized and persistent memory-optimized instances running cluster architecture proxy mode or read/write splitting architecture.
Feature architecture
Enable Proxy Query Cache
The feature is disabled by default. Set the query_cache_enabled parameter to 1 to enable it.
Parameters
| Parameter | Description | Values |
|---|---|---|
query_cache_enabled | Enables or disables Proxy Query Cache. | 0 (disabled, default), 1 (enabled) |
query_cache_expire | Cache validity period in milliseconds. If a key is modified during this window, reads return stale data until the cache expires. Balance between cache hit rate (longer TTL) and data freshness (shorter TTL). | Range: 100–60000. Default: 1000 |
query_cache_mode | Determines which keys are cached. 0 caches only hot keys pushed by data shards. 1 caches all keys using a Least Recently Used (LRU) eviction policy. With mode 1, each proxy thread has a 100 MB cache limit; LRU eviction may reduce hit rate and overall performance. | 0 (default), 1 |
Monitor cache usage
Use these Tair self-developed commands to inspect the proxy query cache state.
QUERYCACHE KEYS
Lists all hot keys currently cached on the proxy node, including the database name and key name for each entry.
QUERYCACHE KEYSExample response:
1) 1) (integer) 0
2) "key:000000000003"
2) 1) (integer) 0
2) "key:000000000001"
3) 1) (integer) 0
2) "key:000000000002"
4) 1) (integer) 0
2) "key:000000000000"QUERYCACHE INFO
Returns the running status of the proxy query cache.
QUERYCACHE INFOExample response:
1) "put_qps:4.00"
2) "get_qps:16570.00"
3) "hit_rate:99.98"
4) "memory_size:180"
5) "query_count:4"
6) "bandwidth_limit_query_cnt:0"
7) "qps_limit_query_cnt:0"Output fields:
| Field | Description |
|---|---|
put_qps | Writes per second from data nodes to the cache |
get_qps | Reads per second from clients to the cache |
hit_rate | Cache hit rate |
memory_size | Memory used by cached data, in bytes |
query_count | Number of cached queries |
bandwidth_limit_query_cnt | Times access was throttled due to bandwidth limits (disabled by default) |
qps_limit_query_cnt | Times access was throttled due to QPS limits (disabled by default) |
QUERYCACHE LISTALL
Returns all cached request commands.
QUERYCACHE LISTALLExample response:
1) 1) (integer) 0
2) "*2\r\n$3\r\nGET\r\n$16\r\nkey:000000000000\r\n"
3) (integer) 668
2) 1) (integer) 0
2) "*2\r\n$3\r\nGET\r\n$16\r\nkey:000000000001\r\n"
3) (integer) 668
3) 1) (integer) 0
2) "*2\r\n$3\r\nGET\r\n$16\r\nkey:000000000003\r\n"
3) (integer) 668
4) 1) (integer) 0
2) "*2\r\n$3\r\nGET\r\n$16\r\nkey:000000000002\r\n"
3) (integer) 667Each entry contains three values: the database name, the full request command in Redis protocol format, and the remaining TTL (time to live) in milliseconds.
Connection usage
The proxy uses persistent connections to aggregate traffic to data shards. For most commands, connections are pooled and shared across clients.
Some commands require the proxy to create a dedicated, non-aggregatable connection to a specific shard. When these commands are in use, connection limits are determined by per-shard limits rather than the instance total. Use these commands carefully to avoid hitting the connection ceiling.
In proxy mode, the connection limit per shard is:
Redis Community Edition: 10,000 connections per shard
Enterprise Edition: 30,000 connections per shard
Commands that create extra connections:
| Category | Commands |
|---|---|
| Blocking commands | BRPOP, BRPOPLPUSH, BLPOP, BZPOPMAX, BZPOPMIN, BLMOVE, BLMPOP, BZMPOP |
| Transaction commands | MULTI, EXEC, WATCH |
| Monitor commands | MONITOR, IMONITOR, RIMONITOR |
| Subscription commands | SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE, SSUBSCRIBE, SUNSUBSCRIBE |
FAQ
Can I route read-only Lua scripts to read-only nodes?
Yes. Two conditions must be met: use a read-only account (see Create and manage accounts) and set the readonly_lua_route_ronode_enable parameter to 1 on your Tair instance (see Configure instance parameters).
What is the difference between proxy mode and direct connection mode?
Proxy mode is recommended for most workloads. The two modes compare as follows:
Proxy mode: Client requests pass through proxy nodes to data shards. This gives you load balancing, read/write splitting, automatic failover, proxy query cache, and persistent connections.
Direct connection mode: Connect directly to backend shards using a direct connection address, bypassing the proxy. This is similar to connecting to a native Redis cluster and eliminates proxy processing overhead, which can reduce response latency slightly.
How does an abnormal data shard affect reads and writes?
Data shards use a primary/secondary high-availability (HA) architecture. When the primary node fails, automatic failover restores service. In the rare case that a shard becomes abnormal before failover completes, the impact depends on how your client uses connections:Data shards use a primary/secondary high-availability architecture. When a primary node fails, the system automatically performs a primary/secondary failover to ensure high service availability. In the rare scenario that a data shard becomes abnormal, the impact on data and the optimization solutions are as follows.
| Scenario | Impact | Mitigation |
|---|---|---|
| Multi-key command (Figure 1) | Sub-commands targeting the abnormal shard time out. Other shards respond normally. A single failed shard can cause an entire MGET or transaction to fail. | Reduce the number of keys per multi-key command. Reduce transaction size so a single shard failure affects fewer operations. |
| Single-connection pipeline (Figure 2) | Even requests targeting healthy shards may not return if they share a connection with a request to the abnormal shard. | Avoid or reduce pipeline usage. Use a connection pool client with a reasonable timeout and pool size (see the Client program connection tutorial). |
Figure 1. Multi-key command scenario
Figure 2. Single-connection scenario
