This document provides a complete learning path for first-time users of Distributed Cache (Redis-compatible), covering everything from product familiarization to business launch. If you already know what you need to do, you can navigate directly to the relevant phase. If you are new to Distributed Cache, we recommend reading in order and moving to the next phase only after the current one is completed.
Getting Started Roadmap
From account registration to stable business operation, you typically go through the following six phases. The first three phases determine the configuration and cost of your instance, while the last three phases determine the stability and maintainability of your business.
|
| What problems can this product solve for me |
| Which engine, architecture, and specifications should I choose |
| How do I create a usable instance |
| How do I confirm that the instance is accessible |
| How to use the cache in code |
| How to prevent failures and data loss |
Note that Phase 6 is often skipped by beginners, but backup rules and alarm policies are exactly the key configurations that determine the extent of loss when a failure occurs. We recommend completing them before your business is officially connected.
Step 1: Understanding the Product
1.1 Product Capabilities and Use Cases
Distributed Cache (Redis-compatible) is an in-memory database service that is compatible with the Redis protocol and stores data in memory to deliver millisecond-level read and write responses. We recommend reading the following three product overviews in order, as they answer three questions: what it is, why to choose it, and where to use it.
|
1 | | Product positioning, core capabilities, and service forms |
2 | | Differences from self-managed Redis, such as high availability, auto scaling, and Ops-free maintenance |
3 | | Cache acceleration, leaderboards, session storage, message queues, and other implementation scenarios |
After reading these three documents, you should be able to determine whether your business is suitable for Distributed Cache and which traffic you plan to handle with it.
1.2 Understanding Key Terms
Terms such as shard, replica, master node, Proxy, and AZ appear frequently throughout the Distributed Cache documentation. If you are unfamiliar with these concepts, you may make incorrect decisions during subsequent selection. We recommend that you first browse Glossary, and you can refer to Terminology at any time when you encounter unfamiliar expressions. Step 2: Completing Product Selection
Selection is the phase where beginners are most prone to mistakes. After an instance is created, the engine type and region cannot be changed. The specifications and architecture can be adjusted, but this incurs change costs. Therefore, we recommend completing the following four decisions before purchase.
2.1 Choosing a Storage Engine
The product offers three storage engines, each designed for different compatibility and feature requirements. The positioning differences among the three are as follows. For a detailed capability comparison, see Storage Engine, Redis Edition, and Valkey Edition. |
Redis | 4.0,5.0,6.2,7.0 | General-purpose choice, complete feature coverage, validated in large-scale production environments |
Valkey | 8.0,9.0 | As the successor to Redis, Valkey delivers performance optimizations in I/O processing. |
Memcached | 1.6 | Only simple key-value caching is required, and the business has been developed based on the Memcached protocol. |
For version selection, we recommend prioritizing newer stable versions to get full data structure and command support. For specific differences, see Major Version Feature List. Also, pay attention to Version Lifecycle Plan to avoid choosing versions that will soon be discontinued. 2.2 Choosing an Architecture
Architecture determines the capacity limit and scaling method of an instance, making it the most far-reaching decision in the selection process. The differences between the two architectures are as follows.
|
Memory specifications | 256MB - 64GB | Single shard: 1 GB to 64 GB |
Shard quantity | Not involved | 1 - 128 shards, with a maximum total capacity of 8 TB |
Data Distribution | Single shard stores full data. | Data is distributed across shards based on hash slots. |
Scaling method | Increase single shard memory capacity | Increase the number of shards to horizontally scale capacity and throughput. |
Concurrent performance | 80,000 - 100,000 QPS | 80,000 - 100,000 per shard, up to tens of millions of QPS |
Command Compatibility | Full support | Compatibility limitations exist for cross-slot commands. |
The decision is based on data volume and command usage: choose the standard architecture when the data volume is within 64 GB and your business uses Lua scripts or cross-key operations extensively. Choose the cluster architecture when the expected data volume exceeds 64 GB or higher throughput is required, but confirm the compatibility of your business commands in advance. For architecture principles, see Standard Architecture and Cluster Architecture. For command differences, see Differences Between Proxy Architecture and Direct Connection Mode. Note:
The 256 MB specification is an entry-level experience specification, suitable only for test environment validation and not recommended for production environments, with limited supported AZs. The data in the table above is for general reference only, and the actual available specifications are subject to what is displayed on the purchase page. The standard architecture can be upgraded to the cluster architecture later, but the upgrade involves data redistribution and requires a compatibility assessment in advance. If the data growth trend is clear, we recommend choosing the cluster architecture from the beginning.
2.3 Determining Specifications and Deployment Location
A specification consists of three dimensions: memory capacity, replica quantity, and number of shards. Together, these dimensions determine the capacity, performance, and availability level of an instance. For the connection quantity and throughput limit of each specification, see Specifications and Performance. The replica quantity can range from 1 to 5, and its role is reflected in two aspects: first, improving availability. All replica nodes participate in high-availability failover. When the master node fails, the system automatically promotes one of the replicas to be the new master node, and the more replicas there are, the higher the availability. Second, improving read performance. When the replica quantity is not less than 1, you can enable read/write separation to offload read requests to replica nodes. For production businesses with high availability requirements, we recommend configuring at least 2 replicas. The number of shards is a specification dimension specific to the cluster architecture and does not apply to the standard architecture. For the cluster architecture, you can choose 1 to 128 shards (available values include 1, 3, 5, 8, 12, 16, 24, 32, 40, 48, 64, 80, 96, and 128). The memory specification per shard ranges from 1 GB to 64 GB. The total instance capacity is the product of the per-shard capacity and the number of shards, up to 8 TB. The number of shards also determines the throughput limit, which can be linearly estimated at 80,000 to 100,000 QPS per shard. If you upgrade from the standard architecture to the cluster architecture later, you need to determine the number of shards again during the upgrade.
For the number of connections, the default limit for each specification is 10,000 (10,000 per shard for the cluster architecture), and it can be adjusted up to 40,000. If your business requires more connections than the default value, you can request additional quota through Adjust Connection Count. The principle for selecting a region and AZ is to deploy nearby: an instance should be in the same region as the CVM that accesses it. Cross-region access significantly increases network latency. For businesses with higher availability requirements, you can choose multi-AZ deployment to distribute nodes across different data centers to withstand data-center-level failures. For the available options, see Regions and AZs. Note:
A region cannot be changed after an instance is created. If you select the wrong region, you can only adjust by creating a new instance and migrating data.
2.4 Choosing a Billing Mode
Billing modes are divided into two types: yearly/monthly subscription and pay-as-you-go. The difference lies in the payment timing and unit cost.
|
Monthly Subscription | Pay before use, billed by purchase duration. | For businesses that run stably over a long period, the unit cost is lower. |
Pay-as-You-Go | Postpaid, settled by actual usage duration. | Scenarios involving short-term testing, temporary capacity expansion, or uncertain usage. |
You are advised to understand the rules for specification changes, renewal, refunds, and overdue payments before purchase to avoid unexpected fees or service interruptions later:
|
How Billing Works When Specifications Are Adjusted | |
How to Renew Upon Expiration | |
How to Request a Refund When No Longer in Use | |
What Happens When an Account Has Overdue Payments | |
Step 3: Creating an Instance
After you complete the selection, you can create an instance. Before creating an instance, make sure that you have completed Tencent Cloud account registration and identity verification, and that your account has sufficient balance. For instructions on filling in the configuration items on the purchase page, see Purchasing an Instance. For the steps to quickly create an instance for the first time, see Quickly Creating an Instance. Note:
Two configurations deserve special attention during the creation process. The first is Password, which serves as the first line of access defense for an instance. We recommend that you set a strong password directly, and you can also enforce unified password rules through Set Password Complexity. The second is VPC and Subnet. The instance should be placed in the same VPC as your business servers. Otherwise, you need to configure network connectivity to enable access. Step 4: Connecting and Verifying
4.1 Preparing for Connection
Connection failure is the most common issue encountered by new users, and its causes typically fall into three categories: network unreachability, security groups not allowing access, and incorrect password format. We recommend that you read Connection Preparation first and confirm that the following conditions are all met. |
Network Connectivity | The client and the instance are in the same VPC, or Peering Connection, CCN, or other interconnection methods have been configured. |
Security Group | The security group bound to the instance allows access to the client source IP address and access port (default: 6379). |
Connection Address | The VIP address and port have been obtained from the network information section on the instance details page. |
Password Format | When the default account is used, the format is Instance ID:Password. When a custom account is used, the format is Username@Password. |
The password format is a point that new users tend to overlook. For the default account, the instance ID needs to be prefixed to the password. If you enter only the password, authentication will fail. For security group configuration, see Configuring Security Groups. 4.2 Establishing a Connection and Verifying It
After a successful connection, we recommend that you run two commands for basic verification. First, run the PING command. If PONG is returned, the link is normal. Then, run SET and GET once to confirm that data can be read and written normally. If both checks pass, the instance is ready for production use.
Note:
The password authentication and connection methods described in this chapter and subsequent content apply to the Redis edition and Valkey edition. The Memcached edition supports only password-free access and cannot be connected through DMC or redis-cli. You need to use telnet instead. For details, see Storage Engine. Step 5: Integrating Business Code
5.1 Choosing a Client and Writing Connection Code
Your business code connects to an instance through a standard Redis client, and the usage is the same as connecting to a self-managed Redis. Select the connection example that matches your development language.
|
Java | |
Python | |
Go | |
Node.js | |
PHP | |
C | |
.Net | |
If your business requires secure transmission, you can enable SSL Encryption to encrypt data before transmitting it over the link. 5.2 Understanding Command Compatibility in Advance
Not all Redis commands can be used on cloud instances. Some commands are restricted because they involve cluster management or pose data risks, and command differences also exist across versions. We recommend that you confirm the support status of the commands you use before writing code to avoid discovering incompatibility issues after deployment.
|
Overall Command Support Scope | |
Restricted Commands | |
Command Differences Across Major Versions | |
Traversal Methods in Cluster Architecture | |
Memcached Edition Compatibility | |
5.3 Following Development Guidelines to Avoid Typical Issues
Performance issues caused by poor cache design mostly originate in the design phase rather than the Ops phase. Big keys can cause a sharp increase in the latency of individual operations, hot keys can cause load imbalance on a single node, and an unreasonable eviction policy can keep the cache hit rate persistently low. Once these issues enter the production environment, the cost of remediation is far higher than avoiding them at the design stage.
Therefore, before your business is launched, we recommend that you read the development guidelines thoroughly:
|
| Naming confusion makes later maintenance and troubleshooting difficult. |
| Producing big keys causes operation blocking. |
| Improper eviction policies cause low hit rates or accidental data loss. |
| Misusing high-complexity commands slows down the overall response. |
| Improper connection pool configuration causes connection exhaustion or uneven load distribution. |
| Pressure concentrates on a single node, causing unstable performance. |
If you develop with the Spring ecosystem, you can refer to the Complete Integration Example in the practice tutorial, which includes the complete process of component configuration, service setup, and performance data collection. Step 6: Establishing Ops Assurance
Completing business access does not mean that your system is ready for launch. The following three configurations are used to address data loss, performance degradation, and security risks. We recommend that you complete all of them before your system starts carrying production traffic.
6.1 Configuring Data Backup
Backup is the baseline of data security. The system provides automatic backup capabilities, but you need to set the retention period and execution time based on the importance of your business data. We recommend that you schedule backups during off-peak hours and determine the backup frequency based on the data loss window your business can tolerate.
|
Understand backup types and restoration capabilities. | |
Set backup time and retention period. | |
Create a verification instance from backup data. | |
6.2 Configuring Monitoring and Alarms
Monitoring allows you to view the running status of instances, while alarms determine whether you can be notified promptly when exceptions occur. If you only view monitoring data without configuring alarms, issues are often discovered only after your business has been impacted. We recommend that you first read Monitoring Overview to understand the capabilities of the monitoring system, then refer to Monitoring Metrics (Redis/Valkey Edition) to understand the meaning of each metric, and finally observe the actual performance of your instances in Viewing Monitoring Data (Redis/Valkey Edition). For beginners, we recommend that you prioritize configuring alarms for the following four metrics, as they directly reflect whether capacity and load are approaching their limits:
|
Memory Utilization | The capacity is about to be fully written, which may trigger data eviction. | |
CPU Utilization | High-complexity commands exist or the request volume is excessive. | |
Connection utilization | The number of connections is approaching the specification limit, and new connections may be rejected. | |
Outbound traffic | Bandwidth is approaching the upper limit, and request queuing may occur. | |
6.3 Hardening Access Security
Instance security protection consists of two layers: network isolation and identity authentication. The network layer uses security groups to limit which sources can access the instance, and the identity layer uses accounts and passwords to limit the permission scope of accessors. Security groups should follow the principle of least privilege and allow access only to the source IPs and ports that your business actually requires, avoiding the practice of allowing all sources for convenience. For accounts, we recommend that you create separate accounts for different purposes and assign appropriate permissions. For example, a data analysis workload requires only read-only permissions.
|
Limit access sources | |
Create accounts and assign permissions. | |
Enforce password strength | |
Encrypt transmission links | |
Block high-risk commands. | |
Note:
The product supports password-free access, but this method lowers the access barrier and is recommended only in test environments with sufficient network isolation. In production environments, enable password authentication. FAQ Quick Reference
Issues encountered by new users typically fall into three categories: connection, instance selection, and billing. The following sections categorize these issues by scenario to help you quickly locate solutions.
Connections and Network
|
How to connect to an instance | |
How to troubleshoot connection failures | |
How to view the connection address | |
Whether it can be accessed from a public network | |
Other connection and network issues | |
Instance Management and Usage
|
What should I do if I forget my password? | |
How do I expand capacity when it is insufficient? | |
Can an accidentally deleted instance be recovered? | |
How to analyze performance that does not meet expectations | |
Other instance management issues | |
Selection and Pricing
|
How to choose specifications and architecture | |
How to request a refund if I purchased the wrong product | |
Whether Services Are Affected After Overdue Payments | |
Service availability commitment | |
Other feature and usage issues | |
Advanced Learning
After completing the six phases above, you will have acquired the foundational skills to support your business with Distributed Cache. To further improve availability, observability, or perform data migration, refer to the following directions.
|
All Ops Operations | Need to systematically understand all console features. | |
Migrating Data to the Cloud | Instances already on self-built or third-party clouds need to be migrated in. | |
Performance Diagnosis and Optimization | Need to locate slow queries, big keys, and hot keys. | |
Cross-Region Disaster Recovery | Business spans multiple regions, requiring local reads or region-level disaster recovery. | |
Automated Ops | Need to manage instances in batches through APIs. | |
Version and Feature Updates | Need to keep track of new product capabilities. | |
Getting Help
If you encounter any issues or have suggestions for improvement during use, you can provide feedback through the following channels, and dedicated personnel will follow up.
Documentation Issues: If you find broken links, incorrect content, or unclear descriptions in the documentation, you can select the relevant content and click Documentation Feedback to submit your feedback on the pop-up page.
Product Issues: For questions about feature usage, troubleshooting, or billing, you can contact Online Support or see Contact Us for other support channels.