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#

CapabilityDescriptionArchitecture SelectionChoose the right Tair architecture (Standard vs Cluster) and edition (Memory-optimized, Persistent memory, Disk-based)Data Structure DesignSelect optimal Redis and Tair extended data structures for your use caseInstance CreationCreate and configure Tair instances via aliyun CLIConnection ManagementConnect via standalone/proxy/cluster modes with TLS supportPerformance MonitoringIntelligent diagnostics via alibabacloud-tair-ai-assistant skillError TroubleshootingDiagnose and resolve common Tair connection, cluster, memory, and client errorsBackup and RecoveryConfigure 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.

bash

# 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

bash

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):

bash

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.

bash

aliyun configure ai-mode disable

2. Security & Compliance#

2.1 User-Agent Requirement#

Every aliyun CLI command invocation must include:

text

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

ComponentDescriptionNodeSmallest unit, runs Redis-compatible processShardGroup of nodes storing a subset of dataMaster nodeHandles write operationsReplica nodeCopy of master, provides failoverRead-only nodeServes read traffic only (read/write splitting)Proxy nodeRoutes requests to appropriate nodes

Architecture Comparison:

DimensionStandardClusterStructureOne master + replicasMultiple shards, each with master + replicasData partitioningNo (single shard)Yes (distributed across shards)Best forSmall data, stable QPSLarge data, high QPS, throughput-intensiveRead/write splittingSupportedSupported

Selection Decision Tree:

text

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:

NameUse CaseStringCaching, counters, distributed locks, session storage, rate limitingHashObject storage (user profiles, product info), grouped field-value pairsListMessage queues, latest feeds, task queues, stack/queue operationsSetUnique collections, tagging, social graph (followers/friends), set operationsSorted SetLeaderboards, ranking systems, priority queues, range queries by scoreStreamEvent sourcing, log streaming, message queues with consumer groupsBitmapFeature flags, online status tracking, daily active user countingBitfieldCompact counters, fixed-width integer encoding, atomic incrementGeospatialLocation-based services, nearby search, geofencingHyperLogLogUnique visitor counting, cardinality estimation with minimal memory

Tair Data Structures:

NameUse CaseexString / TairString (String enhancement)Versioned strings, bounded INCRBY, CAS/CAD for distributed locksexHash / TairHash (Hash enhancement)Field-level TTL, field versioning, multi-device login managementexZset / TairZset (Zset enhancement)Multi-dimensional scoring (256 dims), multi-criteria rankingGIS / TairGis (Geospatial enhancement)Point/line/polygon queries, spatial relationship checksDoc / TairDoc (JSON)JSON with binary tree indexing, fast sub-element accessSearch / TairSearchES-like full-text search, multi-column index, tokenizationTS / TairTs (TimeSeries)Real-time monitoring, IoT data, two-level timeline aggregationBloom / TairBloomProbabilistic membership testing, deduplication, URL filteringCpc / TairCpcCompressed cardinality estimation, streaming analyticsRoaring / TairRoaring (Bitmap enhancement)User segmentation, audience targeting, multi-bitmap operationsVector / TairVectorVector 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:

ParameterDescriptionExampleVPC_IDVPC IDvpc-bp1xxxVSWITCH_IDVSwitch IDvsw-bp1xxx

Optional Parameters (with defaults):

ParameterDefaultDescriptionREGION_IDcn-hangzhouRegion IDZONE_IDcn-hangzhou-hZone IDINSTANCE_TYPEtair_rdbInstance series: tair_rdb (DRAM), tair_scm (Persistent memory), tair_essd (ESSD disk)INSTANCE_CLASStair.rdb.1gInstance specification (see table below)INSTANCE_NAMEtair-benchmark-<timestamp>Instance nameCHARGE_TYPEPostPaidBilling method: PostPaid (pay-as-you-go), PrePaid (subscription)

Common Specifications (Standard Architecture):

InstanceClassMemoryBandwidthMax ConnectionsQPS Referencetair.rdb.1g1 GB768 Mbps30,000300,000tair.rdb.2g2 GB768 Mbps30,000300,000tair.rdb.4g4 GB768 Mbps40,000300,000tair.rdb.8g8 GB768 Mbps40,000300,000tair.rdb.16g16 GB768 Mbps40,000300,000tair.rdb.24g24 GB768 Mbps50,000300,000tair.rdb.32g32 GB768 Mbps50,000300,000tair.rdb.64g64 GB768 Mbps50,000300,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

bash

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:

bash

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):

bash

aliyun r-kvstore describe-instance-attribute \
  --instance-id "$INSTANCE_ID" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

Step 3 — Configure whitelist:

bash

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:

bash

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#

bash

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:

ModeArchitectureDescriptionStandalone/ProxyStandard or Cluster (proxy mode)Connect via proxy node; supports all Redis commands including cross-slot multi-keyCluster DirectCluster (direct mode)Connect directly to data nodes; requires cluster-aware client; cross-slot multi-key commands not supportedTLSAny (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:

bash

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:

CategoryExample ErrorsTypical CauseAuthenticationNOAUTH Authentication required, WRONGPASSPassword not provided, incorrect password, or Lettuce CLIENT SETINFO bugConnectionERR illegal address, max number of clients reachedClient IP not in whitelist, connection pool leak, DNS failureClusterCROSSSLOT Keys in request don't hash to the same slot, MOVEDMulti-key command across slots, key moved to another nodeMemory/CommandOOM command not allowed, WRONGTYPE, ERR unknown commandMemory exceeded, wrong data type, command not supportedProxy Modeclient ip is not in whitelist, redis temporary failureProxy whitelist, sub-instance timeout, request queue overflowLua/TransactionBUSY Redis is busy running a script, NOSCRIPTLong-running Lua script, script SHA not in cacheClient-specificJedis Could not get a resource from the pool, Lettuce NOAUTH with correct password, go-redis cluster format panicPool 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:

PolicyMechanismKey FeatureRDBPeriodic snapshotsSmall files, non-blocking backupAOFLogs all write operationsFsync every second by default, AOF rewrite reduces disk usageTair-BinlogIncremental 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#

ReferenceDescriptionScopereferences/cli-installation-guide.mdAliyun CLI installation and configuration guideCross-cuttingreferences/ram-policies.mdRAM permission policy documentCross-cuttingreferences/acceptance-criteria.mdCLI command correctness standardsCross-cutting (QA)references/related-commands.mdComplete CLI command and parameter referenceInstance Creationreferences/verification-method.mdSuccess verification stepsInstance Creationreferences/architecture-selection/arch-selection.mdArchitecture selection decision guideArchitecture Selectionreferences/architecture-selection/arch-compare-oss-redis.mdTair vs Open Source Redis comparisonArchitecture Selectionreferences/data-structure-design/data-structure-design.mdDetailed data structure use casesData Structure Designreferences/instance-creation/connect-create-instance.mdEnd-to-end instance creation and connection guideInstance Creationreferences/connection-management/connect-standalone-or-proxy.mdStandalone/proxy connection examplesConnection Managementreferences/connection-management/connect-cluster.mdCluster connection examplesConnection Managementreferences/connection-management/connect-with-tls.mdTLS connection examples (Proxy + Direct)Connection Managementreferences/performance-monitoring/perf-monitoring.mdPerformance monitoring and diagnosticsPerformance Monitoringreferences/error-troubleshooting/errors-troubleshooting.mdComplete error tables with causes and solutionsError Troubleshootingreferences/backup-and-recovery/backup-recovery.mdBackup and recovery strategies with CLI examplesBackup and Recovery