upstash-redis-kv

Upstash Redis 键值存储

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

脚本位置

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

重要：始终使用 bun run 运行，不要直接运行。

配置

环境变量

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

• UPSTASH_REDIS_REST_URL - Upstash REST API URL
• UPSTASH_REDIS_REST_TOKEN - Upstash REST API 令牌

覆盖凭据

如果用户提供了来自其他来源（对话上下文、文件等）的凭据，请使用 --url 和 --token 标志覆盖环境变量：

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

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

命令参考

字符串命令

# 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

# Multiple keys (key/value pairs)
MGET <key1> [key2...]
MSET <key1> <val1> [key2 val2...]
MSETNX <key1> <val1> [key2 val2...]    # Set all if none exist

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

哈希命令

哈希用于存储字段-值对。按交替顺序传入字段和值：

# Set hash fields (field/value pairs)
HSET <key> <field1> <val1> [field2 val2...]
HSETNX <key> <field> <value>           # Set field if not exists

# 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]

示例：

# Store user data
bun run scripts/upstash-client.ts HSET user:1 name "John" email "[email protected]" 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

列表命令

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

# 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...]

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

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

示例：

# 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)
bun run scripts/upstash-client.ts LPOP tasks

# Pop task from back (LIFO stack)
bun run scripts/upstash-client.ts RPOP tasks

集合命令

集合用于存储唯一且无序的成员：

# 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]

示例：

# 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

有序集合命令

有序集合用于存储带有分数的成员，以便进行排名：

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

# 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]

示例：

# 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)
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
bun run scripts/upstash-client.ts ZRANGEBYSCORE leaderboard 1000 1500 --withscores

键命令

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

# 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

# Rename
RENAME <key> <newkey>
RENAMENX <key> <newkey>

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

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

示例：

# Set key with 1 hour expiration
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

服务端命令

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

命令选项

SET 选项

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

ZADD 选项

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

ZRANGE 选项

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

输出格式

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

确认行为

默认：请求确认

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

写入操作：

• 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: "[email protected]"}。是否继续？"

YOLO 模式：跳过确认

如果用户表示不希望被征求确认，请在之后的所有操作中遵照执行。包括以下表达：

• “YOLO 模式”
• “不要征求确认”
• “你可以不经询问直接进行更改”
• “直接做”
• “无需确认”
• “自动批准”或“自动确认”
• 任何类似的、表示全面授权的表述

启用 YOLO 模式后，执行破坏性操作无需征求确认，但仍须告知用户已完成的操作。

示例：

已将 {name: "John", email: "[email protected]"} 设置到 user:1。

错误处理

如果凭据缺失或无效，脚本会报错退出。请确保用户已配置以下任一项：

1. 环境变量（UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN）
2. 或通过 --url 和 --token 标志提供凭据

何时使用此技能

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