Tair Proxy features and routing rules - Tair (Redis® OSS-Compatible)

In Tair (Redis OSS-compatible) instances that use the cluster architecture or read/write splitting architecture, proxy nodes are responsible for request routing, load balancing, and failover. Proxy nodes can simplify client-side logic and support advanced features such as multiple databases (DBs) and caching hotkeys. Understanding the routing rules of proxy nodes and how they handle specific commands helps you design more efficient business systems.

Overview of proxy nodes

A proxy node is a standalone component in a Tair instance. It does not consume the resources of data shards. Tair uses multiple proxy nodes to implement load balancing and failover.

Capability	Description
Usage mode transition for cluster instances	Proxy nodes can bridge architectures, allowing you to use a cluster architecture instance as if it were a standalone one. Proxy nodes support cross-slot operations for commands that manage multiple keys, such as DEL, EXISTS, MGET, MSET, SDIFF, and UNLINK. For more information, see List of commands supported in proxy mode. When a standalone architecture instance can no longer meet your business requirements, you can migrate data to a cluster architecture instance with proxy nodes without modifying your code. This significantly reduces business transformation costs.
Load balancing and request routing	Proxy nodes establish persistent connections with backend data shards and handle request routing and load balancing. For more information about routing, see Routing rules of proxy nodes.
Manage traffic to read replicas	Proxy nodes continuously monitor the status of read replicas and control traffic in the following situations: A read replica is in an abnormal state: The proxy node reduces the service weight of the replica. If the proxy node fails to connect to the replica multiple times, it stops sending traffic to the replica. The proxy node resumes sending traffic after the replica recovers. A read replica is performing a full data synchronization: The proxy node temporarily stops sending traffic to the replica until the synchronization is complete.
Proxy query cache	After you enable the proxy query cache feature, proxy nodes cache requests that contain hotkeys and their corresponding responses. When a proxy node receives the same request within the cache validity period, it directly returns the result to the client without interacting with the backend data shards. This helps mitigate access skew caused by a large number of read requests to hotkeys. Note You can enable this feature by setting the query_cache_enabled parameter. This feature is available only for Tair Memory-optimized and Persistent Memory-optimized instances.
Support for multiple databases (DBs)	In cluster mode, native Redis and cluster clients do not support multiple databases (DBs). They only use the default database `0` and do not support the `SELECT` command. However, you can connect to a cluster instance through a proxy node to use multiple DBs and the `SELECT` command. Cluster Edition instances support 256 DBs by default. Note If you use a StackExchange.Redis client, you must use version 2.7.20 or later. Otherwise, an error occurs. For more information, see the StackExchange.Redis upgrade announcement.

Note

As proxy technology evolves, the number of proxy nodes is not the only factor that determines processing capacity. Alibaba Cloud ensures that the ratio of proxy nodes in a cluster instance meets the specified requirements.

Routing rules of proxy nodes

Note

For more information about commands, see Command overview.

Architecture	Routing rule	Description
Cluster architecture	Basic routing rules	For commands that operate on a single key, the proxy node sends the request to the corresponding data shard based on the slot to which the key belongs. For commands that operate on multiple keys stored in different data shards, the proxy node splits the command into multiple commands and sends them to the corresponding shards. Note Starting from Redis Open-Source Edition 5.0.1, and in versions 6.0, 7.0, and later, proxy nodes split commands at the slot level, which is consistent with the Redis community. However, in minor versions of Redis Open-Source Edition 5.0 prior to 5.0.1, and in versions 4.0 and 2.8, the Proxy splits commands at the shard level. When these instances are upgraded to Redis Open-Source Edition 5.0 or later, the change in command splitting rules may cause an increase in QPS and a slight increase in traffic. However, because the Proxy delivers commands by using a pipeline, the impact on performance is relatively small.
Cluster architecture	Routing rules for specific commands	Pub/Sub commands For Pub/Sub commands such as SUBSCRIBE, the proxy node calculates a hash of the channel name and routes the request to the corresponding data shard. Although Pub/Sub commands do not write data to the database, they still consume memory and resources. This consumption is primarily due to client connections, subscription state management, and message buffers. For example, if a channel belongs to data shard 1, clients that subscribe to this channel consume the memory, CPU, and network bandwidth of data shard 1. Note In the Tair console, you can go to the Performance Monitoring page, select Data Node, and then select Pub/Sub Monitoring Group from the custom metrics list. This allows you to view monitoring information for Pub/Sub-related commands on each data shard. By default, data for the first data shard is displayed. Alibaba Cloud-developed commands When you use Alibaba Cloud-developed commands, such as IINFO and ISCAN, you can specify the data shard ID using the idx parameter. The proxy node then sends these commands to the specified data shard. For more information, see Alibaba Cloud-developed proxy commands.
Read/write splitting architecture	Basic routing rules	Write requests: The proxy node forwards write requests directly to the master node. Read requests: The proxy node evenly distributes read requests among the master node and read replicas. Customizing the distribution is not supported. For example, in an instance with one master node and three read replicas, each of the four nodes handles 25% of the read requests. Note SLOWLOG and DBSIZE are also considered read commands.
Read/write splitting architecture	Routing rules for specific commands	SCAN commands When you run HSCAN, SSCAN, or ZSCAN commands, the proxy node first calculates the slot to which the key belongs. Then, it uses a modulo operation to determine the target node. This ensures that requests are evenly distributed between the master node and read replicas. Alibaba Cloud-developed commands When you use Alibaba Cloud-developed commands, such as RIINFO and RIMONITOR, use the ro_slave_idx parameter to specify the target read replica and the idx parameter to specify the data shard. For more information, see Alibaba Cloud-developed proxy commands. Other commands The proxy node forwards transaction commands (MULTI or EXEC), Lua script commands (EVAL or EVALSHA), SCAN, INFO, and Pub/Sub commands (such as PUBLISH and SUBSCRIBE) to the master node.

