Upstash Redis Key-Value Store

Upstash Redis 键值存储

Interact with Upstash's Redis-compatible key-value store using the REST interface.

使用REST接口与Upstash的Redis兼容键值存储进行交互。

Script Location

脚本位置

bash

bun run scripts/upstash-client.ts <command> [args...]

IMPORTANT: Always run with

bun run

, not directly.

bash

bun run scripts/upstash-client.ts <command> [args...]

重要提示：请始终使用

bun run

运行，不要直接执行。

Configuration

配置

Environment Variables

环境变量

The script uses these environment variables by default:

```
UPSTASH_REDIS_REST_URL
```
- The Upstash REST API URL
```
UPSTASH_REDIS_REST_TOKEN
```
- The Upstash REST API token

脚本默认使用以下环境变量：

```
UPSTASH_REDIS_REST_URL
```
- Upstash REST API地址
```
UPSTASH_REDIS_REST_TOKEN
```
- Upstash REST API令牌

Overriding Credentials

覆盖凭证

If the user provides credentials from another source (conversation context, a file, etc.), use the

--url

and

--token

flags to override environment variables:

bash

bun run scripts/upstash-client.ts --url "https://..." --token "AX..." GET mykey

Priority: Command-line flags > Environment variables

如果用户从其他来源（对话上下文、文件等）提供凭证，可以使用

--url

和

--token

标志覆盖环境变量：

bash

bun run scripts/upstash-client.ts --url "https://..." --token "AX..." GET mykey

优先级：命令行标志 > 环境变量

Command Reference

命令参考

String Commands

字符串命令

bash

undefined

bash

undefined

Get/Set

获取/设置

GET <key> SET <key> <value> [--ex seconds] [--px ms] [--nx] [--xx] [--keepttl] [--get] SETNX <key> <value> # Set if not exists SETEX <key> <seconds> <value> # Set with expiration

GET <key> SET <key> <value> [--ex seconds] [--px ms] [--nx] [--xx] [--keepttl] [--get] SETNX <key> <value> # 仅当键不存在时设置 SETEX <key> <seconds> <value> # 设置带过期时间的键值

Multiple keys (key/value pairs)

多键操作（键/值对）

MGET <key1> [key2...] MSET <key1> <val1> [key2 val2...] MSETNX <key1> <val1> [key2 val2...] # Set all if none exist

MGET <key1> [key2...] MSET <key1> <val1> [key2 val2...] MSETNX <key1> <val1> [key2 val2...] # 仅当所有键都不存在时设置

Counters

计数器操作

INCR <key> INCRBY <key> <increment> INCRBYFLOAT <key> <increment> DECR <key> DECRBY <key> <decrement>

String manipulation

字符串操作

APPEND <key> <value> STRLEN <key> GETRANGE <key> <start> <end> SETRANGE <key> <offset> <value>

undefined

APPEND <key> <value> STRLEN <key> GETRANGE <key> <start> <end> SETRANGE <key> <offset> <value>

undefined

Hash Commands

哈希命令

Hashes store field-value pairs. Pass fields and values as alternating arguments:

bash

undefined

哈希存储字段-值对。交替传入字段和值作为参数：

bash

undefined

Set hash fields (field/value pairs)

设置哈希字段（字段/值对）

HSET <key> <field1> <val1> [field2 val2...] HSETNX <key> <field> <value> # Set field if not exists

HSET <key> <field1> <val1> [field2 val2...] HSETNX <key> <field> <value> # 仅当字段不存在时设置

Get hash fields

获取哈希字段

HGET <key> <field> HMGET <key> <field1> [field2...] HGETALL <key>

Hash operations

哈希操作

HDEL <key> <field1> [field2...] HEXISTS <key> <field> HKEYS <key> HVALS <key> HLEN <key> HINCRBY <key> <field> <increment> HINCRBYFLOAT <key> <field> <increment> HSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**Examples:**

```bash

HDEL <key> <field1> [field2...] HEXISTS <key> <field> HKEYS <key> HVALS <key> HLEN <key> HINCRBY <key> <field> <increment> HINCRBYFLOAT <key> <field> <increment> HSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**示例：**

```bash

Store user data

存储用户数据

bun run scripts/upstash-client.ts HSET user:1 name "John" email "john@example.com" age 30

Get single field

获取单个字段

bun run scripts/upstash-client.ts HGET user:1 name

Get all fields

获取所有字段

bun run scripts/upstash-client.ts HGETALL user:1

Increment numeric field

递增数值字段

bun run scripts/upstash-client.ts HINCRBY user:1 age 1

