| name | alibabacloud-tair-devtoolset |
| description | Alibaba Cloud Tair development toolkit — 7 capabilities covering architecture selection, data structure design, instance creation & configuration, connection management, performance monitoring, error troubleshooting, and backup & recovery.
Executes real cloud operations via aliyun CLI (creating instances, modifying whitelists, managing backups, restoring data). Restore operations are high-risk and will overwrite current data. Ensure the RAM account has required permissions (see references/ram-policies.md).
Triggers: "tair", "create tair instance", "tair instance", "redis", "data structure", "backup", "PITR", "tair architecture", "tair connection", "tair error".
|
Tair DevToolset — Full-Lifecycle Tair Development Assistant
This Skill provides operational capabilities and development guidelines for Alibaba Cloud Tair (Redis OSS-Compatible) database, covering architecture selection, data structure design, instance creation, connection management, performance monitoring, error troubleshooting, and backup & recovery.
Note: This Skill executes real cloud operations via aliyun CLI. Restore operations are high-risk and will overwrite current data. Ensure the RAM account has the required permissions before use.
Supported Capabilities
| Capability | Description |
|---|
| Architecture Selection | Choose the right Tair architecture (Standard vs Cluster) and edition (Memory-optimized, Persistent memory, Disk-based) |
| Data Structure Design | Select optimal Redis and Tair extended data structures for your use case |
| Instance Creation | Create and configure Tair instances via aliyun CLI |
| Connection Management | Connect via standalone/proxy/cluster modes with TLS support |
| Performance Monitoring | Intelligent diagnostics via alibabacloud-tair-ai-assistant skill |
| Error Troubleshooting | Diagnose and resolve common Tair connection, cluster, memory, and client errors |
| Backup and Recovery | Configure backup policies, perform PITR, and restore data |
Part I — Cross-Cutting Concerns
1. Prerequisites
1.1 CLI Installation & Version
Aliyun CLI >= 3.3.3 required. Run aliyun version to verify. If not installed or version too low, see references/cli-installation-guide.md for installation instructions.
aliyun configure set --auto-plugin-install true
aliyun plugin update
jq --version
1.2 Authentication
All credential configurations follow existing aliyun CLI settings.
Security Rules:
- NEVER read, echo, or print AK/SK values (e.g.,
echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
- NEVER ask the user to input AK/SK directly in the conversation or command line
- NEVER use
aliyun configure set with literal credential values
- ONLY use
aliyun configure list to check credential status
aliyun configure list
If no valid profile exists, STOP here. Configure credentials outside of this session, then return.
1.3 AI-Mode Configuration
[MUST] Enable AI-Mode at the start of any workflow (before any CLI invocation):
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset"
[MUST] Disable AI-Mode at EVERY exit point — before delivering the final response for ANY reason (success, failure, error, user cancellation, etc.). AI-mode MUST NOT remain enabled after the skill stops running.
aliyun configure ai-mode disable
2. Security & Compliance
2.1 User-Agent Requirement
Every aliyun CLI command invocation must include:
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
2.2 RAM Permissions
This Skill requires R-KVStore RAM permissions for instance management, backup, and recovery operations. See references/ram-policies.md for the full permission table and policy document.
[MUST] Permission Failure Handling: When any command fails due to permission errors:
- Read
references/ram-policies.md to get the full list of required permissions
- Use
ram-permission-diagnose skill to guide the user through requesting permissions
- Pause and wait until the user confirms that the required permissions have been granted
3. Parameter Confirmation Rule
Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, passwords, resource specifications) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
Part II — Capabilities
4. Architecture Selection
Choose the right Tair architecture based on data volume, throughput requirements, and read/write ratio.
When to Use
- Deciding between Standard and Cluster architecture
- Determining whether read/write splitting is needed
- Selecting edition type (Memory-optimized, Persistent memory, Disk-based)
- Evaluating Tair vs Open Source Redis for a new project
Key Guidance
Key Concepts:
| Component | Description |
|---|
| Node | Smallest unit, runs Redis-compatible process |
| Shard | Group of nodes storing a subset of data |
| Master node | Handles write operations |
| Replica node | Copy of master, provides failover |
| Read-only node | Serves read traffic only (read/write splitting) |
| Proxy node | Routes requests to appropriate nodes |
Architecture Comparison:
| Dimension | Standard | Cluster |
|---|
| Structure | One master + replicas | Multiple shards, each with master + replicas |
| Data partitioning | No (single shard) | Yes (distributed across shards) |
| Best for | Small data, stable QPS | Large data, high QPS, throughput-intensive |
| Read/write splitting | Supported | Supported |
Selection Decision Tree:
Data volume > single-node capacity?
├── Yes → Cluster architecture
│ └── Read-heavy? → Enable read/write splitting
└── No → Standard architecture
└── Read-heavy? → Enable read/write splitting
References
5. Data Structure Design
Choose the appropriate data structure based on your access patterns and business requirements.
When to Use
- Selecting data structures for a new feature or application
- Choosing between Redis native and Tair extended data structures
- Migrating data models and evaluating structure alternatives
Key Guidance
Redis Data Structures:
| Name | Use Case |
|---|
| String | Caching, counters, distributed locks, session storage, rate limiting |
| Hash | Object storage (user profiles, product info), grouped field-value pairs |
| List | Message queues, latest feeds, task queues, stack/queue operations |
| Set | Unique collections, tagging, social graph (followers/friends), set operations |
| Sorted Set | Leaderboards, ranking systems, priority queues, range queries by score |
| Stream | Event sourcing, log streaming, message queues with consumer groups |
| Bitmap | Feature flags, online status tracking, daily active user counting |
| Bitfield | Compact counters, fixed-width integer encoding, atomic increment |
| Geospatial | Location-based services, nearby search, geofencing |
| HyperLogLog | Unique visitor counting, cardinality estimation with minimal memory |
Tair Data Structures:
| Name | Use Case |
|---|
| exString / TairString (String enhancement) | Versioned strings, bounded INCRBY, CAS/CAD for distributed locks |
| exHash / TairHash (Hash enhancement) | Field-level TTL, field versioning, multi-device login management |
| exZset / TairZset (Zset enhancement) | Multi-dimensional scoring (256 dims), multi-criteria ranking |
| GIS / TairGis (Geospatial enhancement) | Point/line/polygon queries, spatial relationship checks |
| Doc / TairDoc (JSON) | JSON with binary tree indexing, fast sub-element access |
| Search / TairSearch | ES-like full-text search, multi-column index, tokenization |
| TS / TairTs (TimeSeries) | Real-time monitoring, IoT data, two-level timeline aggregation |
| Bloom / TairBloom | Probabilistic membership testing, deduplication, URL filtering |
| Cpc / TairCpc | Compressed cardinality estimation, streaming analytics |
| Roaring / TairRoaring (Bitmap enhancement) | User segmentation, audience targeting, multi-bitmap operations |
| Vector / TairVector | Vector similarity search, LLM Chatbot, multimodal retrieval |
References
6. Instance Creation
Create and configure Tair instances on Alibaba Cloud, including whitelist configuration and public endpoint allocation.
When to Use
- Creating a new Tair instance for testing, development, or production
- Configuring network access (whitelist, public endpoint) for an instance
- Setting up a Tair benchmark or PoC environment
6.1 Choosing Instance Specifications
Required Parameters:
| Parameter | Description | Example |
|---|
| VPC_ID | VPC ID | vpc-bp1xxx |
| VSWITCH_ID | VSwitch ID | vsw-bp1xxx |
Optional Parameters (with defaults):
| Parameter | Default | Description |
|---|
| REGION_ID | cn-hangzhou | Region ID |
| ZONE_ID | cn-hangzhou-h | Zone ID |
| INSTANCE_TYPE | tair_rdb | Instance series: tair_rdb (DRAM), tair_scm (Persistent memory), tair_essd (ESSD disk) |
| INSTANCE_CLASS | tair.rdb.1g | Instance specification (see table below) |
| INSTANCE_NAME | tair-benchmark-<timestamp> | Instance name |
| CHARGE_TYPE | PostPaid | Billing method: PostPaid (pay-as-you-go), PrePaid (subscription) |
Common Specifications (Standard Architecture):
| InstanceClass | Memory | Bandwidth | Max Connections | QPS Reference |
|---|
| tair.rdb.1g | 1 GB | 768 Mbps | 30,000 | 300,000 |
| tair.rdb.2g | 2 GB | 768 Mbps | 30,000 | 300,000 |
| tair.rdb.4g | 4 GB | 768 Mbps | 40,000 | 300,000 |
| tair.rdb.8g | 8 GB | 768 Mbps | 40,000 | 300,000 |
| tair.rdb.16g | 16 GB | 768 Mbps | 40,000 | 300,000 |
| tair.rdb.24g | 24 GB | 768 Mbps | 50,000 | 300,000 |
| tair.rdb.32g | 32 GB | 768 Mbps | 50,000 | 300,000 |
| tair.rdb.64g | 64 GB | 768 Mbps | 50,000 | 300,000 |
6.2 Automated Workflow (Script)
For quick end-to-end instance creation with public network access, use the all-in-one script:
Execution Constraints:
- MUST use
scripts/create-and-connect-test.sh for this workflow — do NOT bypass the script to directly call individual aliyun r-kvstore commands
- DO NOT write or concatenate aliyun CLI commands to replace script functionality
- Model's responsibility: collect parameters → set environment variables → run script
export VPC_ID="<user-confirmed VPC_ID>"
export VSWITCH_ID="<user-confirmed VSWITCH_ID>"
export REGION_ID="cn-hangzhou"
export ZONE_ID="cn-hangzhou-h"
export INSTANCE_TYPE="tair_rdb"
export INSTANCE_CLASS="tair.rdb.1g"
bash scripts/create-and-connect-test.sh
The script will automatically complete: Create instance → Wait for ready → Configure whitelist → Allocate public endpoint → Get public connection info.
6.3 Manual CLI Steps
For custom requirements (PrePaid subscription, no public endpoint, custom security groups, etc.), use manual CLI steps:
Step 1 — Create instance:
aliyun r-kvstore create-tair-instance \
--biz-region-id "$REGION_ID" --zone-id "$ZONE_ID" \
--vpc-id "$VPC_ID" --vswitch-id "$VSWITCH_ID" \
--instance-type "$INSTANCE_TYPE" --instance-class "$INSTANCE_CLASS" \
--password "$PASSWORD" --charge-type "$CHARGE_TYPE" \
--shard-type "MASTER_SLAVE" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
Step 2 — Wait for instance ready (poll until InstanceStatus is Normal):
aliyun r-kvstore describe-instance-attribute \
--instance-id "$INSTANCE_ID" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
Step 3 — Configure whitelist:
aliyun r-kvstore modify-security-ips \
--instance-id "$INSTANCE_ID" --security-ips "$MY_PUBLIC_IP" \
--security-ip-group-name "default" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
Step 4 — Allocate public endpoint:
aliyun r-kvstore allocate-instance-public-connection \
--instance-id "$INSTANCE_ID" \
--connection-string-prefix "${INSTANCE_ID}pub" --port "6379" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
6.4 Success Verification
aliyun r-kvstore describe-instance-attribute \
--instance-id "$INSTANCE_ID" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset
Confirm InstanceStatus is Normal and public endpoint is allocated. For the full 3-step verification (instance status, whitelist, public endpoint), see references/verification-method.md.
References
7. Connection Management
Connect to Tair instances using various Redis-compatible clients in standalone, proxy, cluster, or TLS modes.
When to Use
- Connecting to a Tair instance from application code
- Choosing the right client library and connection mode
- Configuring TLS/SSL encryption for secure connections
- Troubleshooting connection issues
Key Guidance
Connection Modes:
| Mode | Architecture | Description |
|---|
| Standalone/Proxy | Standard or Cluster (proxy mode) | Connect via proxy node; supports all Redis commands including cross-slot multi-key |
| Cluster Direct | Cluster (direct mode) | Connect directly to data nodes; requires cluster-aware client; cross-slot multi-key commands not supported |
| TLS | Any (overlay) | Encrypt connections with TLS/SSL; supports both Proxy and Direct modes |
Authentication Format:
- Default account: password only
- Custom account:
<user>:<password>
- redis-cli: use
REDISCLI_AUTH environment variable — export REDISCLI_AUTH='InstanceID:Password'
Supported Clients: Jedis, Lettuce, Redisson (Java); redis-py (Python); Predis, phpredis (PHP); StackExchange.Redis (.NET); go-redis (Go); node-redis (Node.js); Spring Data Redis
References
8. Performance Monitoring
Intelligent performance monitoring and diagnostics via the Tair AI Assistant (DAS API).
When to Use
- Diagnosing slow queries or performance degradation
- Analyzing memory usage and identifying big keys / hotspot keys
- Tuning instance parameters and connection settings
- Monitoring instance health and resource utilization
Key Guidance
For intelligent diagnostics, install and use the alibabacloud-tair-ai-assistant skill:
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-tair-ai-assistant --agent <your-agent-platform>
The AI Assistant provides natural language based diagnostics covering: instance management, performance analysis, slow queries, memory analysis, big key / hotspot key detection, parameter tuning, and connection troubleshooting.
References
9. Error Troubleshooting
Diagnose and resolve common Tair errors across authentication, connection, cluster, memory, proxy, Lua/transactions, and client-specific issues.
When to Use
- Encountering authentication or connection errors
- Resolving cluster-related errors (cross-slot, moved, read-only)
- Handling memory exhaustion or command errors
- Debugging client-specific issues (Jedis, Lettuce, Redisson, go-redis, etc.)
Key Guidance
Common Error Categories:
| Category | Example Errors | Typical Cause |
|---|
| Authentication | NOAUTH Authentication required, WRONGPASS | Password not provided, incorrect password, or Lettuce CLIENT SETINFO bug |
| Connection | ERR illegal address, max number of clients reached | Client IP not in whitelist, connection pool leak, DNS failure |
| Cluster | CROSSSLOT Keys in request don't hash to the same slot, MOVED | Multi-key command across slots, key moved to another node |
| Memory/Command | OOM command not allowed, WRONGTYPE, ERR unknown command | Memory exceeded, wrong data type, command not supported |
| Proxy Mode | client ip is not in whitelist, redis temporary failure | Proxy whitelist, sub-instance timeout, request queue overflow |
| Lua/Transaction | BUSY Redis is busy running a script, NOSCRIPT | Long-running Lua script, script SHA not in cache |
| Client-specific | Jedis Could not get a resource from the pool, Lettuce NOAUTH with correct password, go-redis cluster format panic | Pool exhaustion, version incompatibility, RESP2/RESP3 mismatch |
References
10. Backup and Recovery
Configure backup policies, create manual backups, restore data from backups, and perform point-in-time recovery (PITR).
When to Use
- Configuring automatic backup policies
- Creating a manual backup before high-risk operations
- Restoring data from a backup set
- Performing point-in-time recovery (PITR) or key-filtered recovery
Key Guidance
Persistence Policies:
| Policy | Mechanism | Key Feature |
|---|
| RDB | Periodic snapshots | Small files, non-blocking backup |
| AOF | Logs all write operations | Fsync every second by default, AOF rewrite reduces disk usage |
| Tair-Binlog | Incremental AOF archiving (Enterprise DRAM only) | Prevents AOF rewrite degradation, enables PITR accurate to the second |
Key CLI Operations:
modify-backup-policy — Modify automatic backup schedulecreate-backup — Create a manual backupdescribe-backups — Query available backup setsrestore-instance — Restore from backup set or point-in-time
- Full backup:
--backup-id "$BACKUP_ID"
- PITR:
--restore-type 1 --restore-time "2024-01-15T10:30:00Z"
- Key-filtered PITR: add
--filter-key "session:*,user:*"
⚠️ HIGH-RISK OPERATION — restore-instance overwrites current data and cannot be undone.
Before executing any restore:
- Verify current write traffic — Check if the instance has active writes; notify the user if so
- Create a latest backup — Run
create-backup to preserve current data as a rollback point
- Confirm with the user — Explicitly inform that data will be overwritten and obtain confirmation
References
References Index