Proxy query cache

Proxy nodes can cache requests that contain hotkeys and their corresponding query results. When a proxy node receives the same request within the cache validity period, it directly returns the result to the client without interacting with the backend data shards. This feature can mitigate or prevent performance degradation caused by access skew from a high volume of read requests to hotkeys.

The database kernel identifies a hotkey using sorting and statistical algorithms, similar to the Hot Key (QPS) in the Top Key Analytics feature. By default, a key is identified as a hotkey if its QPS exceeds 5,000. You can also customize this threshold using the bigkey-threshold parameter.
If a hotkey is modified while its data is cached, the changes are not synchronized to the cache. This means that subsequent requests may read stale data from the cache until the cache entry expires. You can shorten the cache validity period based on your business requirements.

Note

Proxy nodes do not cache the entire hotkey. Instead, they cache the requests that contain the hotkey and the corresponding query results.
This feature is available only for Tair Memory-optimized and Persistent Memory-optimized instances that use the cluster architecture in proxy mode or the read/write splitting architecture.

Use cases

This feature is suitable for scenarios such as trending topic lists, popular user profiles, and game announcements, where applications can tolerate slightly stale data.

Architecture

Usage

This feature is disabled by default. You can enable it by setting the query_cache_enabled parameter.

Parameters

Parameter	Description

query_cache_enabled	The proxy node query cache feature. When enabled, the proxy node caches requests and query results for hot keys. If the same request is received within the validity period, the proxy node directly returns the result to the client without interacting with the backend data shards. Important The key-value pairs of hot keys cached on the proxy node are not updated during the validity period. Before you enable this feature, confirm that your business can tolerate eventual consistency for the data within the cache validity period. query_cache_enabled: Specifies whether to enable this feature. Valid values are 0 (disable, default) and 1 (enable). query_cache_expire: The validity period of the cached data. The unit is milliseconds. The range is [100-60000]. The default is 1000. If cached data is modified during its validity period, the changes are not synchronized to the cache. This means that the same read request will retrieve dirty data from the cache until the cache expires. You need to carefully evaluate the value of this parameter based on your specific business scenario and tolerance for dirty data. Setting this value too low reduces the cache hit rate, while setting it too high causes clients to read dirty data for a longer period. query_cache_mode: The working mode of the proxy node query cache feature. Valid values: 0 (default): Caches only the hot keys pushed by data shards. 1: Caches all keys and evicts them based on the Least Recently Used (LRU) algorithm. Because the cache space of a proxy node is limited (100 MB per thread), if you set this parameter to 1, the proxy node will evict keys according to the LRU algorithm. This may reduce the cache hit rate and cause a decrease in overall performance.
query_cache_expire
query_cache_mode

You can use the Tair-developed QUERYCACHE KEYS, QUERYCACHE INFO, and QUERYCACHE LISTALL commands to view the usage of the Tair proxy query cache.

Commands

QUERYCACHE KEYS

Syntax: QUERYCACHE KEYS