undefined

bun run scripts/upstash-client.ts HINCRBY user:1 age 1

undefined

List Commands

列表命令

Lists are ordered collections. Values are pushed/popped from left (head) or right (tail):

bash

undefined

列表是有序集合。从左侧（头部）或右侧（尾部）推入/弹出值：

bash

undefined

Push elements

推入元素

LPUSH <key> <val1> [val2...] # Push to head RPUSH <key> <val1> [val2...] # Push to tail LPUSHX <key> <val1> [val2...] # Push if list exists RPUSHX <key> <val1> [val2...]

LPUSH <key> <val1> [val2...] # 推入头部 RPUSH <key> <val1> [val2...] # 推入尾部 LPUSHX <key> <val1> [val2...] # 仅当列表存在时推入头部 RPUSHX <key> <val1> [val2...]

Pop elements

弹出元素

LPOP <key> [count] RPOP <key> [count]

Access elements

访问元素

LRANGE <key> <start> <stop> # Get range (0 = first, -1 = last) LLEN <key> LINDEX <key> <index>

LRANGE <key> <start> <stop> # 获取范围（0=第一个元素，-1=最后一个元素） LLEN <key> LINDEX <key> <index>

Modify

修改操作

LSET <key> <index> <value> LREM <key> <count> <value> # Remove count occurrences LTRIM <key> <start> <stop> # Keep only range LINSERT <key> <BEFORE|AFTER> <pivot> <value> LPOS <key> <value> LMOVE <src> <dst> <LEFT|RIGHT> <LEFT|RIGHT>


**Examples:**

```bash

LSET <key> <index> <value> LREM <key> <count> <value> # 删除指定次数的元素 LTRIM <key> <start> <stop> # 仅保留指定范围的元素 LINSERT <key> <BEFORE|AFTER> <pivot> <value> LPOS <key> <value> LMOVE <src> <dst> <LEFT|RIGHT> <LEFT|RIGHT>


**示例：**

```bash

Create a task queue

创建任务队列

bun run scripts/upstash-client.ts RPUSH tasks "task1" "task2" "task3"

Get all tasks

获取所有任务

bun run scripts/upstash-client.ts LRANGE tasks 0 -1

Pop task from front (FIFO queue)

从头部弹出任务（FIFO队列）

bun run scripts/upstash-client.ts LPOP tasks

Pop task from back (LIFO stack)

从尾部弹出任务（LIFO栈）

bun run scripts/upstash-client.ts RPOP tasks

undefined

bun run scripts/upstash-client.ts RPOP tasks

undefined

Set Commands

集合命令

Sets store unique, unordered members:

bash

undefined

集合存储唯一、无序的成员：

bash

undefined

Add/remove members

添加/移除成员

SADD <key> <member1> [member2...] SREM <key> <member1> [member2...]

Query

查询操作

SMEMBERS <key> SISMEMBER <key> <member> SMISMEMBER <key> <member1> [member2...] SCARD <key>

Random access

随机访问

SPOP <key> [count] SRANDMEMBER <key> [count]

Set operations

集合操作

SINTER <key1> [key2...] SINTERSTORE <dest> <key1> [key2...] SUNION <key1> [key2...] SUNIONSTORE <dest> <key1> [key2...] SDIFF <key1> [key2...] SDIFFSTORE <dest> <key1> [key2...] SMOVE <src> <dst> <member> SSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**Examples:**

```bash

SINTER <key1> [key2...] SINTERSTORE <dest> <key1> [key2...] SUNION <key1> [key2...] SUNIONSTORE <dest> <key1> [key2...] SDIFF <key1> [key2...] SDIFFSTORE <dest> <key1> [key2...] SMOVE <src> <dst> <member> SSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**示例：**

```bash

Add tags

添加标签

bun run scripts/upstash-client.ts SADD article:1:tags "javascript" "redis" "nodejs"

Check membership

检查成员资格

bun run scripts/upstash-client.ts SISMEMBER article:1:tags "javascript"

Get all members

获取所有成员

bun run scripts/upstash-client.ts SMEMBERS article:1:tags

Find common tags between articles

查找文章之间的共同标签

bun run scripts/upstash-client.ts SINTER article:1:tags article:2:tags

undefined

bun run scripts/upstash-client.ts SINTER article:1:tags article:2:tags

undefined

Sorted Set Commands

有序集合命令

Sorted sets store members with scores for ranking:

bash

undefined

有序集合存储带有分数的成员用于排名：

bash

undefined

Add members (score/member pairs)

添加成员（分数/成员对）

