mcpField
R
redis-clustering

redis-clustering

github.com/redisデータ・データベース1711.8k 回インストール7 週間前に更新
リポジトリ

redis-clustering について

Redis Clusterのシャーディング構成や単体のプライマリ／レプリカ構成で、キー設計と読み取り先の選択を案内するスキルです。CROSSSLOTエラーの回避と、結果整合性を踏まえたレプリカへの読み取り分散を扱います。

主な機能

  1. 01複数キー操作向けハッシュタグ
  2. 02レプリカへの読み取り分散
  3. 03プライマリ／レプリカのルーティング指針
  4. 04整合性のトレードオフ解説

活用シーン

  1. 01Redis Clusterのキー設計
  2. 02CROSSSLOTエラーの調査
  3. 03シャードを増やさず読み取りを拡張

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/redis/agent-skills --skill redis-clustering

インストール後、Claude Code で/redis-clusteringを入力して読み込まれたか確認します。

同梱ファイルreferences/hash-tags.mdreferences/read-replicas.md

詳細

Redis クラスタリング

シャーディングされた Redis Cluster（およびスタンドアロンのプライマリ／レプリカレプリケーション）でキーを設計し、読み取りをルーティングするためのガイダンスです。新たにクラスタを使い始めたユーザーが遭遇しやすい、複数キー操作での CROSSSLOT エラーと、読み取りトラフィックによるプライマリの過負荷という2つの障害モードを取り上げます。

適用するケース

  • Redis Cluster のデプロイでキーを設計するとき。
  • MGET、SDIFF、トランザクション、またはパイプラインで CROSSSLOT エラーをデバッグするとき。
  • 複数のキーを操作するトランザクション／Lua スクリプトを実装するとき。
  • シャードを追加せずに読み取りトラフィックを拡大するとき。

1. 複数キー操作のためのハッシュタグ

Redis Cluster はキー名をハッシュ化し、16,384 個のスロットにキーを分散します。複数のキーに対して操作するコマンド（MGET、SDIFF、SUNIONSTORE、トランザクション、パイプライン、複数の KEYS[] を使う Lua スクリプト）では、すべてのキーが同じスロットに属している必要があります。そうでない場合、サーバーは CROSSSLOT エラーを返します。

ハッシュタグを使うと、これを強制できます。{ と } の間の部分だけがスロット割り当てのハッシュ化対象になるため、同じハッシュタグを持つ2つのキーは必ず同じ場所に配置されます。

# Same slot — multi-key ops work
redis.set("{user:1001}:profile",  "...")
redis.set("{user:1001}:settings", "...")
redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")

# Different keys, no hash tag — CROSSSLOT on multi-key commands in cluster mode
redis.set("user:1001:profile",  "...")
redis.set("user:1001:settings", "...")
pipe = redis.pipeline()
pipe.get("user:1001:profile")
pipe.get("user:1001:settings")
pipe.execute()  # CROSSSLOT error in cluster

目安：

  • 意味のあるエンティティの範囲に限定したタグを使います。例：{user:1001}。{1001} のような単独のタグは避けてください。無関係な名前空間（purchase:{1001}、employee:{1001}）がすべて同じスロットに集中してしまいます。
  • 実際に複数キー操作が必要な場合にだけタグを付けます。すべてにタグを付けるとホットスポットが生じ、シャーディングの利点が損なわれます。
  • ハッシュタグ付きのキーでも単一キーのコマンドは問題なく使えるため、後からタグを追加していくこともできます。ただし、本番環境でのキー名変更は困難です。まとめて操作するエンティティについては、あらかじめタグを付ける計画を立ててください。

references/hash-tags.md を参照してください。

2. 読み取り負荷の高いワークロードでの読み取りレプリカ

書き込みよりも読み取りが多い場合は、読み取りをレプリカに振り分けることでプライマリの負荷を軽減できます。Redis Cluster（各シャードに1つ以上のレプリカがある場合）と、スタンドアロンのプライマリ／レプリカレプリケーションの両方で利用できます。

# Redis Cluster: enable replica reads on the client
from redis.cluster import RedisCluster

rc = RedisCluster(host="localhost", port=6379, read_from_replicas=True)
rc.set("key", "value")     # → primary
value = rc.get("key")       # → may be served by a replica

クラスタ以外の構成では、2つのクライアントを適切なノードに接続します。

primary = Redis(host="primary-host", port=6379)
replica = Redis(host="replica-host", port=6379)
primary.set("key", "value")
value = replica.get("key")

トレードオフは一貫性です。レプリカのデータは最終的に一貫します。レプリカから自分の書き込みを読み取らないでください。また、厳密な鮮度が必要な用途（金融残高、冪等性の状態など）にレプリカ読み取りを使わないでください。適した用途は、キャッシュ層、分析、ダッシュボード、レコメンデーションフィードです。

references/read-replicas.md を参照してください。

参考資料

コメント

Markdown 対応