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>                    # 存在しない場合に設定
SETEX <key> <seconds> <value>          # 有効期限付きで設定

# 複数キー(キー/値ペア)
MGET <key1> [key2...]
MSET <key1> <val1> [key2 val2...]
MSETNX <key1> <val1> [key2 val2...]    # いずれも存在しない場合はすべて設定

# カウンタ
INCR <key>
INCRBY <key> <increment>
INCRBYFLOAT <key> <increment>
DECR <key>
DECRBY <key> <decrement>

# 文字列操作
APPEND <key> <value>
STRLEN <key>
GETRANGE <key> <start> <end>
SETRANGE <key> <offset> <value>

ハッシュコマンド

ハッシュはフィールド値ペアを保存します。フィールドと値を交互の引数として渡します:

# ハッシュフィールドを設定(フィールド/値ペア)
HSET <key> <field1> <val1> [field2 val2...]
HSETNX <key> <field> <value>           # フィールドが存在しない場合に設定

# ハッシュフィールドを取得
HGET <key> <field>
HMGET <key> <field1> [field2...]
HGETALL <key>

# ハッシュ操作
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]

例:

# ユーザーデータを保存
bun run scripts/upstash-client.ts HSET user:1 name "John" email "john@example.com" age 30

# 単一フィールドを取得
bun run scripts/upstash-client.ts HGET user:1 name

# すべてのフィールドを取得
bun run scripts/upstash-client.ts HGETALL user:1

# 数値フィールドをインクリメント
bun run scripts/upstash-client.ts HINCRBY user:1 age 1

リストコマンド

リストは順序付きコレクションです。値は左(ヘッド)または右(テール)からプッシュ/ポップされます:

# 要素をプッシュ
LPUSH <key> <val1> [val2...]           # ヘッドにプッシュ
RPUSH <key> <val1> [val2...]           # テールにプッシュ
LPUSHX <key> <val1> [val2...]          # リストが存在する場合にプッシュ
RPUSHX <key> <val1> [val2...]

# 要素をポップ
LPOP <key> [count]
RPOP <key> [count]

# 要素にアクセス
LRANGE <key> <start> <stop>            # 範囲を取得(0=最初、-1=最後)
LLEN <key>
LINDEX <key> <index>

# 変更
LSET <key> <index> <value>
LREM <key> <count> <value>             # count個の出現を削除
LTRIM <key> <start> <stop>             # 範囲のみを保持
LINSERT <key> <BEFORE|AFTER> <pivot> <value>
LPOS <key> <value>
LMOVE <src> <dst> <LEFT|RIGHT> <LEFT|RIGHT>

例:

# タスクキューを作成
bun run scripts/upstash-client.ts RPUSH tasks "task1" "task2" "task3"

# すべてのタスクを取得
bun run scripts/upstash-client.ts LRANGE tasks 0 -1

# 前からタスクをポップ(FIFOキュー)
bun run scripts/upstash-client.ts LPOP tasks

# 後ろからタスクをポップ(LIFOスタック)
bun run scripts/upstash-client.ts RPOP tasks

セットコマンド

セットは一意で順序付けられていないメンバーを保存します:

# メンバーを追加/削除
SADD <key> <member1> [member2...]
SREM <key> <member1> [member2...]

# クエリ
SMEMBERS <key>
SISMEMBER <key> <member>
SMISMEMBER <key> <member1> [member2...]
SCARD <key>

# ランダムアクセス
SPOP <key> [count]
SRANDMEMBER <key> [count]

# セット操作
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]

例:

# タグを追加
bun run scripts/upstash-client.ts SADD article:1:tags "javascript" "redis" "nodejs"

# メンバーシップをチェック
bun run scripts/upstash-client.ts SISMEMBER article:1:tags "javascript"

# すべてのメンバーを取得
bun run scripts/upstash-client.ts SMEMBERS article:1:tags

# 記事間の共通タグを検索
bun run scripts/upstash-client.ts SINTER article:1:tags article:2:tags

ソート済みセットコマンド

ソート済みセットはランキング用のスコアとともにメンバーを保存します:

# メンバーを追加(スコア/メンバーペア)
ZADD <key> <score1> <member1> [score2 member2...] [--nx] [--xx] [--gt] [--lt] [--ch]

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

# スコアとランク
ZSCORE <key> <member>
ZMSCORE <key> <member1> [member2...]
ZRANK <key> <member>                   # ランク(低→高)
ZREVRANK <key> <member>                # ランク(高→低)
ZINCRBY <key> <increment> <member>

# 範囲クエリ
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]

# カウント
ZCARD <key>
ZCOUNT <key> <min> <max>

# ポップ
ZPOPMIN <key> [count]
ZPOPMAX <key> [count]

# セット操作
ZINTERSTORE <dest> <numkeys> <key1> [key2...]
ZUNIONSTORE <dest> <numkeys> <key1> [key2...]
ZSCAN <key> <cursor> [MATCH pattern] [COUNT count]