ZADD <key> <score1> <member1> [score2 member2...] [--nx] [--xx] [--gt] [--lt] [--ch]

Remove

移除操作

ZREM <key> <member1> [member2...] ZREMRANGEBYRANK <key> <start> <stop> ZREMRANGEBYSCORE <key> <min> <max>

Scores and ranks

分数和排名

ZSCORE <key> <member> ZMSCORE <key> <member1> [member2...] ZRANK <key> <member> # Rank (low to high) ZREVRANK <key> <member> # Rank (high to low) ZINCRBY <key> <increment> <member>

ZSCORE <key> <member> ZMSCORE <key> <member1> [member2...] ZRANK <key> <member> # 排名（从低到高） ZREVRANK <key> <member> # 排名（从高到低） ZINCRBY <key> <increment> <member>

Range queries

范围查询

ZRANGE <key> <start> <stop> [--withscores] [--rev] [--byscore] [--bylex] ZRANGEBYSCORE <key> <min> <max> [--withscores] [--limit off,count] ZREVRANGE <key> <start> <stop> [--withscores] ZREVRANGEBYSCORE <key> <max> <min> [--withscores] [--limit off,count]

Counting

计数操作

ZCARD <key> ZCOUNT <key> <min> <max>

Pop

弹出操作

ZPOPMIN <key> [count] ZPOPMAX <key> [count]

Set operations

集合操作

ZINTERSTORE <dest> <numkeys> <key1> [key2...] ZUNIONSTORE <dest> <numkeys> <key1> [key2...] ZSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**Examples:**

```bash

ZINTERSTORE <dest> <numkeys> <key1> [key2...] ZUNIONSTORE <dest> <numkeys> <key1> [key2...] ZSCAN <key> <cursor> [MATCH pattern] [COUNT count]


**示例：**

```bash

Create leaderboard (score member pairs)

创建排行榜（分数成员对）

bun run scripts/upstash-client.ts ZADD leaderboard 1000 "player1" 1500 "player2" 1200 "player3"

Get top 3 with scores (highest first)

获取前3名及分数（从高到低）

bun run scripts/upstash-client.ts ZRANGE leaderboard 0 2 --rev --withscores

Get player's rank

获取玩家排名

bun run scripts/upstash-client.ts ZREVRANK leaderboard "player2"

Increment player's score

递增玩家分数

bun run scripts/upstash-client.ts ZINCRBY leaderboard 100 "player1"

Get players with scores between 1000 and 1500

获取分数在1000到1500之间的玩家

bun run scripts/upstash-client.ts ZRANGEBYSCORE leaderboard 1000 1500 --withscores

undefined

bun run scripts/upstash-client.ts ZRANGEBYSCORE leaderboard 1000 1500 --withscores

undefined

Key Commands

键命令

bash

undefined

bash

undefined

Delete

删除操作

DEL <key1> [key2...] UNLINK <key1> [key2...] # Async delete

DEL <key1> [key2...] UNLINK <key1> [key2...] # 异步删除

Existence/Type

存在性/类型检查

EXISTS <key1> [key2...] TYPE <key>

Expiration

过期时间设置

EXPIRE <key> <seconds> EXPIREAT <key> <timestamp> PEXPIRE <key> <milliseconds> PEXPIREAT <key> <timestamp> TTL <key> PTTL <key> PERSIST <key> # Remove expiration

EXPIRE <key> <seconds> EXPIREAT <key> <timestamp> PEXPIRE <key> <milliseconds> PEXPIREAT <key> <timestamp> TTL <key> PTTL <key> PERSIST <key> # 移除过期时间

Rename

重命名操作

RENAME <key> <newkey> RENAMENX <key> <newkey>

Search

搜索操作

KEYS <pattern> # Use with caution in production SCAN <cursor> [MATCH pattern] [COUNT count]

KEYS <pattern> # 生产环境中谨慎使用 SCAN <cursor> [MATCH pattern] [COUNT count]

Other

其他操作

COPY <src> <dst> DUMP <key> TOUCH <key1> [key2...] RANDOMKEY OBJECT ENCODING|FREQ|IDLETIME|REFCOUNT <key>


**Examples:**

```bash

COPY <src> <dst> DUMP <key> TOUCH <key1> [key2...] RANDOMKEY OBJECT ENCODING|FREQ|IDLETIME|REFCOUNT <key>


**示例：**

```bash

Set key with 1 hour expiration

设置带1小时过期时间的键

bun run scripts/upstash-client.ts SET session:abc "data" bun run scripts/upstash-client.ts EXPIRE session:abc 3600

Or in one command

或者一步完成