Description: Queries all cached hotkeys in the proxy nodes. The command returns the database name and key name for each hotkey.

Example:

QUERYCACHE KEYS

Sample 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

Syntax: QUERYCACHE INFO

Description: Retrieves the operational status of the proxy query cache.

Example:

QUERYCACHE INFO

Sample 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"

Response fields:

put_qps: The number of writes to the proxy query cache from data nodes per second.
get_qps: The number of reads from the proxy query cache by clients per second.
hit_rate: The cache hit rate.
memory_size: The memory usage of the cached data, in bytes.
query_count: The number of cached requests.
bandwidth_limit_query_cnt: The number of times access to the proxy query cache was throttled due to bandwidth limits. Throttling is disabled by default.
qps_limit_query_cnt: The number of times access to the proxy query cache was throttled due to QPS limits. Throttling is disabled by default.

QUERYCACHE LISTALL

Syntax: QUERYCACHE LISTALL

Description: Retrieves all cached request commands.

Example:

QUERYCACHE LISTALL

Sample 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) 667

Description of the sample response: The information for each request command consists of three lines: the database name, the full content of the request command (formatted according to the Redis protocol specification), and the remaining time-to-live (TTL) in milliseconds.

Connection usage

Typically, a proxy node establishes persistent connections with data shards to process requests. However, when a request includes one of the following commands, the proxy node creates additional, non-aggregatable connections on the corresponding data shards based on the command's requirements. In these cases, the maximum number of connections for the instance is limited by the connection limit of a single data shard. For information about the connection limit of a single shard, see the specifications of your instance. Use these commands with care to avoid exceeding the connection limit.

Note

In proxy mode, the maximum number of connections for each data shard is 10,000 for Redis Open-Source Edition instances and 30,000 for Tair (Enterprise Edition) instances.

Blocking commands: BRPOP, BRPOPLPUSH, BLPOP, BZPOPMAX, BZPOPMIN, BLMOVE, BLMPOP, and BZMPOP.
Transaction commands: MULTI, EXEC, and WATCH.
MONITOR commands: MONITOR, IMONITOR, and RIMONITOR.
Subscription commands: SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE, SSUBSCRIBE, and SUNSUBSCRIBE.

FAQ

Can I forward Lua scripts that perform only read operations to read replicas?
Yes, you can forward Lua scripts that perform only read operations to read replicas. However, the following requirements must be met:
- A read-only account is used. For more information, see Create and manage accounts.
- The readonly_lua_route_ronode_enable parameter is set to 1 for your Tair instance. A value of 1 indicates that Lua scripts that perform only read operations are routed to read replicas. For more information, see Configure instance parameters.
Q: What is the difference between proxy mode and direct connection mode? Which mode is recommended?
A: We recommend using proxy mode. The differences are as follows:
- Proxy mode: proxy nodes forward client requests to data shards. This mode provides features such as load balancing, read/write splitting, failover, proxy query cache, and persistent connections.
- Direct connection mode: You can use a direct connection endpoint to bypass proxy nodes and connect directly to backend data shards. This is similar to connecting to a native Redis cluster. Compared with proxy mode, direct connection mode reduces proxy processing overhead and improves response latency.

Q: How are data reads and writes affected if a backend data shard becomes unavailable?

Each data shard uses a high-availability master-replica architecture. If a master node fails, the system automatically performs a failover to ensure high availability. The following table describes the impact of a data shard failure on data reads and writes in extreme scenarios and provides optimization solutions.

Scenario	Impact and optimization
Figure 1. Multi-key commands	Impact: A client sends four requests over four connections. If data shard 2 is unavailable, only Request 1 (GET Key1) can read data successfully. Requests that are routed to data shard 2 time out. Optimization: Reduce the use of multi-key commands, such as MGET, or reduce the number of keys in a single request. This prevents the entire request from failing due to a single unavailable data shard. Reduce the use of transaction commands or decrease the size of transactions. This prevents the failure of a sub-transaction from causing the entire transaction to fail.
Figure 2. Single connection	Impact: A client sends two separate requests over a single connection. If data shard 2 is unavailable, Request 2 (GET Key2) times out. Because Request 1 (GET Key1) shares the same connection, it also fails to return a result. Optimization: Avoid or reduce the use of pipeline. Avoid using clients that support only a single connection. We recommend that you use clients that support connection pooling. For more information, see Client connection tutorial. Ensure you configure a reasonable timeout and connection pool size.