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 に {name: "John", email: "[email protected]"} を HSET しようとしています。続行しますか？」

YOLO モード：確認を省略

ユーザーが確認を求めないように指示した場合は、それ以降のすべての操作でその指示に従います。該当する表現の例：

• 「YOLO モード」
• 「確認は不要です」
• 「確認せずに変更してかまいません」
• 「そのまま実行してください」
• 「確認する必要はありません」
• 「自動承認」または「自動確認」
• 全面的な承認を示す同様の表現

YOLO モードが有効になったら、破壊的な操作を確認なしで実行します。ただし、実行した内容は引き続きユーザーに知らせてください。

例：

{name: "John", email: "[email protected]"} を user:1 に設定しました。

エラー処理

認証情報がないか無効な場合、スクリプトはエラーメッセージを表示して終了します。次のいずれかをユーザーが設定していることを確認してください。

1. 環境変数（UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN）
2. または --url と --token フラグによる認証情報の指定

このスキルを使用する場面

• ユーザーが Upstash／Redis へのデータの保存または取得を明示的に求めた場合
• 会話やセッションをまたいでデータを保持する必要がある場合
• コストの高い操作のキャッシュを実装する場合
• カウンター、レート制限、統計情報を管理する場合
• ユーザー設定やセッションデータを保存する場合
• リーダーボードやランキング（ソート済みセット）を構築する場合
• キューやタスクリスト（リスト）を管理する場合
• タグ付けや分類（セット）を行う場合
• 構造化オブジェクト（ハッシュ）を保存する場合
• 高速なキーバリューストレージが必要なあらゆる場面