例:

# リーダーボードを作成(スコア メンバーペア)
bun run scripts/upstash-client.ts ZADD leaderboard 1000 "player1" 1500 "player2" 1200 "player3"

# トップ3をスコア付きで取得(最高スコアから)
bun run scripts/upstash-client.ts ZRANGE leaderboard 0 2 --rev --withscores

# プレイヤーのランクを取得
bun run scripts/upstash-client.ts ZREVRANK leaderboard "player2"

# プレイヤーのスコアをインクリメント
bun run scripts/upstash-client.ts ZINCRBY leaderboard 100 "player1"

# スコアが1000〜1500のプレイヤーを取得
bun run scripts/upstash-client.ts ZRANGEBYSCORE leaderboard 1000 1500 --withscores

キーコマンド

# 削除
DEL <key1> [key2...]
UNLINK <key1> [key2...]                # 非同期削除

# 存在/タイプ
EXISTS <key1> [key2...]
TYPE <key>

# 有効期限
EXPIRE <key> <seconds>
EXPIREAT <key> <timestamp>
PEXPIRE <key> <milliseconds>
PEXPIREAT <key> <timestamp>
TTL <key>
PTTL <key>
PERSIST <key>                          # 有効期限を削除

# 名前変更
RENAME <key> <newkey>
RENAMENX <key> <newkey>

# 検索
KEYS <pattern>                         # 本番環境では注意して使用
SCAN <cursor> [MATCH pattern] [COUNT count]

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

例:

# 1時間の有効期限でキーを設定
bun run scripts/upstash-client.ts SET session:abc "data"
bun run scripts/upstash-client.ts EXPIRE session:abc 3600

# または1つのコマンドで
bun run scripts/upstash-client.ts SET session:abc "data" --ex 3600

# TTLをチェック
bun run scripts/upstash-client.ts TTL session:abc

# パターンに一致するキーをスキャン
bun run scripts/upstash-client.ts SCAN 0 MATCH "user:*" COUNT 100

サーバーコマンド

PING [message]
ECHO <message>
DBSIZE
TIME
INFO [section]
FLUSHDB                                # 現在のDB内のすべてのキーを削除(危険)
FLUSHALL                               # すべてのDB内のすべてのキーを削除(危険)

コマンドオプション

SET オプション

--ex <seconds>     # 秒単位で有効期限を設定
--px <ms>          # ミリ秒単位で有効期限を設定
--exat <ts>        # Unix タイムスタンプ(秒)で有効期限を設定
--pxat <ts>        # Unix タイムスタンプ(ミリ秒)で有効期限を設定
--nx               # キーが存在しない場合のみ設定
--xx               # キーが存在する場合のみ設定
--keepttl          # 既存の TTL を保持
--get              # 古い値を返す

ZADD オプション

--nx               # 新しいメンバーのみを追加
--xx               # 既存メンバーのみを更新
--gt               # 新しいスコア > 現在のスコアの場合のみ更新
--lt               # 新しいスコア < 現在のスコアの場合のみ更新
--ch               # 変更された要素の数を返す

ZRANGE オプション

--withscores       # 出力にスコアを含める
--byscore          # ランクではなくスコアで範囲を指定
--bylex            # 辞書順で範囲を指定
--rev              # 逆順
--limit off,count  # 結果を制限(例: --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

確認プロンプトの例:

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

YOLO モード: 確認をスキップ

ユーザーが確認を求めないことを表示している場合、以降のすべての操作でこれを尊重します。指標は以下を含みます:

• "YOLO mode"
• "Don't ask for confirmation"
• "You're free to make changes without asking"
• "Just do it"
• "No need to confirm"
• "Auto-approve" または "auto-confirm"
• これに類する包括的承認を示すフレーズ

YOLO モードが有効になると、確認なしに破壊的な操作を進めますが、ユーザーに何が行われたかを知らせます。

例:

Set user:1 with {name: "John", email: "john@example.com"} - done.

エラーハンドリング

認証情報が不足しているか無効な場合、スクリプトはエラーメッセージで終了します。ユーザーが以下のいずれかを設定していることを確認します:

1. 環境変数(UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN)
2. または --url と --token フラグ経由で認証情報を提供

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

• ユーザーが Upstash/Redis からのデータの保存または取得を明示的に要求
• 会話またはセッション全体でデータを永続化する必要がある
• 高コスト操作のキャッシングを実装
• カウンタ、レート制限、または統計を保持
• ユーザー設定またはセッションデータを保存
• リーダーボードまたはランキングを構築(ソート済みセット)
• キューまたはタスクリストを管理(リスト)
• タグ付けまたは分類(セット)
• 構造化オブジェクトを保存(ハッシュ)
• 高速キー値ストレージが必要なシナリオ