bun run scripts/upstash-client.ts SET session:abc "data" --ex 3600

Check TTL

检查剩余过期时间

bun run scripts/upstash-client.ts TTL session:abc

Scan keys matching pattern

扫描匹配模式的键

bun run scripts/upstash-client.ts SCAN 0 MATCH "user:*" COUNT 100

undefined

bun run scripts/upstash-client.ts SCAN 0 MATCH "user:*" COUNT 100

undefined

Server Commands

服务器命令

bash

PING [message]
ECHO <message>
DBSIZE
TIME
INFO [section]
FLUSHDB                                # Delete all keys in current DB (DANGEROUS)
FLUSHALL                               # Delete all keys in all DBs (DANGEROUS)

bash

PING [message]
ECHO <message>
DBSIZE
TIME
INFO [section]
FLUSHDB                                # 删除当前数据库中所有键（危险操作）
FLUSHALL                               # 删除所有数据库中所有键（危险操作）

Command Options

命令选项

SET Options

SET选项

bash

--ex <seconds>     # Expire in seconds
--px <ms>          # Expire in milliseconds
--exat <ts>        # Expire at Unix timestamp (seconds)
--pxat <ts>        # Expire at Unix timestamp (ms)
--nx               # Only set if key does not exist
--xx               # Only set if key exists
--keepttl          # Retain existing TTL
--get              # Return old value

bash

--ex <seconds>     # 秒级过期时间
--px <ms>          # 毫秒级过期时间
--exat <ts>        # Unix时间戳（秒）过期
--pxat <ts>        # Unix时间戳（毫秒）过期
--nx               # 仅当键不存在时设置
--xx               # 仅当键存在时设置
--keepttl          # 保留现有过期时间
--get              # 返回旧值

ZADD Options

ZADD选项

bash

--nx               # Only add new members
--xx               # Only update existing members
--gt               # Only update if new score > current
--lt               # Only update if new score < current
--ch               # Return number of changed elements

bash

--nx               # 仅添加新成员
--xx               # 仅更新现有成员
--gt               # 仅当新分数大于当前分数时更新
--lt               # 仅当新分数小于当前分数时更新
--ch               # 返回更改的元素数量

ZRANGE Options

ZRANGE选项

bash

--withscores       # Include scores in output
--byscore          # Range by score instead of rank
--bylex            # Range by lexicographical order
--rev              # Reverse order
--limit off,count  # Limit results (e.g., --limit 0,10)

bash

--withscores       # 输出中包含分数
--byscore          # 按分数范围查询而非排名
--bylex            # 按字典序范围查询
--rev              # 反转顺序
--limit off,count  # 限制结果数量（例如：--limit 0,10）

Output Format

输出格式

String values: Printed directly
null/nil: Prints
```
(nil)
```
Objects/arrays: Pretty-printed as JSON

字符串值：直接打印
null/nil：打印
```
(nil)
```
对象/数组：以格式化JSON打印

Confirmation Behaviour

确认行为

Default: Ask for Confirmation

默认：请求确认

Before executing any destructive operation (write, modify, or delete), you MUST ask the user for confirmation. This includes:

Write operations:

SET, SETNX, SETEX, PSETEX, MSET, MSETNX
HSET, HSETNX
LPUSH, RPUSH, LPUSHX, RPUSHX, LSET, LINSERT
SADD
ZADD

Modify operations:

INCR, INCRBY, INCRBYFLOAT, DECR, DECRBY
APPEND, SETRANGE
HINCRBY, HINCRBYFLOAT
LREM, LTRIM, LMOVE
ZINCRBY

Delete operations:

DEL, UNLINK
HDEL
LPOP, RPOP
SREM, SPOP, SMOVE
ZREM, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, ZPOPMIN, ZPOPMAX
FLUSHDB, FLUSHALL (extra caution)

TTL/Rename operations:

EXPIRE, EXPIREAT, PEXPIRE, PEXPIREAT, PERSIST
RENAME, RENAMENX

Example confirmation prompt:

"I'm about to HSET
user:1
with fields
{name: "John", email: "john@example.com"}
. Proceed?"

在执行任何破坏性操作（写入、修改或删除）之前，必须请求用户确认。包括：

写入操作：

SET, SETNX, SETEX, PSETEX, MSET, MSETNX
HSET, HSETNX
LPUSH, RPUSH, LPUSHX, RPUSHX, LSET, LINSERT
SADD
ZADD

修改操作：

INCR, INCRBY, INCRBYFLOAT, DECR, DECRBY
APPEND, SETRANGE
HINCRBY, HINCRBYFLOAT
LREM, LTRIM, LMOVE
ZINCRBY

