redis-connections

Redis 接続

Redis と効率よく通信するためのクライアント側のガイダンスです。接続の共有方法、コマンドのバッチ処理方法、本番環境で呼び出してはいけないコマンド、クライアント側キャッシュを有効にするタイミング、正常なトラフィックを損なわずに素早く失敗させるタイムアウトの設定方法を説明します。

適用する場面

• Redis クライアントの設定を作成またはレビューするとき（redis-py、Jedis、Lettuce、go-redis、NRedisStack）。
• Redis の小さな呼び出しを何度も行っており、レイテンシの原因を調べたいとき。
• 大規模なキー空間、セット、ハッシュ、リストを反復処理するとき。
• 頻繁にアクセスされるキーに対してクライアント側キャッシュを有効にするとき。
• 接続／読み取り／書き込みのタイムアウトを調整するとき。

1. プールまたは多重化を使う — リクエストごとに接続を作成しない

Redis クライアントコードで最も大きな間違いは、操作のたびに新しい TCP 接続を開くことです。必ず次のいずれかを使ってください。

• プール — N 個の永続接続を保持し、アプリケーションが呼び出しごとに借りる方式です（redis-py の ConnectionPool、Jedis の JedisPooled、go-redis クライアント）。
• 多重化 — すべてのリクエストで単一の接続を共有する方式です（Lettuce、NRedisStack）。

方式	使用するクライアント	注記
プール	redis-py、Jedis、go-redis	プールが枯渇すると接続の借用時にブロックされます。同時実行数に合わせてプールサイズを設定してください
多重化	Lettuce、NRedisStack	接続は単一です。BLPOP のようなブロッキングコマンドは実行できません

# redis-py — connection pool
pool = redis.ConnectionPool(host="localhost", port=6379, max_connections=50)
r = redis.Redis(connection_pool=pool)

Python、Java、Lettuce の例については、references/pooling.md を参照してください。

2. 大量の処理にはパイプラインを使う

結果が互いに依存しない N 個のコマンドは、パイプラインを使って 1 つのバッチとして送信します。往復は N 回ではなく 1 回で済みます。

pipe = redis.pipeline()
for user_id in user_ids:
    pipe.get(f"user:{user_id}")
results = pipe.execute()

パフォーマンスのためには非トランザクションのパイプラインを使い、原子性が本当に必要な場合にのみ pipeline(transaction=True) を使ってください（redis-core のトランザクションに関するガイダンスを参照）。

references/pipelining.md を参照してください。

3. すべてをスキャンするコマンドは避ける

キー空間全体（または大きなコンテナ全体）を走査するコマンドは、サーバーをブロックします。代わりに、増分処理を行うコマンドを使ってください。

避けるもの	使うもの
KEYS pattern	SCAN のカーソルループ
SMEMBERS large_set	SSCAN
HGETALL large_hash	HSCAN
巨大なリストに対する LRANGE 0 -1	ページング（LRANGE 0 100）

cursor = 0
while True:
    cursor, keys = redis.scan(cursor, match="user:*", count=100)
    for key in keys:
        process(key)
    if cursor == 0:
        break

ブロッキングコマンド（BLPOP、BRPOP、BLMOVE）は別です。データを意図的に待機するため、キューのコンシューマーには適しています。ただし、必ずタイムアウトを指定し、多重化された接続（Lettuce、NRedisStack）では実行しないでください。

references/blocking.md を参照してください。

4. 頻繁にアクセスされるキーにはクライアント側キャッシュを使う

頻繁に読み込まれ、書き込みはまれなデータ（設定、機能フラグ、リクエストごとのセッション）には、RESP3 クライアント側キャッシュを有効にしてください。クライアントはローカルコピーを保持し、書き込み時にはサーバーがそれを無効化するため、頻繁な読み取りでの往復を削減できます。

client = redis.Redis(
    host="localhost",
    port=6379,
    protocol=3,                                    # RESP3 is required
    cache_config=redis.CacheConfig(max_size=1000),
)

書き込みの多いワークロードや、絶えず変化するデータには使わないでください。無効化トラフィックが削減効果を上回ります。

references/client-cache.md を参照してください。

5. タイムアウトを明示的に設定する

デフォルト値はクライアントごとに異なり、長すぎる場合があります。アプリケーションの障害モデルに合った値を選んでください。

r = redis.Redis(
    host="localhost",
    socket_connect_timeout=2.0,   # fail fast on dead nodes
    socket_timeout=5.0,           # tune to expected operation time
    retry_on_timeout=True,
)

目安：接続タイムアウトは読み取り／書き込みタイムアウトより短くします。レイテンシに敏感な経路では短いタイムアウトとタイムアウト時の再試行を組み合わせ、バッチジョブでは長めのタイムアウトを設定します。

references/timeouts.md を参照してください。

参考資料

• Redis：接続プールと多重化
• Redis：パイプライン
• Redis：SCAN
• Redis：クライアント側キャッシュ
• Redis：クライアント