Alibabacloud Tair Devtoolset

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.

# 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