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.

# Enable automatic plugin installation (required for r-kvstore plugin)
aliyun configure set --auto-plugin-install true

# Update existing plugins to latest version
aliyun plugin update

# Verify jq is installed (required for JSON parsing in scripts)
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:

1. Read references/ram-policies.md to get the full list of required permissions
2. Use ram-permission-diagnose skill to guide the user through requesting permissions
3. 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

• references/architecture-selection/arch-selection.md — Architecture selection decision guide
• references/architecture-selection/arch-compare-oss-redis.md — Tair vs Open Source Redis comparison and edition selection

---

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

• references/data-structure-design/data-structure-design.md — Detailed data structure use case descriptions
• Redis Data Types
• Tair Extended Data Structures

---

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

# Optional parameters
export REGION_ID="cn-hangzhou"
export ZONE_ID="cn-hangzhou-h"
export INSTANCE_TYPE="tair_rdb"
export INSTANCE_CLASS="tair.rdb.1g"
# For NAT environment, manually set public IP
# export MY_PUBLIC_IP="your-public-ip"

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

• references/instance-creation/connect-create-instance.md — End-to-end instance creation and connection guide with redis-cli examples
• references/related-commands.md — Complete CLI command and parameter reference
• references/verification-method.md — Detailed success verification steps
• references/acceptance-criteria.md — CLI command correctness standards

---

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

• references/connection-management/connect-standalone-or-proxy.md — Standalone/proxy connection examples in Java, Python, PHP, .NET, Go, Spring Data Redis
• references/connection-management/connect-cluster.md — Cluster connection examples (JedisCluster, RedisCluster, LettuceCluster, go-redis cluster, redis-cli)
• references/connection-management/connect-with-tls.md — TLS/SSL connection examples for all client types (Proxy + Direct)

---

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

• references/performance-monitoring/perf-monitoring.md — Performance monitoring reference
• alibabacloud-tair-ai-assistant

---

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

• references/error-troubleshooting/errors-troubleshooting.md — Complete error tables with causes and solutions for all error categories and client libraries
• Common errors and troubleshooting

---

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 schedule
• create-backup — Create a manual backup
• describe-backups — Query available backup sets
• restore-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:

1. Verify current write traffic — Check if the instance has active writes; notify the user if so
2. Create a latest backup — Run create-backup to preserve current data as a rollback point
3. Confirm with the user — Explicitly inform that data will be overwritten and obtain confirmation

References

• references/backup-and-recovery/backup-recovery.md — Complete backup/recovery guide with CLI examples and data protection details
• Data backup and restoration policies

---

References Index

| Reference | Description | Scope | |-----------|-------------|-------| | references/cli-installation-guide.md | Aliyun CLI installation and configuration guide | Cross-cutting | | references/ram-policies.md | RAM permission policy document | Cross-cutting | | references/acceptance-criteria.md | CLI command correctness standards | Cross-cutting (QA) | | references/related-commands.md | Complete CLI command and parameter reference | Instance Creation | | references/verification-method.md | Success verification steps | Instance Creation | | references/architecture-selection/arch-selection.md | Architecture selection decision guide | Architecture Selection | | references/architecture-selection/arch-compare-oss-redis.md | Tair vs Open Source Redis comparison | Architecture Selection | | references/data-structure-design/data-structure-design.md | Detailed data structure use cases | Data Structure Design | | references/instance-creation/connect-create-instance.md | End-to-end instance creation and connection guide | Instance Creation | | references/connection-management/connect-standalone-or-proxy.md | Standalone/proxy connection examples | Connection Management | | references/connection-management/connect-cluster.md | Cluster connection examples | Connection Management | | references/connection-management/connect-with-tls.md | TLS connection examples (Proxy + Direct) | Connection Management | | references/performance-monitoring/perf-monitoring.md | Performance monitoring and diagnostics | Performance Monitoring | | references/error-troubleshooting/errors-troubleshooting.md | Complete error tables with causes and solutions | Error Troubleshooting | | references/backup-and-recovery/backup-recovery.md | Backup and recovery strategies with CLI examples | Backup and Recovery |