删除操作：

DEL, UNLINK
HDEL
LPOP, RPOP
SREM, SPOP, SMOVE
ZREM, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, ZPOPMIN, ZPOPMAX
FLUSHDB, FLUSHALL（需格外谨慎）

TTL/重命名操作：

EXPIRE, EXPIREAT, PEXPIRE, PEXPIREAT, PERSIST
RENAME, RENAMENX

示例确认提示：

"我即将对
user:1
执行HSET操作，字段为
{name: "John", email: "john@example.com"}
。是否继续？"

YOLO Mode: Skip Confirmation

YOLO模式：跳过确认

If the user indicates they do not want to be asked for confirmation, respect this for all subsequent operations. Indicators include:

"YOLO mode"
"Don't ask for confirmation"
"You're free to make changes without asking"
"Just do it"
"No need to confirm"
"Auto-approve" or "auto-confirm"
Any similar phrasing indicating blanket approval

Once YOLO mode is activated, proceed with destructive operations without asking, but still inform the user what was done.

Example:

Set

user:1

with

{name: "John", email: "john@example.com"}

- done.

如果用户表示不需要确认，后续所有操作均无需询问。以下表述表示用户同意：

"YOLO模式"
"不要询问确认"
"你可以直接修改无需询问"
"直接执行"
"无需确认"
"自动批准"或"自动确认"
任何类似表示 blanket 批准的措辞

一旦激活YOLO模式，执行破坏性操作时无需询问，但仍需告知用户操作已完成。

示例：

已为
user:1
设置
{name: "John", email: "john@example.com"}
- 操作完成。

Error Handling

错误处理

If credentials are missing or invalid, the script will exit with an error message. Ensure the user has configured either:

Environment variables (

UPSTASH_REDIS_REST_URL

,

UPSTASH_REDIS_REST_TOKEN

)

Or provides credentials via
```
--url
```
and
```
--token
```
flags

如果凭证缺失或无效，脚本将退出并显示错误信息。确保用户已配置以下其中一项：

环境变量（

UPSTASH_REDIS_REST_URL

,

UPSTASH_REDIS_REST_TOKEN

）

或通过
```
--url
```
和
```
--token
```
标志提供凭证

When to Use This Skill

何时使用此技能

User explicitly asks to store or retrieve data from Upstash/Redis
Need to persist data across conversations or sessions
Implementing caching for expensive operations
Maintaining counters, rate limits, or statistics
Storing user preferences or session data
Building leaderboards or rankings (sorted sets)
Managing queues or task lists (lists)
Tagging or categorisation (sets)
Storing structured objects (hashes)
Any scenario requiring fast key-value storage

用户明确要求从Upstash/Redis存储或检索数据
需要跨对话或会话持久化数据
为耗时操作实现缓存
维护计数器、速率限制或统计数据
存储用户偏好或会话数据
构建排行榜或排名（有序集合）
管理队列或任务列表（列表）
标记或分类（集合）
存储结构化对象（哈希）
任何需要快速键值存储的场景

upstash-redis-kv

Original

Translation

Upstash Redis Key-Value Store

Upstash Redis 键值存储

Script Location

脚本位置

Configuration

配置

Environment Variables

环境变量

Overriding Credentials

覆盖凭证

Command Reference

命令参考

String Commands

字符串命令

Get/Set

获取/设置

Multiple keys (key/value pairs)

多键操作（键/值对）

Counters

计数器操作

String manipulation

字符串操作

Hash Commands

哈希命令

Set hash fields (field/value pairs)

设置哈希字段（字段/值对）

Get hash fields

获取哈希字段

Hash operations

哈希操作

Store user data

存储用户数据

Get single field

获取单个字段

Get all fields

获取所有字段

Increment numeric field

递增数值字段

List Commands

列表命令

Push elements

推入元素

Pop elements

弹出元素

Access elements

访问元素

Modify

修改操作

Create a task queue

创建任务队列

Get all tasks

获取所有任务

Pop task from front (FIFO queue)

从头部弹出任务（FIFO队列）

Pop task from back (LIFO stack)

从尾部弹出任务（LIFO栈）

Set Commands

集合命令

Add/remove members

添加/移除成员

Query

查询操作

Random access

随机访问

Set operations

集合操作

Add tags

添加标签

Check membership

检查成员资格

Get all members

获取所有成员

Find common tags between articles

查找文章之间的共同标签

Sorted Set Commands

有序集合命令

Add members (score/member pairs)

创建排行榜（分数成员对）