alibabacloud-tair-devtoolset

What this skill does

# 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](references/ram-policies.md) 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](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:
```
--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](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](references/architecture-selection/arch-selection.md) — Architecture selection decision guide
- [references/architecture-selection/arch-compare-oss-redis.md](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 / Ta