Skip to content

Redis CLI チートシート

インメモリのデータ構造ストア — CLI コマンドと使い方。

01

はじめに

Redis サーバーへの接続

標準のコマンドラインクライアントが、redis-cli です。デフォルトが 127.0.0.1:6379 への接続です。ホストは -h、ポートは -p、パスワードは -a で(または、シェルの履歴でシークレットが漏れるのを避けるため、REDISCLI_AUTH env 変数を設定しましょう)。TLS には、cert/key と共に --tls が要ります。URL スキーム redis:// が Redis 6+ でサポートされ、TLS には rediss:// です。

redis-cli
# connect to local server (default port 6379)
redis-cli

# connect to a remote host with custom port
redis-cli -h redis.example.com -p 6380

# connect with authentication
redis-cli -a "yourpassword"
redis-cli -h host -p 6379 -a "yourpassword"

# connect over TLS
redis-cli --tls --cert client.crt --key client.key -h host -p 6379

# connect using a URL (Redis 6+)
redis-cli redis://user:password@host:6379/0
redis-cli rediss://user:password@host:6379/0  # TLS

接続オプションとモード

対話モードと 1 回限りのモードの両方を redis-cli がサポートします。引数としてコマンドを渡すと、実行して exit します。stdin から RESP/テキストコマンドを読むのが、pipe モードです — スクリプティングと一括ロードに最適です。論理データベースを選ぶのが、-n です。組み込みのモニタリングのヘルパーが、--stat と --latency です。タイプの接頭辞なしで値を出力するのが、--raw で、パイプに有用です。

redis-cli
# select a specific database index (0-15)
redis-cli -n 1            # use database 1

# run a single command and exit (non-interactive)
redis-cli GET mykey
redis-cli -h host PING

# pass command with arguments
redis-cli SET counter 100
redis-cli INCR counter

# read commands from stdin (pipe mode)
echo "SET k1 v1" | redis-cli
cat commands.txt | redis-cli

# repeat a command every second (watch mode)
redis-cli --stat
redis-cli --latency

# pretty-print JSON output (Redis 6+)
redis-cli --raw GET user:json

PING と接続テスト

最も単純なヘルスチェックが、PING です。機能する Redis が PONG を返します。ラウンドトリップタイムを継続的に測るのが(ネットワーク問題の診断に有用)、--latency です。ヒストグラムを示すのが、--latency-dist で、rolling 統計をログするのが、--latency-history です。パフォーマンスチューニングの前に、接続品質の基準線を引くのに、これらを使いましょう。

redis-cli
# basic connectivity test
redis-cli ping
# PONG

# ping with a message (echoed back)
redis-cli PING "hello"
# "hello"

# test auth + connection in one shot
redis-cli -a password PING

# check round-trip latency (continuous)
redis-cli --latency
# output: min: 0, max: 1, avg: 0.27 (3421 samples)

# latency histogram
redis-cli --latency-dist

# latency history (rolling, every 15s by default)
redis-cli --latency-history -i 1

対話モードのヒント

Redis コマンドのための REPL であるのが、対話モードです。組み込みのドキュメント(インターネット不要)を示すのが、HELP <command> か HELP @<group> です。セッション内でサーバーを切り替えるのが、CONNECT です。画面の消去が、CLEAR です。引用符付き文字列のために、CLI が複数行の入力を自動検出します。Redis コマンドと CLI 固有のコマンド(:raw など)を区別するため、':' を接頭辞に付けましょう。

redis-cli
# start interactive mode
redis-cli

# inside the CLI:
127.0.0.1:6379> HELP SET       # command help
127.0.0.1:6379> HELP @string   # help for a command group
127.0.0.1:6379> SCAN 0         # any Redis command

# clear the screen
127.0.0.1:6379> CLEAR

# connect to a different server without restarting
127.0.0.1:6379> CONNECT host 6380

# exit
127.0.0.1:6379> EXIT
127.0.0.1:6379> QUIT

# multi-line input: end with a backslash
127.0.0.1:6379> SET mykey "this is \
a multi-line value"

# toggle raw output mode
127.0.0.1:6379> :raw

データベースの選択と基本

論理的な名前空間(0〜15)であるのが、Redis のデータベースです。同じメモリを共有し、隔離されたスキーマではありません。db 0 だけを使うのが、ほとんどのアプリです。現在の db を消去するのが、FLUSHDB で、すべてを消去するのが(注意!)、FLUSHALL です。単一のスレッドを共有するため、別のインスタンスかキーの接頭辞が推奨され、複数データベースは推奨されません。

redis-cli
# Redis has 16 logical databases (0-15) by default
SELECT 0     # switch to database 0
SELECT 15    # switch to database 15

# move a key to another database
MOVE mykey 1

# flush the current database (DESTRUCTIVE)
FLUSHDB

# flush ALL databases (VERY DESTRUCTIVE)
FLUSHALL

# get the number of keys in the current db
DBSIZE

# swap two databases (Redis 4.0+)
SWAPDB 0 1

ヘルプとコマンドの発見

サーバーのコマンドテーブルを内省するのが、COMMAND です。能力と arity の発見に有用です。構造化されたドキュメントを返すのが、COMMAND DOCS(7.0+)です。カテゴリ(@string、@hash、@server など)ごとにグループ化されたオフラインのドキュメントを示すのが、CLI の HELP コマンドです。すべての CLI フラグとオプションには、「redis-cli --help」を実行しましょう。

redis-cli
# list all commands (huge output)
COMMAND

# get details of a specific command
COMMAND INFO GET
COMMAND INFO SET HSET LPUSH

# structured documentation (Redis 7+)
COMMAND DOCS SET
COMMAND DOCS @string

# count available commands
COMMAND COUNT

# CLI help
redis-cli --help
redis-cli --version

# inside interactive mode
HELP
HELP @server
HELP @string
HELP @hash
HELP GETSET
02

Strings

基本の SET と GET

根本的な文字列の操作が、SET/GET です。存在しなければ設定するのが(ロックに使われます)、NX で、存在すれば設定するのが、XX です。アトミックに有効期限を設定するのが、EX/PX/EXAT/PXAT です(SET と EXPIRE の間の競合なし)。新しい値を設定しつつ、前の値を返すのが、GETSET です。512MB までバイナリセーフなのが、文字列です。

redis-cli
# set and get a key
SET mykey "Hello"
GET mykey               # "Hello"

# set only if not exists (NX) or only if exists (XX)
SET mykey "new" NX      # set only if key does NOT exist
SET mykey "new" XX      # set only if key DOES exist

# set with expiration (seconds / milliseconds)
SET token "abc" EX 3600    # expires in 3600s
SET token "abc" PX 60000   # expires in 60000ms

# set with expiration at a Unix timestamp
SET token "abc" EXAT 1700000000

# get and set atomically (returns old value)
GETSET counter 0        # returns old value, sets new

# delete a key
DEL mykey

数値カウンタ(INCR/DECR)

アトミックであるのが、INCR/DECR です。ロックなしの同時アクセスに安全です。これにより、Redis がカウンタ、レート制限(INCR + EXPIRE)、シーケンス ID の生成に理想的になります。小数に対応するが、倍精度を使うのが(丸めに注意)、INCRBYFLOAT です。値が整数でなければ、INCR がエラーを返します。

redis-cli
# increment a numeric string atomically
SET counter 100
INCR counter            # 101
INCRBY counter 10       # 111

# decrement
DECR counter            # 110
DECRBY counter 5        # 105

# floating point increment
SET price "10.50"
INCRBYFLOAT price 0.25  # "10.75"
INCRBYFLOAT price -1.00 # "9.75"

# all increment ops are atomic and concurrency-safe
# use for: counters, rate limiting, sequence IDs, stats

# INCR on a non-integer value returns an error
SET mystr "hello"
INCR mystr              # ERROR: value is not an integer

APPEND と文字列の操作

文字列を拡張するのが(欠けていれば作る)、APPEND です。長さを報告するのが、STRLEN です。部分文字列上で動くのが(バイナリセーフ)、GETRANGE/SETRANGE です。アトミックに返し削除するのが(1 回限りの読み取りパターンに有用)、GETDEL(6.2+)です。アトミックに値を返し TTL を設定するのが、GETEX です — 読み取り時のセッションの有効期限の更新に手軽です。

redis-cli
# append to a string value
SET msg "Hello"
APPEND msg " World"     # "Hello World"

# get string length
STRLEN msg              # 11

# get substring
GETRANGE msg 0 4        # "Hello"
GETRANGE msg 6 -1       # "World"

# overwrite a substring (grows if needed)
SETRANGE msg 6 "Redis"  # "Hello Redis"

# get and delete atomically
GETDEL mykey            # returns value AND deletes key
# get and set expiration atomically (6.2+)
GETEX mykey EX 3600     # returns value, sets TTL

# append only if key exists
APPEND existing_key "more"

MSET と MGET(バッチ操作)

操作を 1 ラウンドトリップへバッチするのが、MSET/MGET です。パフォーマンスには不可欠です(Redis がシングルスレッドであるため、コマンドごとのオーバーヘッドが効きます)。アトミックであるのが、MSETNX です。すべてのキーが設定されるか、どれもされません。多くの小さいキー・バリューのペアのためには、listpack のエンコーディング経由でより良いメモリ効率のために、それらをハッシュ(HSET)へグループ化することを検討しましょう。

redis-cli
# set multiple keys at once (atomic)
MSET k1 "v1" k2 "v2" k3 "v3"

# get multiple keys at once
MGET k1 k2 k3           # 1) "v1" 2) "v2" 3) "v3"

# set multiple only if ALL keys are new
MSETNX k1 "v1" k4 "v4"  # 1 if all set, 0 if any existed

# MSET/MGET reduce round-trips — much faster than
# separate SET/GET calls in a loop

# get the length of a string value
STRLEN k1               # 2

# set multiple fields of different keys is not possible;
# for per-field updates use hashes (HSET)

# pipeline alternative in CLI:
printf '%s\n' "SET k1 v1" "SET k2 v2" "GET k1" | redis-cli --pipe-mode

Bitmaps(文字列ベース)

約 512MB で最大 40 億ユーザーの真偽フラグを保存するのが、Bitmaps です。極めてスペース効率が良いです。Bitmaps を組み合わせるのが、BITOP の AND/OR/XOR/NOT です(複数日でアクティブなユーザーなど)。アクティブユーザーを数えるのが、BITCOUNT です。1 つの文字列へ複数の小さいカウンタをパックするのが、BITFIELD です。位置 = ユーザー ID です。ユースケース:デイリーアクティブユーザー、フィーチャーフラグ。

redis-cli
# bitmaps are strings operated on at the bit level
# great for boolean flags on a large user base

# set bit at position (0 or 1)
SETBIT user:1:active 7 1    # user 1 active
GETBIT user:1:active 7      # 1

# count set bits
BITCOUNT user:1:active      # total bits set to 1

# bitwise operations between strings
SETBIT users:d1 5 1
SETBIT users:d2 5 1
BITOP AND active-both users:d1 users:d2
BITCOUNT active-both        # users active on both days

BITOP OR  active-either users:d1 users:d2
BITOP XOR diff         users:d1 users:d2

# find the first set bit
BITPOS user:1:active 1      # position of first 1-bit

# bitfield: multiple counters in one string
BITFIELD mycnt SET u8 0 100
BITFIELD mycnt INCRBY u8 0 10

文字列の有効期限と TTL

存在しないキーに -2 を、有効期限のないキーに -1 を返すのが、TTL です。アトミックであるのが(SET と EXPIRE の間の競合なし)、EX 付きの SET です。TTL を保ちつつ値を更新できるのが、KEEPTTL(6.0+)です。有効期限の窓をリセットせず、キャッシュ値の更新に有用です。遅延であるのが(アクセス時に確認)、有効期限で、定期的な背景の掃除が加わります。

redis-cli
# set a key with expiration in one atomic command
SET session "data" EX 3600    # 1 hour
SET cache "value" PX 60000    # 60 seconds (ms)

# set expiration on an existing key
EXPIRE mykey 60               # 60 seconds
PEXPIRE mykey 60000           # 60 seconds (ms)
EXPIREAT mykey 1700000000     # Unix timestamp

# view remaining time to live
TTL mykey          # seconds (-1 = no expiry, -2 = no key)
PTTL mykey         # milliseconds

# remove expiration (make key persistent)
PERSIST mykey

# TTL with KEEPTTL option (6.0+): set value, keep existing TTL
SET mykey "newval" KEEPTTL
03

Lists

Push と Pop の操作

両端が、リストです。LPUSH+RPOP = キュー(FIFO)で、LPUSH+LPOP = スタック(LIFO)です。アイテムが利用可能になるまでブロックするのが、BLPOP/BRPOP です。Redis キューの基盤です(ポーリング不要)。切断への対処のため、BLPOP には必ずタイムアウトを設定しましょう。head/tail の操作が O(1) であり、中間アクセスが O(N) であるのが、リストです。

redis-cli
# lists are ordered sequences of strings (linked lists)
LPUSH mylist "a" "b"      # list: [b, a]
RPUSH mylist "c"          # list: [b, a, c]

# pop from head or tail
LPOP mylist               # "b" (removes from head)
RPOP mylist               # "c" (removes from tail)

# pop multiple (6.2+)
LPOP mylist 2             # pop 2 from head

# get length
LLEN mylist               # 0

# blocking pop (waits if empty, up to timeout)
BLPOP queue:tasks 30      # blocks up to 30 seconds
BRPOP queue:tasks 0       # blocks forever

# push only if the list exists (don't create new key)
LPUSHX mylist "x"         # 0 if key doesn't exist

LRANGE とインデックス

リスト全体を返すのが、LRANGE 0 -1 です。中間の要素に対し O(N) であるのが(末端アクセスに最適化されているのが、リストです)、LINDEX です。インデックスによる修正が、LSET です。O(N) であるのが(大きなリストでは控えめに)、LINSERT です。取り除かずに要素の位置を見つけるのが、LPOS です。インデックスによる頻繁なランダムアクセスには、リストが間違った選択であるため — ソート済みセットを検討しましょう。

redis-cli
# get a range of elements (0-based, negative from end)
LRANGE mylist 0 -1        # all elements
LRANGE mylist 0 2         # first 3 elements
LRANGE mylist -3 -1       # last 3 elements

# get element by index (O(N) traversal)
LINDEX mylist 0           # first element
LINDEX mylist -1          # last element

# set an element by index
LSET mylist 1 "newval"

# get length
LLEN mylist

# insert before or after a pivot element
LINSERT mylist BEFORE "pivot" "new"
LINSERT mylist AFTER "pivot" "new"

# find the position of an element (6.0+)
LPOS mylist "value"
LPOS mylist "value" RANK 2   # find 2nd occurrence

ブロッキングポップとキュー

アイテムをソースから宛先へアトミックに移動するのが、BRPOPLPUSH/BLMOVE です。コンシューマが安全に処理でき、クラッシュすれば、アイテムが宛先に残ります(reliable queue のパターン)。BRPOP の後のクラッシュがアイテムを失うため、BRPOP+処理より勝ります。処理後に、宛先のリストから削除しましょう。

redis-cli
# simple FIFO queue: LPUSH to add, RPOP to consume
LPUSH tasks "job1" "job2"
RPOP tasks                # "job1" (FIFO order)

# reliable queue with BRPOP (blocking, waits for work)
BRPOP tasks 0             # blocks until a task is available

# move items between lists atomically
RPOPLPUSH source destination  # move one item

# blocking move (reliable queue pattern)
BRPOPLPUSH source destination 30  # blocks up to 30s

# Redis 6.2+: BLMOVE replaces BRPOPLPUSH
BLMOVE source destination RIGHT LEFT 30

# capped queue (e.g., recent events)
LPUSH recent "event"
LTRIM recent 0 99         # keep latest 100

LREM、LSET、LTRIM

リストサイズに上限を設けるよくあるパターンが、LTRIM です(最新の 100 イベントだけを保つなど)。値により取り除くのが、LREM です(カウント:正 = 先頭、負 = 末尾、0 = すべて)。1 回の呼び出しで複数のリストからポップするのが(優先順位付きキューに有用)、LMPOP(7.0+)です。頻繁なリスト中間の操作には、リストが間違った選択です。

redis-cli
# trim to a range (removes everything outside)
LTRIM mylist 0 99         # keep only first 100 elements
LTRIM mylist -50 -1       # keep only last 50

# remove elements by value
LREM mylist 2 "value"     # remove first 2 occurrences of "value"
LREM mylist -2 "value"    # remove last 2 occurrences
LREM mylist 0 "value"     # remove ALL occurrences

# pop and push in one atomic operation
RPOPLPUSH source dest

# pop from multiple lists (7.0+)
LMPOP 2 mylist1 mylist2 LEFT COUNT 3

# blocking pop from multiple lists (7.0+)
BLMPOP 30 2 mylist1 mylist2 LEFT COUNT 3

# remove a key only if it's a list (type-safe)
DEL mylist                # works on any type

リストのユースケース

末端アクセスのパターンを持つシーケンスに最良なのが、リストです:キュー、スタック、フィード、バッファです。上限付きのログ/フィードに理想的にするのが、LTRIM です。レート制限のためには、タイムスタンプのリスト + LTRIM が、簡単なスライディングウィンドウです。ソート/優先順位付きのキューには、代わりにソート済みセットを。重複除去をリストがサポートしないため — それには、セットを。

redis-cli
# 1. Task queue (FIFO)
LPUSH tasks "process_order:123"
BRPOP tasks 30

# 2. Recent activity feed (capped)
LPUSH user:1:feed "post:99" "post:98"
LTRIM user:1:feed 0 49     # latest 50

# 3. Stack (LIFO)
LPUSH stack "item"
LPOP stack

# 4. Circular buffer (limited size)
LPUSH buffer "new"
LTRIM buffer 0 999         # keep 1000 items

# 5. Rate limiter (sliding window)
LPUSH rate:user:1 1700000000
LTRIM rate:user:1 0 99
LLEN rate:user:1           # request count in window

# 6. Chat history (capped)
LPUSH chat:room:1 "alice: hello"
LTRIM chat:room:1 0 999    # keep last 1000 messages
04

Sets

SADD、SMEMBERS、SISMEMBER

一意の値を保存するのが、セットです。タグ、カテゴリ、重複除去に完璧です。O(1) であるのが、SISMEMBER です。リストの確認よりはるかに速いです。大きなセットでブロックし得るのが、SMEMBERS で、反復には SSCAN を。ラウンドトリップを減らし、メンバーシップをバッチ確認するのが、SMISMEMBER(7.4+)です。すべてのメンバーが整数のとき、intset(ソート済み配列)を使うのが、セットです。非常にメモリ効率が良いです。

redis-cli
# sets: unordered collection of unique strings
SADD tags "redis" "db" "cache"
SADD tags "redis"          # ignored (already exists)

# check membership (O(1))
SISMEMBER tags "redis"     # 1 if member, 0 if not

# get all members (avoid on large sets)
SMEMBERS tags              # 1) "redis" 2) "db" 3) "cache"

# get the number of members
SCARD tags                 # 3

# remove a member
SREM tags "cache"          # 1

# check multiple memberships at once (7.4+)
SMISMEMBER tags "redis" "db" "missing"
# 1) 1  2) 1  3) 0

集合の操作(Union/Inter/Diff)

Redis の超能力が、集合の操作です。クライアント側の処理なしで O(N) の、和集合、積集合、差集合です。ユースケース:共通の友人(SINTER)、一意の訪問者(SUNION)、タグベースのフィルタリング(タグのセットの SINTER)です。メンバーが不要なとき、カウントだけを返すのが(より速い)、SINTERCARD(7.0+)です。再計算を避けるため、結果を保存しましょう。

redis-cli
# set union, intersection, difference
SADD set1 "a" "b" "c"
SADD set2 "b" "c" "d"

# union (all unique members from all sets)
SUNION set1 set2           # a, b, c, d

# intersection (members in ALL sets)
SINTER set1 set2           # b, c

# difference (members in set1 but NOT in set2)
SDIFF set1 set2            # a

# store the result in a new set
SUNIONSTORE result set1 set2
SINTERSTORE result set1 set2
SDIFFSTORE result set1 set2

# count intersection without returning members (7.0+)
SINTERCARD 2 set1 set2 LIMIT 0

# operations on multiple sets at once
SUNION s1 s2 s3 s4

SREM、SMOVE、SPOP

アトミックであるのが、SMOVE です。状態遷移に有用です(ユーザーを「pending」から「active」のセットへ移動するなど)。ランダムなメンバーを取り除くのが(抽選/シャーディングに有用)、SPOP で、取り除かないのが、SRANDMEMBER です。BLPOP のようにブロックするがセット向けなのが(順序が効かないイベント駆動のパターンに有用)、BSPOP(7.0+)です。実際に取り除かれた数を返すのが、SREM です。

redis-cli
# remove one or more members
SADD myset "a" "b" "c" "d"
SREM myset "a" "b"         # 2 (number removed)

# move a member from one set to another atomically
SMOVE source dest "member"

# pop a random member (removes it)
SPOP myset                 # removes and returns one
SPOP myset 3               # removes and returns 3 (6.2+)

# get a random member (does NOT remove)
SRANDMEMBER myset          # one random member
SRANDMEMBER myset 3        # 3 random (may repeat)
SRANDMEMBER myset -3       # 3 unique random

# blocking set pop (7.0+) - waits until a member exists
BSPOP myset 30             # blocks up to 30 seconds

# delete the entire set
DEL myset

SSCAN の反復

大きなセットを反復する安全な方法が、SSCAN です。巨大なセットで SMEMBERS がサーバーをブロックします。カーソルベースなのが、SSCAN です。カーソルが 0 に戻るまで繰り返し呼びましょう。ヒントであるのが、COUNT です(多くも少なくも返し得ます)。弱い保証を提供するのが、SSCAN です。反復中に加えられたメンバーを重複返したり見逃したりし得ますが、決してブロックしません。コード内でカーソルのループを必ず処理しましょう。

redis-cli
# SSCAN: cursor-based iteration for large sets
SSCAN myset 0 MATCH "pre*" COUNT 100
# returns: [nextCursor, [member1, member2, ...]]

# continue until cursor returns to 0
SSCAN myset <nextCursor> MATCH "pre*" COUNT 100

# iterate all members safely
cursor=0
while true:
  cursor, members = SSCAN myset cursor COUNT 100
  process(members)
  if cursor == 0: break

# scan with type filtering (7.0+ for SCAN, sets always same type)
# COUNT is a hint, not exact (may return more or fewer)

# MATCH pattern supports glob: *, ?, [abc]
SSCAN myset 0 MATCH "user:*" COUNT 1000

# for small sets, SMEMBERS is fine
# for large sets (>10k), always use SSCAN

セットのユースケース

一意性と関係性の頼みの綱が、セットです。相互のフォロワー/友人のための SINTER のパターンが、クラシックです。巨大なカーディナリティの「1 日の訪問者」のためには、HyperLogLog を検討しましょう(近似的だが、固定の 12KB です)。順序付きの一意データ(リーダーボード)には、ソート済みセットを。順序なしであるのが、セットです。順序が効くなら、リストかソート済みセットを使いましょう。

redis-cli
# 1. Tags / categories
SADD post:1:tags "redis" "db"
SADD post:2:tags "redis" "cache"
SINTER post:1:tags post:2:tags   # posts sharing "redis"

# 2. Unique visitors per day
SADD visitors:2025-01-01 "user:1" "user:2"
SCARD visitors:2025-01-01        # visitor count

# 3. Followers / following (mutual friends)
SADD user:1:following "user:2" "user:3"
SADD user:2:following "user:1" "user:3"
SINTER user:1:following user:2:following  # mutual follows

# 4. Blacklist / whitelist
SADD blacklist "ip:1.2.3.4"
SISMEMBER blacklist "ip:1.2.3.4"   # 1 = blocked

# 5. Lottery / random selection
SADD participants "u1" "u2" "u3" "u4"
SPOP participants 1        # draw a winner
05

Sorted Sets

ZADD、ZSCORE、ZRANK

Redis の最も強力な構造が、ソート済みセット(zsets)です。スコアで順序付けられた一意のメンバーで、O(log N) の操作です。条件付きの更新を可能にするのが、ZADD のオプション(NX/XX/GT/LT)です。新しいスコアがより大きいときだけ更新するのが(「最良スコア」の追跡に最適)、GT です。double であるのが、スコアで、一意なのが、メンバーです。辞書式に破られるのが、同点です。

redis-cli
# sorted set: unique members ordered by a float score
ZADD leaderboard 100 "alice" 200 "bob" 150 "carol"

# update a score (re-add with new score)
ZADD leaderboard 250 "alice"   # alice's score becomes 250

# add with options (NX: only new, XX: only existing, GT/LT)
ZADD leaderboard NX 300 "new"        # only if new
ZADD leaderboard GT 300 "alice"      # only if new score > current
ZADD leaderboard LT 50 "alice"       # only if new score < current

# get a member's score
ZSCORE leaderboard "alice"      # "250"

# get a member's rank (0-based, ascending)
ZRANK leaderboard "alice"       # rank from lowest
ZREVRANK leaderboard "alice"    # rank from highest (0 = top)

# get the number of members
ZCARD leaderboard               # 3

# get multiple scores at once (6.2+)
ZMSCORE leaderboard "alice" "bob"  # ["250", "200"]

ZRANGE と ZREVRANGE

ランク(インデックス)により返すのが、ZRANGE で、BYSCORE によりスコア範囲で返します。ZRANGEBYSCORE/ZREVRANGE を、BYSCORE/BYLEX/REV のオプション付きの ZRANGE へ統一したのが、Redis 6.2 です。出力にスコアを含めるのが、WITHSCORES です。リーダーボードのためには、トップ 10 が、ZRANGE 0 9 REV です。後の処理のために、結果を新しいキーへ保存するのが、ZRANGESTORE(6.2+)です。

redis-cli
# get members by index range (ascending)
ZRANGE leaderboard 0 -1              # all, ascending
ZRANGE leaderboard 0 2               # first 3 (lowest scores)
ZRANGE leaderboard -3 -1             # last 3 (highest scores)

# descending order
ZREVRANGE leaderboard 0 2            # top 3 (highest scores)

# with scores
ZRANGE leaderboard 0 -1 WITHSCORES

# Redis 6.2+: unified ZRANGE with BYSCORE/REV options
ZRANGE leaderboard 100 200 BYSCORE
ZRANGE leaderboard 200 100 BYSCORE REV

# store a range in a new key (6.2+)
ZRANGESTORE top3 leaderboard 0 2 REV

# get by rank with scores
ZRANGE leaderboard 0 9 REV WITHSCORES  # top 10

# limit results (pagination)
ZRANGE leaderboard 0 -1 BYSCORE LIMIT 0 10

ZRANGEBYSCORE と ZCOUNT

スコア範囲により返すのが、ZRANGEBYSCORE です。スコアを排他的にするのが、「(」の接頭辞です。メンバーを取得せず、範囲内のカウントを与えるのが、ZCOUNT です。アトミックにスコアを調整し再ソートするのが、ZINCRBY です。ライブのリーダーボードに完璧です。zset に上限を設けるのに(トップ 1000 だけを保つなど)、素晴らしいのが、ZREMRANGEBYRANK です。

redis-cli
# get members by score range
ZRANGEBYSCORE leaderboard 100 200    # scores 100-200
ZRANGEBYSCORE leaderboard 100 +inf   # scores >= 100
ZRANGEBYSCORE leaderboard -inf 200   # scores <= 200
ZRANGEBYSCORE leaderboard (100 200   # scores > 100 (exclusive)

# with pagination
ZRANGEBYSCORE leaderboard 100 200 LIMIT 0 10

# count members in a score range
ZCOUNT leaderboard 100 200

# increment a member's score atomically
ZINCRBY leaderboard 50 "alice"     # alice += 50

# remove a member
ZREM leaderboard "bob"

# remove by rank range
ZREMRANGEBYRANK leaderboard 0 9    # remove lowest 10
ZREMRANGEBYSCORE leaderboard 0 100 # remove scores <= 100

ZUNIONSTORE と ZINTERSTORE

設定可能な集約(SUM/MIN/MAX)と重み付きで、zsets を組み合わせるのが、ZUNIONSTORE/ZINTERSTORE です。加重スコアリングに強力です(関連度 = text_match*2 + recency*1 など)。保存せず結果を返すのが、Redis 6.2 が加えた、ZUNION/ZINTER/ZDIFF です(コマンドが 1 つ減ります)。O(N*M) であるため — 多くの大きなセットには注意しましょう。セット名の前に、セット数が来なければなりません。

redis-cli
# combine multiple sorted sets
ZADD set1 1 "a" 2 "b"
ZADD set2 2 "a" 3 "c"

# union: sum scores by default (a = 1+2 = 3)
ZUNIONSTORE result 2 set1 set2
ZRANGE result 0 -1 WITHSCORES   # a=3, b=2, c=3

# specify aggregation: SUM (default), MIN, MAX
ZUNIONSTORE result 2 set1 set2 AGGREGATE MAX   # a=2, b=2, c=3

# apply weights to each set's scores
ZUNIONSTORE result 2 set1 set2 WEIGHTS 2 1     # set1 scores * 2

# intersection (only members in ALL sets)
ZINTERSTORE result 2 set1 set2                 # only "a"

# Redis 6.2+: return without storing
ZUNION 2 set1 set2 WITHSCORES
ZINTER 2 set1 set2 WITHSCORES
ZDIFF 2 set1 set2 WITHSCORES

# count intersection (7.0+)
ZINTERCARD 2 set1 set2 LIMIT 0

辞書式の範囲(BYLEX)

スコアが等しいとき、メンバー上のレンジクエリを可能にするのが、BYLEX です。ソート済みセットを、自動ソートされる文字列のインデックスへ変えます。ユースケース:オートコンプリート(スコア 0 で単語を保存し、接頭辞の範囲をクエリする)、ソートされた辞書です。含むのが「[a」で、排他的なのが「(a」、開始が「-」、終了が「+」です。すべてのスコアが同一のときにのみ、意味を持つのが、これです。

redis-cli
# when all scores are equal, sorted sets act as a sorted string set
ZADD myset 0 "apple" 0 "banana" 0 "cherry" 0 "date"

# range by lexicographical order
ZRANGEBYLEX myset "[a" "[c"        # apple, banana, cherry
ZRANGEBYLEX myset "(a" "[c"        # banana, cherry (a exclusive)
ZRANGEBYLEX myset "-" "[b"         # from start to banana
ZRANGEBYLEX myset "[c" "+"         # cherry to end

# count in a lex range
ZLEXCOUNT myset "[a" "[c"          # 3

# remove by lex range
ZREMRANGEBYLEX myset "[a" "[b"

# Redis 6.2+: use ZRANGE with BYLEX
ZRANGE myset "[a" "[c" BYLEX

# limit results (pagination)
ZRANGEBYLEX myset "[a" "[c" LIMIT 0 10

リーダーボードのパターン

リーダーボードを自明にするのが、ソート済みセットです。スコアを更新するのが、ZADD、トップ N が、ZREVRANGE、プレイヤーの順位が、ZREVRANK です。アトミックにスコアを更新するのが、ZINCRBY です。時間バケットのリーダーボード(日次/週次)のためには、TTL 付きの期間ごとのキーを使いましょう。オフセット付きの ZREVRANGE が、ページネーションに使われます。Redis の最も自然で強力なユースケースの一つが、これです。

redis-cli
# build a leaderboard
ZADD leaderboard 100 "alice" 250 "bob" 150 "carol"

# top 10 players (highest scores)
ZREVRANGE leaderboard 0 9 WITHSCORES

# a player's rank (0 = top)
ZREVRANK leaderboard "alice"

# update a score (atomic)
ZINCRBY leaderboard 50 "alice"

# players within a score range (e.g., silver tier 100-199)
ZRANGEBYSCORE leaderboard 100 199

# percentile rank
total = ZCARD(leaderboard)
rank = ZREVRANK(leaderboard "alice")
# percentile = (total - rank) / total * 100

# pagination (page 3, 10 per page)
ZREVRANGE leaderboard 20 29 WITHSCORES

# time-bucketed leaderboards (weekly)
ZADD leaderboard:2025-W01 100 "alice"
EXPIRE leaderboard:2025-W01 604800   # 1 week TTL
06

Hashes

HSET、HGET、HGETALL

オブジェクトの保存に理想的なのが、ハッシュです。オブジェクトごとに 1 キー、プロパティごとにフィールドです。これが JSON のシリアライズに勝る理由は、read-modify-write なしで、(HSET により)個々のフィールドをアトミックに更新できるからです。すべてのフィールドを返すのが、HGETALL で、大きなハッシュには HSCAN を推奨しましょう。小さいとき(約 128 フィールド未満)に listpack のエンコーディングを使うのが、ハッシュです。メモリ効率が良いです。

redis-cli
# a hash maps fields to values (like a small object)
HSET user:1 name "Alice" age 30 email "[email protected]"

# get a single field
HGET user:1 name            # "Alice"

# get all fields and values
HGETALL user:1
# 1) "name"   -> "Alice"
# 2) "age"    -> "30"
# 3) "email"  -> "[email protected]"

# get the number of fields
HLEN user:1                 # 3

# get the string length of a field's value
HSTRLEN user:1 name          # 5 (length of "Alice")

# set a field only if it doesn't exist
HSETNX user:1 status "new"   # 1 if set, 0 if existed

# delete a field
HDEL user:1 email            # removes the email field

HMGET(マルチフィールドの取得)

1 ラウンドトリップで複数のフィールドをバッチ取得するのが、HMGET です。別々の HGET 呼び出しよりはるかに速いです。複数のフィールド・バリューのペアを受け付けるのが、HSET(4.0 以降)で、HMSET が非推奨になります。すべてのフィールド名/値を返すのが、HKEYS/HVALS です。サンプリングに有用なのが(ランダムなフィーチャーフラグなど)、HRANDFIELD(6.2+)です。大きなハッシュでブロックするのが、HGETALL です。本番の反復には HSCAN を。

redis-cli
# get multiple fields at once
HMGET user:1 name age       # 1) "Alice" 2) "30"
HMGET user:1 name missing age  # 1) "Alice" 2) nil 3) "30"

# set multiple fields (HSET supports multiple field-value pairs)
HSET user:1 name "Bob" age 25 email "[email protected]"

# HMSET is deprecated (use HSET with multiple fields)
# HMSET still works but returns OK instead of count

# get all field names
HKEYS user:1                # 1) "name" 2) "age" 3) "email"

# get all values
HVALS user:1                # 1) "Alice" 2) "30" 3) "[email protected]"

# check if a field exists
HEXISTS user:1 name          # 1 if exists, 0 if not

# get a random field (6.2+)
HRANDFIELD user:1            # one random field name
HRANDFIELD user:1 3 WITHVALUES  # 3 random fields + values

HINCRBY(数値フィールド)

ハッシュのフィールド上の HINCRBY がアトミックであるため、ユーザーごとのカウンタ(ログイン数、閲覧数、カートの数量)に完璧です。小数に対応するのが、HINCRBYFLOAT です。最後のフィールドが取り除かれると、ハッシュが自動削除されます(HDEL)。これにより、数値のカウンタを持つオブジェクトのための理想的な構造が、ハッシュになります。カウンタごとの別々の文字列キーより、はるかに効率的です。

redis-cli
# increment a numeric field atomically
HSET user:1:stats logins 0
HINCRBY user:1:stats logins 1    # logins = 1
HINCRBY user:1:stats logins 1    # logins = 2
HINCRBY user:1:stats logins -1   # logins = 1

# increment by a specific amount
HINCRBY user:1:stats page_views 10

# floating point increment
HINCRBYFLOAT user:1:stats score 0.5

# all HINCRBY operations are atomic
# perfect for per-user/per-object counters

# use case: shopping cart (product_id -> quantity)
HSET cart:user:1 product:100 2
HINCRBY cart:user:1 product:100 1   # now 3
HINCRBY cart:user:1 product:100 -1  # now 2
HDEL cart:user:1 product:100        # remove item

HSCAN(ハッシュの反復)

大きなハッシュでサーバーをブロックするのが、HGETALL です。本番の反復には、HSCAN を使いましょう。カーソルベースなのが、HSCAN です。カーソルが 0 に戻るまで繰り返し呼びましょう。ヒントであるのが、COUNT です。フラットな [field, value, field, value, ...] の配列として来るのが、結果です。コード内でペアにしましょう。何百万ものフィールドを持つハッシュには、複数のキーへのシャーディングを検討しましょう。

redis-cli
# HSCAN: cursor-based iteration (for large hashes)
HSCAN user:1 0 MATCH "na*" COUNT 10
# returns [cursor, [field, value, field, value, ...]]

# iterate all fields safely
cursor=0
while true:
  cursor, fields = HSCAN user:1 cursor COUNT 100
  process(fields)
  if cursor == 0: break

# HGETALL is fine for small hashes (< 100 fields)
# HSCAN is required for large hashes to avoid blocking

# match field names with glob patterns
HSCAN user:1 0 MATCH "user:*" COUNT 1000

# no VALUES-only option; results are [field, value, field, value, ...]
# pair them up in your code

# COUNT is a hint — may return more or fewer than requested

# HSCAN never blocks; safe for production use

ハッシュのユースケース

オブジェクトとグループ化されたカウンタで輝くのが、ハッシュです。強力なメモリの技法:多くの小さい文字列のキーがあるとき、それらを 1 つのハッシュへグループ化しましょう。数千の個別のキー(それぞれがメタデータ付き)より、listpack のエンコーディングが、はるかに少ないオーバーヘッドを使います。この「キーのバケット化」が、小さい値のために、メモリ使用量を 5〜10 倍切り詰め得ます。重大な追加が、(7.4+ の)フィールドレベルの TTL です。

redis-cli
# 1. Store an object (user profile, config)
HSET config:app name "MyApp" version "2.0" debug "off"

# 2. Per-user counters
HINCRBY user:1:stats logins 1
HINCRBY user:1:stats page_views 1
HGET user:1:stats logins

# 3. Shopping cart (product_id -> quantity)
HSET cart:user:1 product:100 2
HINCRBY cart:user:1 product:100 1
HDEL cart:user:1 product:100

# 4. Feature flags
HSET feature_flags user:1 new_ui 1 beta 0
HGET feature_flags user:1 new_ui   # 1

# 5. Session store with TTL
HSET session:abc user_id 1 data "..."
EXPIRE session:abc 1800   # 30 min

# 6. Hash field expiration (Redis 7.4+)
HEXPIRE user:1 60 FIELDS 1 session_token
HPTTL user:1 FIELDS 1 session_token
07

キーの管理

EXISTS、TYPE、DEL

既存のもののカウントを返すのが、複数キー付きの EXISTS です。データ構造のタイプを返すのが、TYPE です。WRONGTYPE のエラーを避けるため、操作の前に必ず確認しましょう(キーのタイプが、その生涯で不変です)。ブロックであり、大きな構造上でサーバーを止め得るのが、DEL です。大きいキーには UNLINK を推奨しましょう。存在しないキーに「none」を返すのが、TYPE です。

redis-cli
# check if a key exists
SET mykey "hello"
EXISTS mykey             # 1
EXISTS missing           # 0
EXISTS key1 key2 key3    # count of existing keys (multiple)

# get the type of a value
TYPE mykey               # "string"
TYPE mylist              # "list"
TYPE missing             # "none"

# delete one or more keys
DEL mykey                # 1 if deleted, 0 if not
DEL key1 key2 key3       # number of keys deleted

# delete is blocking for large keys — use UNLINK instead
# UNLINK deletes in a background thread

# check type before operating to avoid WRONGTYPE errors
TYPE mykey
# returns: string | list | hash | set | zset | stream | none

UNLINK(非同期削除)

大きいキーのための DEL のノンブロッキングな代替が、UNLINK(4.0+)です。キーを即座にキースペースから取り除きますが、背景のスレッドでメモリを解放するため、サーバーの停止を防ぎます。何百万もの要素を持つキーには、UNLINK を必ず使いましょう。一括削除のために同じことをするのが、FLUSHDB ASYNC / FLUSHALL ASYNC です。実際の解放を扱うのが、lazyfree のスレッドプールです。

redis-cli
# UNLINK: non-blocking delete (large keys)
UNLINK biglist bighash   # returns count of deleted keys

# UNLINK removes the key from the keyspace immediately
# but frees the memory in a background thread

# compare:
DEL biglist              # blocks until fully freed
UNLINK biglist           # returns immediately, frees later

# for small keys, DEL and UNLINK are equivalent
# for large keys (millions of elements), UNLINK is essential

# flush database asynchronously (non-blocking)
FLUSHDB ASYNC
FLUSHALL ASYNC

# check what's being freed in background
INFO memory | grep lazyfree

RENAME と RENAMENX

キーをアトミックに新しい名前へ動かすのが、既存の宛先キー(とその値)を上書きする、RENAME です。宛先が存在しない場合にだけ改名するのが(うっかりの上書きを防ぐ)、RENAMENX(6.2+)です。改名で TTL が保たれます。アトミックなのが、RENAME です。他のクライアントが中間の状態を見られません。データベースをまたぐ改名はサポートされず、MOVE か DUMP/RESTORE を使うしましょう。

redis-cli
# rename a key (overwrites destination if it exists)
SET oldkey "value"
RENAME oldkey newkey     # OK; oldkey is gone, newkey has "value"

# rename only if destination doesn't exist (6.2+)
RENAMENX oldkey newkey   # 1 if renamed, 0 if newkey already exists

# rename preserves the type and TTL
SET tempkey "data" EX 3600
RENAME tempkey permkey   # permkey now has TTL of ~3600s
TTL permkey              # ~3600

# rename across databases is not supported
# use MOVE + RENAME, or DUMP/RESTORE for cross-db moves

# type is immutable — rename keeps the type
TYPE permkey             # "string"

# renaming is atomic

KEYS 対 SCAN

キースペース全体をスキャンする間、サーバーをブロックするのが、KEYS です。大きな dataset での本番では NEVER で使いましょう。本番セーフな代替が、SCAN です。カーソルベースで、ノンブロッキングで、0 までたどるカーソルを返します。反復中に加えられたキーを重複返したり見逃したりし得ますが、決してブロックしません。ヒントであるのが、COUNT です(多くも少なくも返し得ます)。コード内でカーソルのループを必ず処理しましょう。

redis-cli
# KEYS: blocks the server while scanning — NEVER in production
KEYS *                   # all keys (DANGEROUS on large DBs)
KEYS user:*              # keys matching pattern
KEYS session:*

# SCAN: cursor-based iteration (non-blocking, production-safe)
SCAN 0 MATCH user:* COUNT 100
# returns: [nextCursor, [key1, key2, ...]]

# continue until cursor returns to 0
SCAN <nextCursor> MATCH user:* COUNT 100

# scan by type (7.0+)
SCAN 0 TYPE hash
SCAN 0 MATCH user:* TYPE string COUNT 100

# SCAN is weakly consistent:
# - may return duplicates
# - may miss keys added during iteration
# - but NEVER blocks the server

# COUNT is a hint, not exact

RANDOMKEY と DBSIZE

取り除かずにランダムなキーを返すのが(サンプリングに有用)、RANDOMKEY です。現在のデータベースの正確なキー数を返すのが(O(1))、DBSIZE です。有効期限の統計(keys、expires、avg_ttl)付きで、データベースごとのカウントを示すのが、INFO keyspace です。特定のタイプのランダムなキーのための組み込みコマンドはなく — ループ内で SCAN + TYPE を使いましょう。

redis-cli
# get a random key (O(1), does not remove)
RANDOMKEY                # "user:1" or nil if db is empty

# get the number of keys in the current database
DBSIZE                   # 1234

# count keys across all databases (in a cluster)
# note: DBSIZE only counts the current db
SELECT 0; DBSIZE
SELECT 1; DBSIZE

# get keyspace info (keys per db with expiry info)
INFO keyspace
# db0:keys=1000,expires=500,avg_ttl=3600000
# db1:keys=50,expires=10,avg_ttl=60000

# scan with count for approximate size estimation
SCAN 0 COUNT 1           # get cursor + small sample

# find a random key of a specific type
# (no built-in; use SCAN + TYPE in a loop)

OBJECT のコマンド

(メモリのデバッグのために)内部の表現を明らかにするのが、OBJECT ENCODING です。コールドキー(追い出しの候補)を見つけるのが、OBJECT IDLETIME です。maxmemory-policy が LFU のときだけ機能するのが、OBJECT FREQ です。正確に数えるのが、SAMPLES 0 付きの MEMORY USAGE です(大きなコレクションでは、デフォルトでサンプリングします)。構造化されたドキュメントを返すのが、COMMAND DOCS(7.0+)です。メモリの肥大のデバッグに、これらの内省ツールが役立ちます。

redis-cli
# OBJECT subcommands for introspection
OBJECT ENCODING mykey     # internal encoding (embstr, raw, int, listpack, etc.)
OBJECT REFCOUNT mykey     # reference count
OBJECT IDLETIME mykey     # seconds since last access
OBJECT FREQ mykey         # access frequency (LFU mode only)

# check memory usage of a key (bytes)
MEMORY USAGE mykey
MEMORY USAGE mykey SAMPLES 0   # exact count (slower for large keys)

# total memory used by the server
INFO memory | grep used_memory_human

# inspect a key's internal structure (debugging, can be slow)
DEBUG OBJECT mykey        # raw internal info

# the encoding changes automatically as the structure grows
# e.g., hash: listpack -> hashtable when fields exceed threshold

# help understand a command
COMMAND INFO GET
COMMAND DOCS SET          # structured docs (7.0+)
08

有効期限と永続化

EXPIRE と EXPIREAT

既存のキーに TTL を設定するのが、EXPIRE で、(推奨される)アトミックにやるのが、EX/PX/EXAT/PXAT 付きの SET です。条件付きの TTL 設定を可能にするのが、NX/GT/LT のオプション(7.0+)です。「期限がない場合だけ加える」や「延びるだけ、短くはしない」に有用です。有効期限のないキーに -1 を、存在しないキーに -2 を返すのが、TTL です。遅延であるのが(アクセス時に確認)、有効期限で、定期的な背景の掃除が加わります。

redis-cli
# set expiration on an existing key (seconds)
SET mykey "value"
EXPIRE mykey 60              # expires in 60 seconds
EXPIRE mykey 60 NX           # only set TTL if none exists (7.0+)
EXPIRE mykey 60 GT           # only set if new TTL > current (7.0+)
EXPIRE mykey 60 LT           # only set if new TTL < current (7.0+)

# set expiration in milliseconds
PEXPIRE mykey 60000

# set expiration at a Unix timestamp
EXPIREAT mykey 1700000000       # seconds
PEXPIREAT mykey 1700000000000    # milliseconds

# set value AND expiration atomically (preferred)
SET token "abc" EX 3600
SET token "abc" PX 3600000
SET token "abc" EXAT 1700000000

# get remaining TTL
TTL mykey          # seconds (-1 = no expiry, -2 = no key)
PTTL mykey         # milliseconds

PERSIST(TTL の除去)

TTL を取り除き、キーを永続化させるのが(値が残ります)、PERSIST です。アトミックに値を返し TTL を設定・取り除くのが、GETEX(6.2+)です。読み取り時のセッションの有効期限の更新(GETEX key EX 3600)や、一時的なキーの永続化(GETEX key PERSIST)に有用です。GET+SET の競合なしで、(省略可能にデータベースをまたぐ)キーをコピーするのが、COPY(6.2+)です。

redis-cli
# remove expiration (make key persistent)
SET session "data" EX 3600
TTL session               # 3600
PERSIST session           # 1 (success)
TTL session               # -1 (no expiry)

# PERSIST returns 1 if the TTL was removed, 0 if key had no TTL or doesn't exist

# copy a key with optional TTL handling (6.2+)
COPY source dest               # copy without TTL
COPY source dest REPLACE       # overwrite destination
COPY source dest DB 1          # copy to another database

# GETEX: get value and optionally set/remove TTL (6.2+)
GETEX mykey EX 3600       # returns value, sets 3600s TTL
GETEX mykey PERSIST       # returns value, removes TTL

# note: PERSIST only removes TTL; the key and value remain

SAVE と BGSAVE(RDB)

スナップショットが完了するまでサーバーをブロックするのが、SAVE です。本番では決して使わないこと。メインスレッドがブロックされないよう、プロセスを fork するのが(コピーオンライト)、BGSAVE ですが、fork の間、大きな dataset がメモリのスパイクを引き起こし得ます。変化率に基づき自動スナップショットをトリガーするのが、「save」のルールです。コンパクトでありバックアップに理想的なのが、RDB ですが、最後のスナップショットの後に書かれたデータを失うリスクがあります。

redis-cli
# SAVE: synchronous snapshot (BLOCKS the server until done)
SAVE                     # blocks — use only in maintenance windows

# BGSAVE: background snapshot (non-blocking, forks a child)
BGSAVE                   # returns immediately, saves in background
LASTSAVE                 # Unix timestamp of the last successful save

# check if a BGSAVE is in progress
INFO persistence | grep rdb_bgsave_in_progress

# configure automatic snapshots in redis.conf:
#   save 3600 1     # save if >= 1 key changed in 3600s
#   save 300 100    # save if >= 100 keys changed in 300s
#   save 60 10000   # save if >= 10000 keys changed in 60s
#   save ""         # disable RDB entirely

# RDB file location
CONFIG GET dbfilename    # "dump.rdb"
CONFIG GET dir           # "/var/lib/redis"

# RDB pros: compact, fast restart, great for backups
# RDB cons: potential data loss between snapshots

BGREWRITEAOF(AOF のコンパクション)

すべての書き込みコマンドをログへ追記するのが、AOF です。RDB よりはるかに耐久性があります(everysec で最大 1 秒のデータ喪失です)。すべての書き込みで fsync するのが(非常に遅く、クリティカルなデータだけに)、always です。ログをコンパクションするのが(最小のコマンドのセットとして書き直す)、BGREWRITEAOF です。マルチパートの AOF 形式を使うのが(ベース RDB + 段階的なログ)、Redis 7 で、パーツを保持するのが、appenddirname です。

redis-cli
# AOF: logs every write command (durable, replayable)
# enable in redis.conf:
#   appendonly yes
#   appendfilename "appendonly.aof"

# fsync policies:
#   appendfsync always    # fsync every write (safest, slowest)
#   appendfsync everysec  # fsync once per second (default, balanced)
#   appendfsync no        # let OS decide (fastest, risk of data loss)

# trigger AOF rewrite (compacts the log)
BGREWRITEAOF             # non-blocking, rewrites in background

# AOF auto-rewrite thresholds:
#   auto-aof-rewrite-percentage 100
#   auto-aof-rewrite-min-size 64mb

# check AOF status
INFO persistence | grep aof

# AOF pros: minimal data loss (1 sec max with everysec)
# AOF cons: larger files, slower load on restart

# Redis 7: multi-part AOF (base + incremental files)
CONFIG GET appenddirname   # "appendonlydir"

永続化の設定

再起動なしで実行時に設定を変えるのが、CONFIG SET で、redis.conf へ永続化するのが、CONFIG REWRITE です。推奨される本番のセットアップが、RDB + AOF のハイブリッドです。速い再起動とバックアップのために RDB を、最小のデータ喪失のために AOF を。Redis 7 以降、AOF が、段階的なコマンドが続く RDB のベーススナップショットで始まるため — 耐久性と、速いロードを組み合わせます。

redis-cli
# view current persistence settings
CONFIG GET save
CONFIG GET appendonly
CONFIG GET appendfsync
CONFIG GET dir
CONFIG GET dbfilename
CONFIG GET appendfilename

# enable AOF at runtime
CONFIG SET appendonly yes

# change fsync policy at runtime
CONFIG SET appendfsync everysec

# disable RDB snapshots
CONFIG SET save ""

# persist config changes to redis.conf
CONFIG REWRITE

# hybrid persistence (recommended):
# RDB for fast restart + AOF for durability
# redis.conf:
#   save 3600 1
#   appendonly yes
#   aof-use-rdb-preamble yes   # RDB header in AOF (faster load)

# check persistence status
INFO persistence

バックアップとリストア

RDB ファイルを定期的にバックアップしましょう(コンパクトで速い)。Redis が動いている間でも(コピーオンライト)、一貫したスナップショットです。AOF のためには、appendonly のディレクトリ全体をバックアップしましょう(Redis 7 のマルチパート)。Redis を停止し、ファイルを置き換え、再起動することで、リストアします。悪いコマンドからの回復には、再起動前に AOF を編集してそれを取り除きましょう。ファイルシステムに直接触れずにオンラインバックアップを行うのが、redis-cli --rdb です。

redis-cli
# backup: copy the RDB file while Redis runs
BGSAVE
# wait for LASTSAVE to update, then copy the file
cp /var/lib/redis/dump.rdb /backup/dump-$(date +%F).rdb

# AOF backup: copy the AOF manifest + files (Redis 7)
cp -r /var/lib/redis/appendonlydir /backup/

# restore: stop Redis, replace data files, restart
redis-cli SHUTDOWN
cp /backup/dump.rdb /var/lib/redis/dump.rdb
redis-server /etc/redis/redis.conf

# for point-in-time recovery from AOF:
# edit the AOF file to remove unwanted commands, then restart

# RDB file analysis (offline, safe)
redis-check-rdb /var/lib/redis/dump.rdb
redis-check-aof /var/lib/redis/appendonly.aof

# fix a truncated AOF
redis-check-aof --fix /var/lib/redis/appendonly.aof

# online backup with --rdb (dumps RDB to stdout/file)
redis-cli --rdb /backup/dump.rdb
09

Pub/Sub

SUBSCRIBE と UNSUBSCRIBE

1 つ以上のチャンネルからメッセージを受け取るため、クライアントをブロックするのが、SUBSCRIBE です。SUBSCRIBE/UNSUBSCRIBE/PSUBSCRIBE/PUNSUBSCRIBE/PING/QUIT しか呼べないのが、購読したクライアントです — 他のコマンドは不可です。pub/sub の状態(アクティブなチャンネル、購読者数)を内省するのが、PUBSUB です。発火後放置です:リスナーの購読者がいなければ、メッセージが失われます。信頼できる配信のためには、Streams を。

redis-cli
# subscribe to channels (in one client, blocks)
SUBSCRIBE news alerts

# the client now listens for messages:
# 1) "subscribe" 2) "news" 3) 1
# 1) "subscribe" 2) "alerts" 3) 2

# unsubscribe from specific channels
UNSUBSCRIBE news
UNSUBSCRIBE news alerts

# unsubscribe from ALL channels
UNSUBSCRIBE

# note: published messages are NOT persisted
# if no subscriber is listening, the message is lost
# for persistent messaging, use Streams instead

# count active subscriptions (in another client)
PUBSUB CHANNELS           # list active channels
PUBSUB NUMSUB news        # subscriber count for "news"

PUBLISH

メッセージを受け取った購読者の数を返すのが(なければ 0)、PUBLISH です。公開後にメッセージを取得する方法はなく — リスナーの購読者がいなければ、消えます。少なくとも 1 つの購読者がいるアクティブなチャンネルを列挙するのが、PUBSUB CHANNELS で、購読者数を返すのが、PUBSUB NUMSUB です。信頼できリプレイ可能なメッセージングのためには、Streams(XADD/XREAD)を。

redis-cli
# publish a message to a channel (from another client)
PUBLISH news "Breaking: Redis 7.4 released"
# returns: number of subscribers that received the message

# publish to a channel with no subscribers
PUBLISH empty "hello"
# returns: 0 (message is lost)

# publish to multiple channels (separate PUBLISH calls)
PUBLISH news "msg1"
PUBLISH alerts "msg2"

# pub/sub has no persistence, no replay, no consumer groups
# subscribers must be connected to receive messages

# check how many clients are listening
PUBSUB NUMSUB news
PUBSUB NUMSUB news alerts    # multiple channels

# list active channels (with pattern)
PUBSUB CHANNELS              # all active channels
PUBSUB CHANNELS news:*       # channels matching pattern

PSUBSCRIBE(パターン購読)

glob パターンに一致するチャンネルを購読するのが、PSUBSCRIBE です。イベントルーティングに強力です(例:user:*:login が、すべてのユーザーログインイベントを捉えます)。直接の購読とパターンの両方に一致するメッセージが、2 回配信されます。パターン、チャンネル、メッセージ付きの「pmessage」イベントを受け取るのが、パターンの購読者です。パターン購読の取り消しは、PUNSUBSCRIBE です。

redis-cli
# subscribe to channels matching a glob pattern
PSUBSCRIBE news.*
PSUBSCRIBE user:*:login
PSUBSCRIBE events:*

# patterns use glob syntax:
#   *    matches any sequence
#   ?    matches one character
#   [ab] matches 'a' or 'b'

# unsubscribe from patterns
PUNSUBSCRIBE news.*
PUNSUBSCRIBE               # unsubscribe from ALL patterns

# a message matching both a direct subscription and a pattern
# is delivered twice (once for each)

# pattern subscribers receive:
# 1) "pmessage" 2) "news.*" 3) "news.tech" 4) "the message"

# use case: event routing
PSUBSCRIBE user:*:login       # all user logins
PSUBSCRIBE order:*:created    # all order creations
PSUBSCRIBE cache:*:invalidate # cache invalidation events

Sharded Pub/Sub(7.0+)

Cluster モードの問題を解決するのが、Sharded Pub/Sub(7.0+)です。通常の Pub/Sub がすべてのクラスタノードへすべての PUBLISH をブロードキャストし、帯域を浪費します。チャンネルキーを所有するシャードへだけメッセージをルートするのが、Sharded Pub/Sub です。大きなクラスタではるかに効率的です。Cluster のデプロイでは、SSUBSCRIBE/SPUBLISH を使いましょう。シャードを決めるのが(キーのように)、チャンネル名です。

redis-cli
# regular Pub/Sub broadcasts to ALL cluster nodes (expensive)
# sharded Pub/Sub routes messages only to the shard owning the channel

# subscribe to a shard channel
SSUBSCRIBE mychannel

# publish to a shard channel
SPUBLISH mychannel "hello"

# sharded pub/sub uses the channel name for shard routing
# so messages only travel within one shard (more efficient)

# use sharded pub/sub in a Redis Cluster to avoid
# broadcasting messages to every node

# regular SUBSCRIBE/PUBLISH still work in cluster mode
# but they broadcast to all shards (cluster-wide overhead)

# check shard channel subscribers (7.0+)
PUBSUB SHARDCHANNELS
PUBSUB SHARDNUMSUB mychannel

キースペース通知

クライアントが、キーのライフサイクルイベント(設定、削除、有効期限、追い出し)へ反応できるのが、キースペース通知です。notify-keyspace-events で設定しましょう。発火後放置であり(永続化なし)、信頼できません。Redis サーバーが再起動すれば、pending のイベントが失われます。信頼できるイベント処理のためには、Streams を。後始末やキャッシュの予熱のような副作用に素晴らしいのが、キースペース通知です。

redis-cli
# enable keyspace notifications (disabled by default)
CONFIG SET notify-keyspace-events "KEA"
# K = keyspace events, E = keyevent events
# g = generic (DEL, EXPIRE, ...), $ = string, l = list
# h = hash, s = set, z = sorted set, x = expired, e = evicted
# A = all except m (m = keymiss)

# subscribe to events on a specific key
SUBSCRIBE __keyspace@0__:mykey
# publishes "set", "del", "expire", etc.

# subscribe to events of a specific type
SUBSCRIBE __keyevent@0__:del
# publishes the key name that was deleted

# example: react when a key expires
SUBSCRIBE __keyspace@0__:session:abc
# receives "expired" when the key TTL ends

# example: react to all expired keys
SUBSCRIBE __keyevent@0__:expired

# check current setting
CONFIG GET notify-keyspace-events
10

トランザクション

MULTI と EXEC

コマンドをアトミックで逐次的なブロックへグループ化するのが、MULTI/EXEC です。他のクライアントが割り込めません。キューに入り(QUEUED を返し)、EXEC で一緒に実行されるのが、コマンドです。トランザクション全体を中止するのが、(悪いコマンド名の)キューイングエラーです。そのコマンドだけをスキップするのが(キー上の間違ったタイプなどの)ランタイムエラーです。残りが依然実行されます。SQL のトランザクションと違うのが、これです。

redis-cli
# MULTI starts a transaction; commands are queued
MULTI
SET counter 1
INCR counter
INCR counter
GET counter
EXEC
# returns: 1) OK  2) 2  3) 3  4) "3"

# all queued commands execute atomically (no interleaving)
# other clients cannot run commands between MULTI and EXEC

# each queued command returns "QUEUED" until EXEC
MULTI
SET x 1
# "QUEUED"
INCR x
# "QUEUED"
EXEC
# 1) OK 2) 2

# the transaction is atomic: all or nothing (at queuing time)

DISCARD(トランザクションの取り消し)

トランザクションを取り消し、キューに入ったすべてのコマンドを消去し、接続をトランザクションモードから解放するのが、DISCARD です。WATCH されたキーも消去します(WATCH を参照)。DISCARD 後、クライアントが再度通常のコマンドを発行できます。ロールバックの等価物であるのが、DISCARD ですが、EXEC 内の部分的なロールバックを Redis がサポートしないことに注意しましょう。ランタイムエラーが、失敗するコマンドをスキップし、残りをコミットします。

redis-cli
# DISCARD cancels a transaction (clears all queued commands)
MULTI
SET x 1
INCR x
DISCARD
# OK — no commands are executed

# after DISCARD, the connection returns to normal mode
GET x
# (nil) or the previous value — nothing changed

# DISCARD also clears all WATCHed keys
WATCH counter
MULTI
INCR counter
DISCARD
# counter is no longer watched

# you must call MULTI before DISCARD
DISCARD
# ERR DISCARD without MULTI

WATCH(楽観的ロッキング)

楽観的ロッキングを実装するのが、WATCH です。WATCH と EXEC の間で、watch されたキーが変われば、トランザクションが中止されます(EXEC が nil を返します)。read-modify-write の原子性のための、標準の Redis のパターンです(Redis に行ロックがないため)。nil のときは必ず再試行しましょう。EXEC の時点で確認されるのが、WATCH です。watch の取り消しは、UNWATCH です(DISCONNECT でも起きます)。同じクライアントによる、watch されたキーの修正も、中止をトリガーします。

redis-cli
# WATCH monitors keys; if any change before EXEC, transaction aborts
WATCH counter
val = GET counter          # read current value
MULTI
INCR counter               # queue the update
EXEC                       # nil if counter changed -> retry

# typical pattern: read-modify-write with retry
WATCH key
current = GET key
new_value = compute(current)
MULTI
SET key new_value
EXEC
# if EXEC returns nil, the key changed — loop and retry

# UNWATCH cancels all watches
UNWATCH

# WATCH is checked at EXEC time, not during queuing
# if a watched key is modified (by any client, including yourself),
# EXEC returns nil and the transaction is not executed

UNWATCH と WATCH の端のケース

(トランザクションがコミットされたか、WATCH により中止されたかにかかわらず)すべての watch が自動的に消去されるのが、EXEC の後です。DISCARD も同様です。楽観的ロックのループを再試行するには、次の MULTI の前に、WATCH を再度呼ばなければなりません。エラーであるのが、MULTI 内の WATCH です。WATCH は、常に MULTI に先行しなければなりません。トランザクションに入らず watch を取り消すのが、主に UNWATCH です。

redis-cli
# UNWATCH cancels all watches
WATCH key1 key2
UNWATCH                    # both keys are no longer watched

# WATCH inside a MULTI is not allowed (error)
MULTI
WATCH key
# ERR WATCH inside MULTI is not allowed

# after EXEC (success or abort), watches are cleared
WATCH key
MULTI
SET key "new"
EXEC
# key is no longer watched after EXEC

# after DISCARD, watches are cleared
WATCH key
MULTI
DISCARD
# key is no longer watched

# re-WATCH after EXEC to retry the optimistic lock loop
WATCH key
val = GET key
MULTI
SET key newval
EXEC
# if nil, loop: WATCH key again, GET, MULTI, SET, EXEC

トランザクションのエラー処理

トランザクションで 2 つのエラーのタイプを持つのが、Redis です。EXEC の時点でトランザクション全体を中止するのが、(悪いコマンド名/arity の)キューイングエラーです(EXECABORT)— 何も動きません。失敗するコマンドだけをスキップするのが、(非整数上の INCR などの)ランタイムエラーです。残りが依然実行されます。ロールバックは「ありません」。SQL データベースとの決定的に重要な違いです。ランタイムエラーを避けるため、MULTI の前にデータを検証しましょう。

redis-cli
# two types of errors in transactions:

# 1. Queuing errors (bad command syntax) — aborts the WHOLE transaction
MULTI
SET key "value"
INCRBY key "notanumber"   # error during queuing (wrong arity/type at parse)
GET key
EXEC
# EXECABORT Transaction discarded because of previous errors.
# NOTHING executes — not even the SET

# 2. Runtime errors (wrong type at execution) — skips ONLY that command
SET key "stringvalue"
MULTI
INCR key                  # queues fine (syntax OK)
SET otherkey "ok"
EXEC
# 1) (error) ERR value is not an integer
# 2) OK
# the INCR failed but SET otherkey succeeded — no rollback!

# lesson: Redis transactions do NOT have rollback like SQL
11

パイプライン

Pipeline の基本

ネットワークのラウンドトリップを減らすため、コマンドをバッチ化するのが、パイプラインです。ネットワーク上の個々のコマンドより劇的に速いです。ネットワークレイテンシがかかるのが(約 0.1〜1ms)、各ラウンドトリップで、1000 の個々のコマンド = 100〜1000ms ですが、パイプライン化すると = 約 1ms です。pipeline/multi のメソッドを提供するのが、ほとんどのクライアントライブラリです。stdin 経由でパイプライン化できるのが、redis-cli です。原子性をパイプラインが保証し「ません」 — 他のクライアントが割り込めます。

redis-cli
# pipelining sends multiple commands in one network round-trip
# (no atomicity guarantee, just reduced latency)

# using redis-cli with stdin (simple pipeline):
printf '%s\n' "SET k1 v1" "SET k2 v2" "GET k1" | redis-cli
# OK
# OK
# "v1"

# using redis-cli --pipe (raw RESP, fastest for bulk loads):
# (see the data-import-export section for details)

# in a client library (e.g., Node.js with ioredis):
const pipe = redis.pipeline()
pipe.set("k1", "v1")
pipe.set("k2", "v2")
pipe.incr("counter")
const results = await pipe.exec()

# vs individual commands:
await redis.set("k1", "v1")    # round-trip 1
await redis.set("k2", "v2")    # round-trip 2
await redis.incr("counter")    # round-trip 3

MULTI 対パイプライン

原子性を保証し(他のクライアントが割り込めません)、ほとんどのクライアントライブラリにより自動的にパイプライン化されるのが(ラウンドトリップも減ります)、MULTI/EXEC です。ラウンドトリップだけを減らすのが、素のパイプラインです。あなたのパイプライン化されたコマンドの間に、他のクライアントが実行できます。原子性が必要なときは(WATCH での read-modify-write など)、MULTI/EXEC を使い、順序/原子性が効かない一括操作には、素のパイプラインを使いましょう。

redis-cli
# MULTI/EXEC: atomic (no interleaving), pipelined automatically
MULTI
SET k1 v1
SET k2 v2
INCR counter
EXEC
# all 3 commands run atomically as one block

# Pipelining: NOT atomic, just batched (other clients can interleave)
# (in client code)
pipe.set("k1", "v1")
pipe.set("k2", "v2")
pipe.incr("counter")
pipe.exec()
# commands may interleave with other clients

# when to use which:
# - need atomicity (all-or-nothing)?      -> MULTI/EXEC
# - just want speed (bulk operations)?    -> pipelining
# - both?                                  -> MULTI/EXEC (auto-pipelined)

# MULTI/EXEC is automatically pipelined by most clients
# so you get atomicity + batch round-trips in one

RESP プロトコル

Redis のワイヤプロトコルが、RESP です。単純で、テキストベースで、速いです。N 要素の配列を示すのが、*N で、N バイトの bulk 文字列を示すのが、$N、単純な文字列が +、整数が :、エラーが - です。最大速度の一括ロードのための生の RESP を受け付けるのが(stdin 経由のテキストコマンドよりはるかに速い)、redis-cli --pipe モードです。カスタムクライアントの構築とデバッグに、RESP の理解が役立ちます。

redis-cli
# RESP (REdis Serialization Protocol) is the wire format
# redis-cli sends RESP; you can also send it raw with --pipe

# simple command (PING) in RESP:
# *1\r\n$4\r\nPING\r\n

# SET key value in RESP:
# *3\r\n$3\r\nSET\r\n$3\r\nkey\r\n$5\r\nvalue\r\n

# RESP types:
#   +OK      simple string
#   -ERR     error
#   :42      integer
#   $5\r\nhello   bulk string
#   *2\r\n...     array

# raw pipeline with RESP (fastest bulk insert):
# generate a RESP file and pipe it:
cat commands.resp | redis-cli --pipe

# --pipe mode expects raw RESP; checks reply counts
# output: "Last reply received from server: ..."
# "errors: 0, replies: N"

シェルスクリプト内のパイプライン

データの一括ロードやバッチ操作のよくある方法が、redis-cli でのシェルスクリプティングです。最も簡単なアプローチが、stdin 経由のテキストコマンドのパイプです(echo/cat | redis-cli)。最大速度のためには、RESP を生成し --pipe モードを使いましょう(大きなロードでは一桁速いです)。両方のアプローチを示すのが、bash ループの例です。ボリュームとパフォーマンスのニーズに基づき選びましょう。

redis-cli
# pipeline multiple commands via stdin
echo -e "SET k1 v1\nSET k2 v2\nGET k1\nGET k2" | redis-cli

# pipeline from a file
cat commands.txt | redis-cli

# pipeline with --pipe-mode (raw RESP, fastest)
# first generate RESP, then pipe:
redis-cli --pipe < commands.resp

# bulk insert example (bash, generate RESP):
for i in $(seq 1 1000); do
  printf '*3\r\n$3\r\nSET\r\n$4\r\nkey:\r\n$1\r\n%s\r\n' "$i"
done | redis-cli --pipe

# or simpler (text mode, slightly slower):
for i in $(seq 1 1000); do
  echo "SET key:$i value$i"
done | redis-cli

# --pipe-mode reports errors and throughput

パイプラインの限界とベストプラクティス

Redis パフォーマンスの最大の単一のレバーが、パイプラインですが、過剰なパイプライン化は避けましょう — クライアントとサーバーの両方で、キューに入ったリプライがメモリを消費します。100〜1000 コマンドのグループでバッチ化しましょう。甘味点を見つけるには、redis-benchmark -P でベンチマークしましょう(非常に大きいパイプラインでは、スループットが平らになり、レイテンシが増えます)。前の結果に依存するコマンドのためには、複数のパイプライン化された呼び出しの代わりに、Lua スクリプトを(アトミック、1 ラウンドトリップ)。

redis-cli
# don't pipeline too many commands at once
# (queued replies consume memory on both client and server)

# bad: 1 million commands in one pipeline
# -> huge memory buffer, potential timeout

# good: batch in groups of 100-1000
for batch in chunks(data, 500):
  pipe = redis.pipeline()
  for item in batch:
    pipe.set(item.key, item.value)
  pipe.exec()

# benchmark pipelining
redis-benchmark -t set -n 100000 -P 16   # -P = pipeline size
# try -P 1, 10, 100, 1000 to find the sweet spot

# use pipelining for:
# - bulk imports
# - batch reads (MGET is better for simple multi-get)
# - pre-warming cache
# - reducing latency in high-RTT environments

# avoid pipelining for:
# - commands that depend on previous results (use Lua instead)
# - very large batches (split into chunks)
12

Lua スクリプティング

EVAL の基本

Lua スクリプトをアトミックに実行するのが、EVAL です。スクリプトが動く間、他のコマンドが実行されないため、マルチステップのアトミックな操作に理想的です。呼び出し元からデータを運ぶのが、KEYS と ARGV です。スクリプト内で文字列の連結によりキーを構築してはいけません(クラスタのルールに違反します — すべてのキーが KEYS になければなりません)。エラーを上げるのが(止まる)、redis.call で、返すのが、redis.pcall です。EVALSHA のために、SHA1 ハッシュによりキャッシュされるのが、スクリプトです。

redis-cli
# EVAL: run a Lua script inline
# EVAL "script" numkeys key1 key2 ... arg1 arg2 ...
EVAL "return redis.call('GET', KEYS[1])" 1 mykey
# 1 = number of keys
# mykey = KEYS[1]

# run a simple script (no keys)
EVAL "return 42" 0
EVAL "return {1, 2, 3}" 0
EVAL "return 'hello'" 0

# a check-and-set script:
EVAL "
  local cur = redis.call('GET', KEYS[1])
  if cur == ARGV[1] then
    return redis.call('SET', KEYS[1], ARGV[2])
  end
  return 0
" 1 mykey "expected" "newvalue"

# redis.call() raises error if command fails (stops script)
# redis.pcall() returns error as a table (can handle)
EVAL "local ok, err = pcall(redis.call, 'GET', 'missing'); return err" 0

EVALSHA と SCRIPT LOAD

SHA1 ハッシュにより、以前ロードされたスクリプトを実行するのが、EVALSHA です。毎呼び出しのスクリプト本文の再送信を避けるため、同じスクリプトを繰り返し実行するアプリにとって、大きな帯域の勝ちです。キャッシュミスのとき(SCRIPT FLUSH の後か再起動の後)、NOSCRIPT を返すのが、Redis で、クライアントがこれを捉え、EVAL + SCRIPT LOAD へフォールバックします。これを透過的に扱うライブラリ(redis-py、ioredis)を必ず使いましょう。

redis-cli
# load a script once, get its SHA1
SCRIPT LOAD "return redis.call('GET', KEYS[1])"
# returns: "fa00d1f0..." (the SHA1 hash)

# execute by hash (saves bandwidth on repeated calls)
EVALSHA "fa00d1f0..." 1 mykey

# check if a script is cached
SCRIPT EXISTS "fa00d1f0..." "abcd1234..."
# 1) 1  2) 0   (1 = exists, 0 = not cached)

# flush the script cache
SCRIPT FLUSH

# list all running scripts (during debug)
SCRIPT DEBUG SYNC   # blocking debug mode
SCRIPT DEBUG NO     # disable debugger

# typical client library pattern:
# 1. SCRIPT LOAD the script on startup
# 2. EVALSHA to run it (falls back to EVAL on NOSCRIPT error)

SCRIPT LOAD、FLUSH、EXISTS

スクリプトをキャッシュし SHA1 を返すのが、SCRIPT LOAD です。スクリプトがキャッシュされているか確認するのが(再起動後に有用)、SCRIPT EXISTS です。キャッシュされたすべてのスクリプトを消去するのが、SCRIPT FLUSH です。以後の EVALSHA が NOSCRIPT を返します。長時間実行されるスクリプトを止めるのが、SCRIPT KILL ですが、いかなる書き込みもまだしていなければ、だけです(一貫性の維持のためです)。していれば、SHUTDOWN NOSAVE しなければなりません。一時的であるのが、スクリプトです。永続化のためには、Functions(7.0+)を使いましょう。

redis-cli
# SCRIPT LOAD: load a script without running it
SCRIPT LOAD "return redis.call('SET', KEYS[1], ARGV[1])"
# returns the SHA1 hash

# SCRIPT EXISTS: check if scripts are cached (after load or restart)
SCRIPT EXISTS "abc123..." "def456..."
# 1) 1  2) 0

# SCRIPT FLUSH: clear the script cache
SCRIPT FLUSH
# all EVALSHA calls will now return NOSCRIPT until scripts are reloaded

# SCRIPT KILL: stop a running script (only if it hasn't written yet)
SCRIPT KILL

# if the script has already executed a write command:
# SHUTDOWN NOSAVE is the only way to stop it (extreme measure)

# scripts are ephemeral — they don't survive a restart
# use Redis Functions (7.0+) for persistent scripts

# check the script cache size
INFO memory | grep script_cache

KEYS と ARGV

キー名を運ぶのが、KEYS[] です(クラスタルーティングには不可欠です。スクリプトを扱うシャードを決めるのに、クラスタがこれらを使います)。値とパラメータを運ぶのが、ARGV[] です。スクリプトの内側でキー名をハードコードしてはいけません(redis.call('GET', 'mykey') など)— クラスタが、「mykey」がどのシャードに住むか伝えられないため、これがクラスタルーティングを壊します。KEYS[] 経由で、必ずキーを渡しましょう。Redis にいくつの KEYS を期待するか伝えるのが、numkeys 引数です。

redis-cli
# KEYS[]: key names passed to the script
# ARGV[]: additional arguments (values, options)

# example: atomic increment with cap
EVAL "
  local current = tonumber(redis.call('GET', KEYS[1]) or 0)
  local max = tonumber(ARGV[1])
  if current >= max then
    return -1  -- cap reached
  end
  return redis.call('INCR', KEYS[1])
" 1 counter 100
# KEYS[1] = counter, ARGV[1] = 100

# example: move item between lists atomically
EVAL "
  local item = redis.call('RPOP', KEYS[1])
  if item then
    redis.call('LPUSH', KEYS[2], item)
  end
  return item
" 2 source_list dest_list

# NEVER hardcode key names in scripts (breaks cluster routing)
# always pass keys via KEYS[] so the cluster can route correctly

Lua によるアトミックな操作

Redis でのアトミックなマルチコマンドの操作の正統な方法が、Lua スクリプトです(MULTI/EXEC の競合なし)。compare-and-set、セマフォの取得、キューの移行、レート制限が、すべて利得を得ます。実行間、スクリプトがサーバーをブロックするため、短く保ち、多くのキーの上のループを避けましょう(他のクライアントを止め得ます)。非常に長い作業には、Redis Functions(Redis 7.0+)を。ストアドプロシージャのように宣言され、バージョン管理されるのです。

redis-cli
# atomic compare-and-set (only update if value matches)
EVAL "
  local cur = redis.call('GET', KEYS[1])
  if cur == ARGV[1] then
    return redis.call('SET', KEYS[1], ARGV[2])
  end
  return 0
" 1 mykey "expected" "newvalue"

# atomic 'decrement if positive' (semaphore / rate limit)
EVAL "
  local val = tonumber(redis.call('GET', KEYS[1]) or 0)
  if val > 0 then
    redis.call('DECR', KEYS[1])
    return 1
  end
  return 0
" 1 semaphore

# atomic list pop + push (move between queues)
EVAL "
  local item = redis.call('RPOP', KEYS[1])
  if item then
    redis.call('LPUSH', KEYS[2], item)
  end
  return item
" 2 source_queue dest_queue

# atomic rate limiter (fixed window)
EVAL "
  local count = redis.call('INCR', KEYS[1])
  if count == 1 then
    redis.call('EXPIRE', KEYS[1], ARGV[1])
  end
  return count
" 1 rate:user:1 60

Redis Functions(7.0+)

EVAL スクリプトを改善するのが、Functions(7.0+)です。名前が付けられ(ハッシュだけでなく)、ライブラリへ整理され、再起動をまたいで持続します(一時的なのが、EVAL スクリプトです)。これで、管理とデプロイがしやすくなります。名前により関数を呼び出すのが、FCALL です。アトミックなサーバー側のロジックを加えるモダンな方法が、Functions です。スクリプトのように、レプリケーションのために決定的でなければなりません。バックアップと移行を可能にするのが、FUNCTION DUMP/RESTORE です。

redis-cli
# FUNCTIONS are named, versioned Lua scripts (better than EVAL)
# register a function library
FUNCTION LOAD '#!lua name=mylib
redis.register_function("my_set",
  function(keys, args)
    return redis.call("SET", keys[1], args[1])
  end
)'

# call a function by name
FCALL my_set 1 mykey "hello"

# list loaded libraries
FUNCTION LIST
FUNCTION LIST WITHCODE   # include source

# get the function's code (for backup)
FUNCTION DUMP

# delete a library
FUNCTION DELETE mylib

# restore from a dump (for migration)
FUNCTION RESTORE <payload>

# functions persist across restarts (unlike EVAL scripts)
# they're saved in RDB/AOF
13

接続の管理

CLIENT LIST

アドレス、年齢、アイドル時間、現在のコマンド、フラグと共に、接続されたすべてのクライアントを示すのが、CLIENT LIST です。リークや塞がったクライアントの発見には非常に有用です。放置された接続を見つけるのに役立つのが、「idle」のフィールドです。遅いコマンドを実行するクライアントの発見に有用なのが(示すのが)、最後のコマンドの「cmd」です。クライアントのタイプを示すのが、「flags」です(N = 通常、M = master、S = slave/replica、P = pubsub、b = blocked です)。フィルタするのが、7.0+ の TYPE です。

redis-cli
# list all connected clients
CLIENT LIST
# fields: id, addr, laddr, fd, name, age, idle, flags, db, cmd, ...

# filter by type (7.0+)
CLIENT LIST TYPE normal    # normal clients only
CLIENT LIST TYPE replica   # replicas
CLIENT LIST TYPE pubsub    # pub/sub subscribers

# filter by ID (7.0+)
CLIENT LIST ID 1 2 3

# output includes useful fields:
#   addr=10.0.0.1:12345   remote address
#   age=3600              seconds since connected
#   idle=0                seconds since last command
#   cmd=get               last command executed
#   db=0                  current database
#   flags=N               N=normal, M=master, S=slave, P=pubsub

# count connected clients
CLIENT LIST | wc -l

CLIENT SETNAME と GETNAME

接続にラベルを付け、CLIENT LIST で識別できるのが、CLIENT SETNAME です。マルチサービス環境での接続リークのデバッグには不可欠です。アプリで接続後すぐに名前を設定しましょう(例:「api-server:pid12345:pool1」)。CLIENT LIST の「name」フィールドに現れるのが、名前です。これで、塞がったか漏れた接続をどのサービスが所有するか見つけるのが自明になります。

redis-cli
# name your connection (for identification in CLIENT LIST)
CLIENT SETNAME "my-app-worker-1"

# get the current connection's name
CLIENT GETNAME

# in application code, set the name immediately after connecting:
# redis-cli example:
redis-cli CLIENT SETNAME "debug-session"

# names appear in CLIENT LIST output:
CLIENT LIST
# ... name=my-app-worker-1 ...

# names are useful for:
# - identifying which app/pool a connection belongs to
# - finding leaks (connections that should have been closed)
# - debugging stuck clients
# - naming conventions: app:hostname:pid or pool:name

# names are limited to a reasonable length and cannot contain spaces

CLIENT KILL

クライアントを強制的に切断するのが、CLIENT KILL です。塞がったか漏れた接続の除去に有用です。ADDR(ip:port)、ID、TYPE、か USER(ACL)により、kill できます。N 秒より長くアイドルなクライアントを殺すのが、MAXAGE(7.0+)です。自分の接続の kill を防ぐのが、SKIPME yes(デフォルト)です。まず CLIENT LIST でターゲットを見つけ、その後、切断するために CLIENT KILL を使いましょう。即座であるのが(優雅なシャットダウンなし)、kill です。

redis-cli
# kill a client by address
CLIENT KILL ADDR 10.0.0.1:12345

# kill a client by ID
CLIENT KILL ID 42

# kill by type (7.0+)
CLIENT KILL TYPE normal    # kill all normal clients
CLIENT KILL TYPE pubsub    # kill all pub/sub clients

# kill by user (ACL, 6.0+)
CLIENT KILL USER appuser

# kill by address with skip-me
CLIENT KILL ADDR 10.0.0.1:0 SKIPME yes   # don't kill myself

# kill all clients matching filters (7.0+)
CLIENT KILL TYPE normal MAXAGE 3600      # kill idle > 1h

# kill returns the number of clients killed
# use with caution — kills are immediate, no graceful shutdown

# common use: disconnect a stuck client consuming resources
CLIENT LIST
CLIENT KILL ID <id>

CLIENT ID と INFO

接続のための、決して再利用されない一意の整数を返すのが、CLIENT ID です。ロギングと相関に有用です。自分の接続についての詳細な情報を与えるのが、CLIENT INFO です。クライアントの書き込みが、追い出しをトリガーするのを守るのが、CLIENT NO-EVICT(6.0+)です(クリティカルな書き込みに有用)。サーバーがリプライを送るかどうかを制御するのが、CLIENT REPLY です(発火後放置の一括ロードのための OFF、1 コマンドのための SKIP)。

redis-cli
# get the current client's unique ID (never reused)
CLIENT ID

# get the current client's info (detailed)
CLIENT INFO
# id=42 addr=127.0.0.1:12345 laddr=127.0.0.1:6379 name= db=0 ...

# the ID is a monotonically increasing integer
# it's unique per connection and never reused
# useful for logging and tracking

# CLIENT NO-EVICT (6.0+): this client's writes won't trigger eviction
CLIENT NO-EVICT ON    # protect this client from eviction
CLIENT NO-EVICT OFF   # normal behavior

# CLIENT REPLY (6.0+): control reply mode
CLIENT REPLY ON       # normal replies
CLIENT REPLY OFF      # no replies
CLIENT REPLY SKIP     # skip reply for next command only

# CLIENT UNPAUSE: resume processing after CLIENT PAUSE
CLIENT UNPAUSE

CLIENT PAUSE

N ミリ秒の間、他のすべてのクライアントのコマンド実行をブロックするのが、CLIENT PAUSE です。安全なスナップショット、移行、クラスタのフェイルオーバーに有用です。読み取りが続けられる間、書き込みだけを止めるのが、WRITE モード(7.0+)です(より侵襲的でありません)。止められることのないのが、止め側のクライアント自身です。止めの間、キューに入ったコマンドがメモリを消費するため、止めは短く保ちましょう。即座に再開するのが、CLIENT UNPAUSE です。

redis-cli
# pause all client processing for N milliseconds
CLIENT PAUSE 10000         # pause for 10 seconds
# all other clients' commands are queued, not executed

# pause modes (7.0+):
CLIENT PAUSE 10000 ALL        # pause all commands (default)
CLIENT PAUSE 10000 WRITE      # pause only writes (reads continue)

# resume processing immediately
CLIENT UNPAUSE

# use cases:
# - safe snapshot/migration (pause writes, take consistent backup)
# - cluster failover (pause to ensure clean handoff)
# - debugging (pause to inspect state)

# during pause:
# - commands from OTHER clients are queued (memory grows)
# - the pausing client can still run commands
# - paused commands execute when the pause ends

# check if a pause is active
CLIENT INFO | grep flags
# 'P' flag = paused

接続の限界とタイムアウト

同時接続に上限を設けるのが(デフォルト 10000)、maxclients です。多くのアプリサーバーや接続プールがあるなら引き上げましょう。アイドルのクライアントを切断するのが、timeout です(0 = 決して。安全のため 300 秒に設定)。死んだ TCP 接続を検出するのが、tcp-keepalive です(デフォルト 300 秒)。出力バッファのためのメモリを、各クライアントが消費するため、INFO clients で監視しましょう。1 つの遅いクライアントがすべてのサーバーのメモリを消費するのを防ぐのが、client-output-buffer-limit です(pub/sub とレプリカでは特に重要です)。

redis-cli
# max concurrent clients
CONFIG GET maxclients        # default 10000
CONFIG SET maxclients 50000  # increase limit

# timeout: disconnect idle clients after N seconds
CONFIG GET timeout           # default 0 (never)
CONFIG SET timeout 300       # 5 minutes

# TCP keepalive (detect dead connections)
CONFIG GET tcp-keepalive     # default 300
CONFIG SET tcp-keepalive 60

# when maxclients is reached, new connections are rejected
# error: "ERR max number of clients reached"

# check current client count vs limit
INFO clients
# connected_clients:150
# blocked_clients:5
# maxclients:10000

# each connection uses memory (~a few KB for the output buffer)
# monitor for output buffer growth:
INFO clients | grep client_recent_max_output_buffer

# set output buffer limits (prevent one client from using all memory)
CONFIG GET client-output-buffer-limit
14

サーバーの管理

INFO のセクション

主要なモニタリングコマンドが、INFO です。メモリ、クライアント、レプリケーション、永続化、統計を 1 発で報告します。出力を減らすのが、セクションのフィルタ(INFO memory)です。主要な指標:used_memory_rss(本物のフットプリント)、mem_fragmentation_ratio(理想的なのが、約 1.0〜1.5)、connected_clients、instantaneous_ops_per_sec、(キャッシュのヒット率の)keyspace_hits/misses です。時計の同期のためのサーバー時刻を返すのが、TIME です。

redis-cli
# comprehensive server information
INFO                  # all sections
INFO server           # version, uptime, config
INFO clients          # connected clients
INFO memory           # memory usage, fragmentation
INFO persistence      # RDB/AOF status
INFO stats            # ops/sec, hit rate, keyspace
INFO replication      # primary/replica state
INFO cpu              # CPU usage
INFO keyspace         # keys per database
INFO commandstats     # command frequency
INFO errorstats       # error frequency

# get a specific metric
INFO memory | grep used_memory_human
INFO stats | grep instantaneous_ops_per_sec
INFO replication | grep role

# check Redis version and mode
INFO server | grep redis_version
INFO server | grep redis_mode        # standalone, cluster, sentinel

# get server time
TIME                    # [unix_timestamp, microseconds]

CONFIG GET と SET

Redis を再起動せず実行時に設定を変えるのが、CONFIG SET です。チューニングに理想的です。現在の値を取得するのが、CONFIG GET で(CONFIG GET *memory* のようなパターンを使いましょう)。よくあるランタイムの調整:maxmemory + 追い出しポリシー、slowlog のしきい値、timeout、エンコーディングのしきい値です。実行時に変更可能でないのが、すべての設定ではありません(ポートや bind アドレスのようなものは、再起動が要ります)。まずステージングで、設定の変化を必ずテストしましょう。

redis-cli
# view config (runtime changes with CONFIG SET)
CONFIG GET maxmemory
CONFIG GET maxmemory-policy
CONFIG GET save
CONFIG GET appendonly
CONFIG GET requirepass

# change config at runtime (no restart needed)
CONFIG SET maxmemory 4gb
CONFIG SET maxmemory-policy allkeys-lru
CONFIG SET slowlog-log-slower-than 10000   # 10ms in microseconds
CONFIG SET timeout 300

# view all config (large output)
CONFIG GET *

# get a specific pattern
CONFIG GET *max*
CONFIG GET *timeout*

# common runtime tweaks:
CONFIG SET maxclients 20000
CONFIG SET hash-max-listpack-entries 256
CONFIG SET appendfsync everysec

CONFIG REWRITE

実行時の CONFIG SET の変化を redis.conf へ永続化し戻すのが、CONFIG REWRITE です。コメントと構造を保ちつつ、ファイルがその場で更新されます。これが、実行時の変化と、再起動をまたぐ永続化の間のギャップを橋渡しします。REWRITE の前に、redis.conf を必ずバックアップしましょう(めったに問題を起こしませんが、安全第一です)。時間をかけて変化を追跡・監査できるよう、redis.conf をバージョン管理しましょう。

redis-cli
# persist config changes to redis.conf
CONFIG REWRITE

# after CONFIG SET maxmemory 4gb
# CONFIG REWRITE updates redis.conf to include:
#   maxmemory 4gb

# the original redis.conf is updated in-place
# comments and structure are preserved

# view the config file path
CONFIG GET *

# typical redis.conf (production):
# bind 127.0.0.1
# protected-mode yes
# port 6379
# maxmemory 4gb
# maxmemory-policy allkeys-lru
# save 3600 1
# appendonly yes
# appendfsync everysec
# tcp-keepalive 300
# timeout 0

# always back up redis.conf before CONFIG REWRITE

SLOWLOG

設定されたしきい値(デフォルト 10ms = 10000us)より遅いコマンドを記録するのが、SLOWLOG です。レイテンシの犯人の発見には非常に有用です。あなたの SLO へしきい値を設定しましょう(例:5ms)。よくある遅いコマンド:巨大なセット上の KEYS、SMEMBERS、巨大なハッシュ上の HGETALL、大きなデータ上の SORT です。ログに上限を設けるのが、slowlog-max-len です(デフォルト 128)。デバッグのためには(高オーバーヘッドです)、しきい値を 0 へ設定しすべてをログしましょう。

redis-cli
# configure slow log (threshold in microseconds)
CONFIG SET slowlog-log-slower-than 10000   # 10ms (10000 us)
CONFIG SET slowlog-max-len 128             # keep last 128 entries

# view slow commands
SLOWLOG GET          # last 10 (default)
SLOWLOG GET 5        # last 5
SLOWLOG GET 0        # all entries

# each entry:
# 1) id              unique ID
# 2) timestamp       Unix time
# 3) duration        microseconds
# 4) command         the command and args
# 5) client          address:port
# 6) client name     if set

# slowlog length
SLOWLOG LEN

# reset (clear all entries)
SLOWLOG RESET

# set threshold to 0 to log ALL commands (debugging)
# set to -1 to disable
CONFIG SET slowlog-log-slower-than 0

MONITOR

すべてのクライアントからのすべてのコマンドをリアルタイムにストリーミングするのが、MONITOR です。強力なデバッグツールですが、巨大なパフォーマンスの影響があります(スループットを大まかに半減させます)。絶対に必要でない限り、本番で MONITOR を決して使いず、短い間だけにしましょう。ステージングに完璧です:MONITOR に接続し、問題を再現すれば、アプリが送るコマンドが正確に見えます。本番には、代わりに SLOWLOG、LATENCY MONITOR、か INFO commandstats を。

redis-cli
# MONITOR: real-time log of ALL commands (debugging only!)
MONITOR
# every command from every client is printed:
# 1700000000.123456 [0 10.0.0.1:12345] "SET" "key" "value"
# 1700000000.123567 [0 10.0.0.1:12345] "GET" "key"

# to stop monitoring, send any non-MONITOR command or disconnect
# press Ctrl+C in redis-cli

# WARNING: MONITOR has a HUGE performance impact
# it roughly halves throughput — use only for debugging

# use cases:
# - debugging what commands an app is sending
# - auditing command patterns
# - finding the source of unexpected writes

# safer alternatives for production:
# - SLOWLOG (only slow commands)
# - LATENCY MONITOR (specific events)
# - COMMANDSTATS in INFO (command frequency)

# MONITOR is best used in a staging/dev environment

LATENCY のモニタリング

レイテンシのイベントを追跡するのが(しきい値を設定しましょう。例:100ms)、LATENCY MONITOR です。最近のイベントを分析し修正を提案するのが、LATENCY DOCTOR です。診断の素晴らしい出発点です。よくあるイベント:「command」(遅いコマンド)、「fork」(BGSAVE の fork 遅延)、「expire-cycle」(有効期限の掃除)、「aof-write」(AOF の fsync 遅延)です。ASCII のタイムラインを示すのが、LATENCY GRAPH です。しきい値をあなたの SLO へ設定し、定期的に監視しましょう。

redis-cli
# enable latency monitoring (threshold in ms)
CONFIG SET latency-monitor-threshold 100   # 100ms

# view latency events
LATENCY HISTORY event-name
LATENCY LATEST                            # most recent events
LATENCY HISTORY command
LATENCY HISTORY expire-cycle

# ASCII art graph of an event
LATENCY GRAPH command

# human-readable diagnosis and recommendations
LATENCY DOCTOR

# reset latency data
LATENCY RESET
LATENCY RESET event-name

# common events to monitor:
#   command         slow commands
#   fast-command    slow O(1) commands
#   expire-cycle    expiration cycle taking too long
#   fork            BGSAVE/BGREWRITEAOF fork taking too long
#   aof-write       AOF write delays
#   unlink          async delete delays

# check current threshold
CONFIG GET latency-monitor-threshold
15

Cluster

CLUSTER INFO

素早い健康の要約を与えるのが、CLUSTER INFO です。cluster_state が「ok」であるべき(すべての 16384 スロットがカバーされている)で、cluster_slots_ok が 16384 と等しいべきです。合計のノード数が、cluster_known_nodes で、プライマリの数が、cluster_size です。cluster_state が「fail」なら、いくつかのスロットが利用不可です(おそらく、プライマリとそのレプリカの両方が down です)。任意のノードから確認しましょう — 情報が、クラスタ全体です。

redis-cli
# cluster-wide health
CLUSTER INFO
# key fields:
#   cluster_state:ok              # ok or fail
#   cluster_slots_assigned:16384  # total slots
#   cluster_slots_ok:16384        # slots covered
#   cluster_known_nodes:6         # total nodes
#   cluster_size:3                # number of primaries
#   cluster_current_epoch:7
#   cluster_my_epoch:1

# cluster_state:ok means all slots are covered
# cluster_state:fail means some slots are unavailable

# check from any node in the cluster
redis-cli -p 7000 CLUSTER INFO

# other cluster commands require being in cluster mode
# (redis-server --cluster-enabled yes)

CLUSTER NODES

決定的なトポロジのビューが、CLUSTER NODES です。ノードごとに 1 行で、ID、アドレス、ロール(master/slave)、(レプリカのために)従う master、スロットの範囲を持ちます。不健康なノードを示す、「fail」か「fail?」のフラグを探しましょう。どのプライマリがどのハッシュスロット(0〜16383)を所有するか示すのが、スロットの範囲です。シャード(プライマリ + そのレプリカ)によりノードをグループ化するのが、CLUSTER SHARDS(7.0+)です。

redis-cli
# view the full cluster topology
CLUSTER NODES
# each line is a node:
# <id> <addr:port@cport> <flags> <master> <ping-sent> <pong-recv> <epoch> <link> <slots>

# flags include:
#   M  = master (primary)
#   S  = slave (replica)
#   mymaster = the node this replica follows
#   fail? = suspected down
#   fail  = confirmed down
#   handshake = new node joining
#   nofailover = failover disabled

# example output:
# 1a2b... 127.0.0.1:7000@17000 myself,master - 0 0 1 connected 0-5460
# 3c4d... 127.0.0.1:7001@17001 master - 0 0 2 connected 5461-10922
# 5e6f... 127.0.0.1:7002@17002 master - 0 0 3 connected 10923-16383
# 7g8h... 127.0.0.1:7003@17003 slave 1a2b... 0 0 4 connected

# count nodes by type
CLUSTER NODES | grep -c master
CLUSTER NODES | grep -c slave

# Redis 7.0+: shard view
CLUSTER SHARDS

CLUSTER KEYSLOT と COUNTKEYSINSLOT

キーがどのスロットへマッピングされるか示すのが(CRC16 % 16384)、CLUSTER KEYSLOT です。関連するキーを同じスロットへ強制するのが、ハッシュタグ({...})です。クラスタでのマルチキー操作(MGET、トランザクション、Lua スクリプト)には不可欠です。MOVED のリダイレクトを自動的に追うのが、redis-cli -c(クラスタモード)です。スロット内のキーを取得するのが(リシャーディング中に使われます)、CLUSTER GETKEYSINSLOT です。

redis-cli
# get the hash slot for a key
CLUSTER KEYSLOT mykey       # e.g., 1234
# CRC16(key) % 16384

# count keys in a specific slot (on the owning node)
CLUSTER COUNTKEYSINSLOT 1234

# get keys in a slot (must be run on the slot's owning node)
CLUSTER GETKEYSINSLOT 1234 10   # up to 10 keys

# in a cluster, keys must be on the same slot for multi-key ops
# use hash tags to force keys to the same slot:
SET {user:1}:profile "alice"
SET {user:1}:cart "items"
# both map to the same slot (the part inside {})

# CLUSTER KEYSLOT {user:1}:profile
# CLUSTER KEYSLOT {user:1}:cart
# same result -> same slot -> same shard

# if you access a key on the wrong node, you get a MOVED redirect:
# (error) MOVED 1234 127.0.0.1:7000
# redis-cli -c follows redirects automatically

ハッシュタグ

キーを同じスロットへ強制し、クラスタでマルチキーの操作を可能にするのが、ハッシュタグ({...})です。しかし賢明に使いましょう — 1 つのタグの乱用({users}:1、{users}:2 など)が、1 シャード上にホットスポットを作ります。アクセスパターンの周りで、ハッシュタグを設計しましょう:一緒にアクセスされるキーをグループ化し(ユーザーのデータ、注文のアイテム)、無関係なキーは分けましょう。これが、コアのクラスタのデータモデリングの課題です。

redis-cli
# hash tags: the substring inside {} determines the slot
# {user:1}:profile and {user:1}:cart share a slot

# enabling multi-key operations in a cluster:
MSET {user:1}:name "Alice" {user:1}:age 30   # OK (same slot)
MSET user:1:name "Alice" user:2:age 30       # CROSSSLOT error

# transactions across keys (must be same slot)
WATCH {order:1}:items
MULTI
HINCRBY {order:1}:items product:1 1
HINCRBY {order:1}:total 10
EXEC

# Lua scripts accessing multiple keys (all keys must share a slot)
EVAL "..." 2 {user:1}:a {user:1}:b

# design hash tags carefully:
# - too broad -> hotspots (one shard overloaded)
#   e.g., {users}:1, {users}:2 -> all on one shard (bad!)
# - too narrow -> can't do multi-key ops
#   e.g., user:1:a, user:1:b -> different slots (can't MGET)

# good: {user:1}:* groups one user's data on one shard
# bad:  {all-users}:* puts everyone on one shard

CLUSTER FAILOVER

プライマリが、cluster-node-timeout(デフォルト 15 秒)を超えて到達不能なとき、自動であるのが、クラスタのフェイルオーバーです。メンテナンスのためのものが(ダウンタイムゼロのアップグレード)、手動のフェイルオーバーです:優雅なのが(レプリケーションの同期を待つ)、FAILOVER で、同期をスキップするのが(より速い、わずかなデータ喪失のリスク)、FORCE、合意をバイパスするのが(緊急のみ、スプリットブレインのリスク)、TAKEOVER です。フェイルオーバー後、戻ったとき、レプリカになるのが、古いプライマリです。本番では、レプリカと共に必ず実行しましょう。

redis-cli
# when a primary fails, its replica is promoted automatically
# manual failover (for maintenance), run on the REPLICA:
redis-cli -p 7001 CLUSTER FAILOVER         # graceful (waits for sync)
redis-cli -p 7001 CLUSTER FAILOVER FORCE   # without primary agreement (faster)
redis-cli -p 7001 CLUSTER FAILOVER TAKEOVER # force, may split brain (emergency)

# graceful failover steps:
# 1. replica stops syncing from master
# 2. master stops accepting writes
# 3. replica catches up on replication offset
# 4. replica is promoted to master
# 5. cluster is updated with new master info
# 6. old master becomes a replica when it returns

# CLUSTER RESET resets a node (HARD removes all data)
CLUSTER RESET HARD
CLUSTER RESET SOFT

# check failover status
CLUSTER INFO | grep cluster_state

# rolling upgrade pattern:
# for each replica: CLUSTER FAILOVER (becomes master), upgrade old master

redis-cli --cluster ツール

複雑なクラスタ操作を扱うのが、redis-cli --cluster のツールです:作成、リシャーディング、再バランス、ノードの追加・削除、ヘルスチェック、修復です。変化後のクラスタ健康の検証の頼みの綱が、--cluster check です。軽微な問題(孤立したスロットなど)を自動修復するのが、--cluster fix です。すべてのノード上でコマンドを実行するのが、--cluster call です。運用タスクには、手動の CLUSTER コマンドの代わりに、これらを使いましょう。

redis-cli
# create a cluster (6 nodes: 3 primaries + 3 replicas)
redis-cli --cluster create \
  host1:7000 host2:7000 host3:7000 \
  host1:7001 host2:7001 host3:7001 \
  --cluster-replicas 1

# check cluster health
redis-cli --cluster check host1:7000

# repair issues
redis-cli --cluster fix host1:7000

# reshard (move slots between nodes)
redis-cli --cluster reshard host1:7000
# prompts for: how many slots, target node, source nodes

# rebalance slots across all nodes
redis-cli --cluster rebalance host1:7000

# add a new node
redis-cli --cluster add-node newhost:7000 host1:7000

# add a replica
redis-cli --cluster add-node newhost:7001 host1:7000 \
  --cluster-slave --cluster-master-id <nodeId>

# remove a node (migrates its slots first)
redis-cli --cluster del-node host1:7000 <nodeId>

# call a command on all nodes
redis-cli --cluster call host1:7000 INFO server
16

Sentinel(HA)

Sentinel のセットアップ

シャーディングなしの HA を提供するのが、Sentinel です。プライマリを監視し、失敗時にレプリカを昇格させ、クライアントを再設定します。プライマリが down に同意しなければならない sentinel の数が、(最後の数字の)クォーラムです。N sentinel のためには、(N/2)+1 に設定しましょう。フォールトトレランスのために、別々のマシン上に 3 sentinel をデプロイしましょう。ネットワークのジッターを超えるべきなのが、down-after-milliseconds です。低すぎると、誤ったフェイルオーバーが起きます。

redis-cli
# Sentinel monitors a primary + replicas, handles failover
# sentinel.conf (port 26379):
sentinel monitor mymaster 192.168.1.10 6379 2
# name, host, port, quorum (number of sentinels to agree on failure)

sentinel down-after-milliseconds mymaster 30000   # 30s to declare down
sentinel failover-timeout mymaster 180000         # 3min failover timeout
sentinel parallel-syncs mymaster 1                # replicas to resync in parallel

# start a sentinel:
redis-sentinel /etc/redis/sentinel.conf
# or:
redis-server /etc/redis/sentinel.conf --sentinel

# deploy at least 3 sentinels (odd number) for quorum
# sentinels communicate with each other and the Redis nodes

# connect to a sentinel to find the current primary:
redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster

# sentinel auto-discovers other sentinels and replicas

SENTINEL の masters と replicas

監視されるすべてのプライマリを列挙するのが、SENTINEL masters で、(num-slaves と num-other-sentinels を含む)詳細を与えるのが、SENTINEL master <name> です。レプリカを示すのが、SENTINEL replicas で、ピアの sentinel を示すのが、SENTINEL sentinels です。クォーラムのため十分な sentinel がいるか検証するのが、ckquorum です。モニタリングで実行しましょう。Sentinel をネイティブにサポートするのが、すべての主要な Redis クライアントライブラリです(現在のプライマリを見つけるため、sentinel をクエリします)。

redis-cli
# query sentinel state
redis-cli -p 26379 SENTINEL masters          # all monitored primaries
redis-cli -p 26379 SENTINEL master mymaster  # details of one primary
# fields: name, ip, port, runid, role, ...
#   num-slaves, num-other-sentinels
#   quorum, down-after-milliseconds
#   failover-timeout, parallel-syncs

# list replicas of a master
redis-cli -p 26379 SENTINEL replicas mymaster

# list other sentinels monitoring the same master
redis-cli -p 26379 SENTINEL sentinels mymaster

# count monitoring sentinels (should be >= quorum)
redis-cli -p 26379 SENTINEL sentinels mymaster | grep -c name

# check the number of OK sentinels
SENTINEL ckquorum mymaster
# "OK 3 usable Sentinels. Quorum and failover authorization can be reached"
# or "NOQUORUM" warning (not enough sentinels)

SENTINEL get-master-addr-by-name

現在のプライマリの IP とポートを返すのが、SENTINEL get-master-addr-by-name です。プライマリを発見し、その後接続するために、クライアントがこれを呼びます。フェイルオーバーのとき、新しいプライマリのアドレスを返すのが、sentinel です。フェイルオーバーを即座に知るため、クライアントが、+switch-master のイベントを購読すべきです。すべての主要な Redis クライアントライブラリの Sentinel モードに組み込まれているのが、この発見のパターンです。

redis-cli
# find the current primary address
redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster
# 1) "192.168.1.10"
# 2) "6379"

# clients use this to discover the current primary
# on failover, the sentinel returns the new primary's address

# clients should connect to sentinels, NOT directly to the primary
# libraries: redis-py, jedis, ioredis all support sentinel mode

# example client connection (pseudo-code):
# 1. connect to a sentinel
# 2. SENTINEL get-master-addr-by-name mymaster
# 3. connect to the returned primary
# 4. on connection error, repeat from step 1

# monitor for failover events
redis-cli -p 26379 SUBSCRIBE +switch-master
# publishes: mymaster 192.168.1.10 6379 192.168.1.11 6379

# other events:
redis-cli -p 26379 SUBSCRIBE +failover-state
redis-cli -p 26379 SUBSCRIBE +sdown
redis-cli -p 26379 SUBSCRIBE +odown

SENTINEL の failover

手動のフェイルオーバーをトリガーするのが(ローリングのアップグレード/メンテナンスのため)、SENTINEL failover です。プライマリが、down-after-milliseconds より長く down しているとき、自動のフェイルオーバーが起きます。自動ですが、短い書き込みの停止を引き起こします(秒です)。昇格させる最も新しいレプリカを選ぶのが、選出された sentinel のリーダーです。戻ったとき、レプリカになるのが、古いプライマリです。ネットワークの分離の間、受け付けた書き込みが LOST されます(スプリットブレインのリスク)。

redis-cli
# force a manual failover (for maintenance)
SENTINEL failover mymaster
# triggers failover: promotes a replica to primary

# the failover process:
# 1. sentinels mark primary SDOWN (subjectively down)
# 2. quorum agrees -> ODOWN (objectively down)
# 3. a sentinel is elected leader
# 4. leader picks the best replica (most up-to-date)
# 5. promotes the replica: REPLICAOF NO ONE
# 6. reconfigures other replicas to follow the new primary
# 7. updates sentinel configs with the new primary address
# 8. clients reconnect via sentinel discovery

# during failover, writes fail briefly (seconds)
# reads from replicas continue (if the app uses them)

# the old primary, when it returns, is reconfigured as a replica
# of the new primary (its writes during partition are lost)

# monitor failover events:
redis-cli -p 26379 SUBSCRIBE +switch-master
redis-cli -p 26379 SUBSCRIBE +failover-*

Sentinel のクォーラムとモニタリング

フェイルオーバーをトリガーする前に、プライマリが down に同意しなければならない sentinel の数が、クォーラムです。N sentinel のために、多数派(N/2+1)へ設定しましょう。十分にいるか検証するのが、ckquorum です。ネットワークのジッターを超えるべきなのが、down-after-milliseconds です(安全なのが 30 秒です)。フェイルオーバーの duration に上限を設けるのが、failover-timeout です。同時に再同期するレプリカの数を制御するのが(1 = 安全だが遅い)、parallel-syncs です。トポロジの変化のとき、設定を自動更新するのが、Sentinel です。

redis-cli
# quorum: number of sentinels that must agree a master is down
# set in sentinel monitor command:
sentinel monitor mymaster 192.168.1.10 6379 2
#                                          ^ quorum = 2

# for 3 sentinels: quorum = 2 (majority)
# for 5 sentinels: quorum = 3 (majority)

# check quorum status
SENTINEL ckquorum mymaster
# "OK 3 usable Sentinels" or "NOQUORUM"

# tune down-after-milliseconds (time before declaring down)
sentinel down-after-milliseconds mymaster 30000   # 30s default

# tune failover-timeout (max time for failover to complete)
sentinel failover-timeout mymaster 180000   # 3min default

# parallel-syncs: how many replicas resync simultaneously
sentinel parallel-syncs mymaster 1   # 1 at a time (safe, slow)

# view sentinel configuration
SENTINEL masters
SENTINEL master mymaster

# reset a master's state (clears discovered replicas/sentinels)
SENTINEL reset mymaster

# Sentinel automatically updates its config file when topology changes
17

モニタリング

MONITOR のコマンド

すべてのクライアントからのすべてのコマンドをリアルタイムにストリーミングするのが、MONITOR です。出力の形式が、timestamp [db client_addr] "command" "args" です。アプリが実際に送るコマンドのデバッグには非常に有用です。しかし、スループットをおおよそ半減させるため — ステージング/dev でか、短い本番のデバッグのためだけに使いましょう。特定のパターンのために grep でフィルタしましょう。本番のモニタリングには、代わりに SLOWLOG、INFO commandstats、か LATENCY MONITOR を。

redis-cli
# MONITOR: real-time log of ALL commands (debugging only!)
MONITOR
# every command from every client is printed:
# 1700000000.123456 [0 10.0.0.1:12345] "SET" "key" "value"
# 1700000000.123567 [0 10.0.0.1:12345] "GET" "key"

# format: <unix_time> [<db> <addr>] "<cmd>" "<arg>" ...
# the [0 ...] shows which database and client

# to stop monitoring: Ctrl+C or send any command

# filter for specific patterns (in another terminal):
redis-cli MONITOR | grep "SET"
redis-cli MONITOR | grep "10.0.0.1"
redis-cli MONITOR | grep -E "(SET|DEL)"

# WARNING: MONITOR roughly halves throughput
# use only for debugging, never in production

# safer alternatives:
# - SLOWLOG (only slow commands)
# - INFO commandstats (command frequency)
# - LATENCY MONITOR (latency events)

LATENCY のモニタリング

イベントタイプごとにレイテンシのスパイクを追跡するのが、LATENCY MONITOR です。しきい値を設定すれば(例:100ms)、それを超えるイベントを Redis が記録します。最近のイベントを分析し修正を提案するのが、LATENCY DOCTOR です。診断の素晴らしい出発点です。ASCII のタイムラインを示すのが、LATENCY GRAPH です。よくある犯人:「fork」(大きな dataset 上の BGSAVE)、「expire-cycle」(大規模な有効期限)、「aof-fsync-always」(AOF の fsync)です。しきい値をあなたの SLO へ設定し、定期的に監視しましょう。

redis-cli
# enable latency monitoring (threshold in ms)
CONFIG SET latency-monitor-threshold 100   # 100ms

# view recent latency events
LATENCY LATEST
# event, timestamp, last latency, max latency

# history of an event
LATENCY HISTORY command
LATENCY HISTORY expire-cycle
LATENCY HISTORY fork

# ASCII art graph
LATENCY GRAPH command

# human-readable diagnosis and recommendations
LATENCY DOCTOR

# reset latency data
LATENCY RESET
LATENCY RESET command

# common events:
#   command         slow commands (over threshold)
#   fast-command    slow O(1)/O(log N) commands
#   expire-cycle    key expiration sweep too slow
#   fork            BGSAVE/BGREWRITEAOF fork delay
#   aof-fsync-always  AOF fsync delay
#   unlink          async delete delay

# check threshold
CONFIG GET latency-monitor-threshold

MEMORY DOCTOR と STATS

1 つのキーのバイトを報告するのが、MEMORY USAGE です(完全な精度のためには SAMPLES 0)。詳細なアロケータの統計を与えるのが、MEMORY STATS です。自動化された診断を提供するのが(断片化、大きいキーなどを探します)、MEMORY DOCTOR です。見るべきもの:mem_fragmentation_ratio です。>1.5 がメモリを浪費し(断片化)、<1 が、Redis がスワップしていることを意味します(レイテンシには破滅的です)。OS へメモリを返すのを試みるのが、MEMORY PURGE です。断片化したメモリを自動的に取り戻すのが(4.0+)、active defrag です。

redis-cli
# MEMORY USAGE: bytes used by a single key
MEMORY USAGE mykey
MEMORY USAGE bigset SAMPLES 0   # exact (default samples for large keys)

# MEMORY STATS: detailed allocator stats
MEMORY STATS

# MEMORY DOCTOR: automated memory diagnosis
MEMORY DOCTOR

# MEMORY MALLOC-STATS: low-level allocator stats (jememalloc)
MEMORY MALLOC-STATS

# check total memory used
INFO memory | grep used_memory_human

# key metrics to watch:
#   used_memory             logical bytes used
#   used_memory_rss         RSS from OS (real footprint)
#   used_memory_peak        peak usage
#   mem_fragmentation_ratio >1.5 = fragmentation, <1 = swapping (bad!)

# MEMORY PURGE: attempt to free memory back to OS
MEMORY PURGE

# active defragmentation (4.0+)
CONFIG SET activedefrag yes

DEBUG のコマンド

診断とテストのためのものが、DEBUG のコマンドです。注意して使いましょう。アプリがレイテンシをどう扱うかテストするのが(サーバーをブロックする)、DEBUG SLEEP です。キーの内部のエンコーディングと refcount を明らかにするのが、DEBUG OBJECT です。dataset の保存、消去、再ロードを行うのが(永続化のテストに有用)、DEBUG RELOAD です。強力ですが危険であるため、本番では ACL により制限しましょう(-@admin か -@dangerous のカテゴリです)。影響を理解せず、本番のプライマリ上で DEBUG を決して実行しないこと。

redis-cli
# DEBUG SLEEP: block the server for N seconds (testing only!)
DEBUG SLEEP 2             # blocks for 2 seconds (testing latency)

# DEBUG OBJECT: raw internal info about a key
DEBUG OBJECT mykey
# Value at:0x7f... refcount:1 encoding:embstr serializedlength:12 ...

# DEBUG SET-ACTIVE-EXPIRE: toggle expiration sweeps
DEBUG SET-ACTIVE-EXPIRE 0  # disable expiration sweeps (debugging)
DEBUG SET-ACTIVE-EXPIRE 1  # re-enable

# DEBUG JMAP: memory map (jemalloc)
DEBUG JMAP

# DEBUG CHANGE-REPL-ID: change replication ID (advanced)
DEBUG CHANGE-REPL-ID

# DEBUG RELOAD: save RDB, flush, reload from RDB (testing)
DEBUG RELOAD

# DEBUG LOADAOF: reload from AOF (testing)
DEBUG LOADAOF

# WARNING: DEBUG commands can be dangerous
# use ACL to restrict them in production:
# ACL SETUSER default -@admin

redis-cli --latency

ラウンドトリップタイムを継続的に測るのが、redis-cli --latency です。ネットワークのパフォーマンスの基準線を引くには不可欠です。15 秒ごとに rolling 統計をログするのが、--latency-history です(変えるのが、-i です)。ヒストグラムを示すのが(ジッターとテールレイテンシを可視化します)、--latency-dist です。クラスタモードでは、各ノードへのレイテンシを個別に確認しましょう。基準線を引き、その後、スパイクを監視しましょう。localhost で >1ms のレイテンシが、問題(CPU、メモリ圧迫、遅いコマンド)を示します。

redis-cli
# continuous latency measurement (round-trip time)
redis-cli --latency
# output: min: 0, max: 1, avg: 0.27 (3421 samples)

# latency history (rolling, every N seconds)
redis-cli --latency-history
# default interval: 15 seconds
# output: min: 0, max: 2, avg: 0.31 (1500 samples) -- 15.01 seconds

# custom interval (1 second)
redis-cli --latency-history -i 1

# latency distribution (histogram)
redis-cli --latency-dist
# shows a visual histogram of latency distribution

# latency to a remote host
redis-cli -h remote-host --latency

# use cases:
# - baseline your network latency
# - detect network issues (jitter, spikes)
# - compare latency before/after config changes
# - monitor latency over time with --latency-history

# for cluster mode, check latency to each node:
redis-cli -h node1 -p 7000 --latency &
redis-cli -h node2 -p 7000 --latency &

redis-cli --stat

Redis の「top」のようなのが、redis-cli --stat です。keys、memory、clients、blocked clients、requests/sec、connections の、更新される要約を示します。リクエストの隣の(+N)が、最後のサンプルからの差分を示します。素早いヘルスチェックと、異常の発見(成長するメモリ、漏れるクライアント、スパイクするリクエストレート)に使いましょう。BGSAVE/BGREWRITEAOF の子が動いているか示すのが、「child」の列です。

redis-cli
# --stat: continuous server stats (like top for Redis)
redis-cli --stat
# output (refreshes every second):
# ------- data ------ --------------------- load -------------------- - child -
# keys       mem      clients blocked requests            connections
# 1000       1.50M    50      0       12345 (+12)         1000

# --stat shows:
#   keys       total keys in the db
#   mem        memory usage
#   clients    connected clients
#   blocked    blocked clients (BLPOP, etc.)
#   requests   total requests (+N since last sample)
#   connections total connections since start
#   child      child process info (BGSAVE/BGREWRITEAOF)

# custom interval (every 5 seconds)
redis-cli --stat -i 5

# monitor a remote server
redis-cli -h host --stat

# use cases:
# - quick health check (are clients/memory/keys growing?)
# - spot traffic spikes (requests/second)
# - monitor during load tests
# - detect connection leaks (clients increasing steadily)

# combine with --no-raw for machine-readable output
18

セキュリティ

AUTH(レガシーのパスワード)

レガシーの単一パスワードの認証であるのが(Redis 6 以前)、AUTH です。Redis 6+ では、ACL のユーザーを使いましょう(AUTH username password)。シェルの履歴でパスワードを露出するのが、-a のフラグです。REDISCLI_AUTH の環境変数を推奨しましょう。強いパスワードを必ず使いましょう(ランダムな 64+ 文字)。本番では、多層防御のために、AUTH と TLS、ネットワークの制限(bind/firewall)、ACL ベースの最小特権を組み合わせましょう。

redis-cli
# set a password (simple, legacy)
CONFIG SET requirepass "strongpassword"

# authenticate (legacy, before Redis 6)
AUTH "strongpassword"
# OK

# authenticate as a specific user (Redis 6+ ACL)
AUTH appuser "secretpassword"
# OK

# connect with password via CLI
redis-cli -a "strongpassword"
redis-cli -a "strongpassword" --no-auth-warning  # suppress warning

# safer: use environment variable
export REDISCLI_AUTH="strongpassword"
redis-cli   # reads REDISCLI_AUTH automatically

# remove password
CONFIG SET requirepass ""

# AUTH returns ERR if the password is wrong
# after AUTH, all commands work normally

ACL SETUSER

単一パスワードのモデルを置き換えるのが、Redis 6+ の ACL です。スコープ付きの権限でユーザーを作りましょう。構文:on(有効)、>password、~pattern(キーのパターン)、+command/-command、+@category/-@category(例:+@read、-@dangerous)です。各アプリのための最小特権のユーザーを必ず作りましょう。常に存在するのが、デフォルトのユーザーです。強いパスワードを設定するか制限しましょう。永続化のため、ACL をファイルへ保存するのが、ACL SAVE です。

redis-cli
# Redis 6+: ACL system with users and permissions
# create a user with limited access
ACL SETUSER appuser on >secretpassword ~app:* +get +set +del -@dangerous
# on = enabled
# >password = set password
# ~pattern = key patterns this user can access
# +command = allowed commands
# -command = denied commands
# +@category / -@category = allow/deny command categories

# categories: @read, @write, @admin, @dangerous, @keyspace, @connection, etc.

# create a read-only user
ACL SETUSER readonly on >pass ~* +@read -@dangerous

# create an admin user
ACL SETUSER admin on >adminpass ~* +@all

# create a user for a specific app (restricted keys)
ACL SETUSER app1 on >pass ~app1:* +@read +@write +@connection -@dangerous

# the default user (always exists)
ACL SETUSER default on >defaultpass ~* +@all -@dangerous

ACL LIST と GETUSER

コンパクトなルール形式ですべてのユーザーを示すのが、ACL LIST です。1 ユーザーの詳細な権限を与えるのが、ACL GETUSER です(ハッシュ化されたパスワード、許可/拒否されたコマンド、キーのパターンを含みます)。現在のユーザーを返すのが、ACL WHOAMI です。拒否されたコマンドと認証の失敗を記録するのが、ACL LOG(7.0+)です。セキュリティ監査に有用です。再起動をまたぐ永続化のために、ACL ファイルを管理するのが、ACL SAVE/LOAD です。

redis-cli
# list all users (compact rules)
ACL LIST
# 1) "user default on nopass ~* +@all"
# 2) "user appuser on #abc123... ~app:* +get +set +del -@dangerous"

# view a user's detailed permissions
ACL GETUSER appuser
# flags, passwords, commands, keys, channels, selectors

# view current user
ACL WHOAMI
# "appuser"

# view all users (just names, 7.0+)
ACL USERS

# delete a user
ACL DELUSER appuser

# save ACLs to a file (persists across restarts)
ACL SAVE

# reload ACLs from file
ACL LOAD

# aclfile in redis.conf:
#   aclfile /etc/redis/users.acl

# view current user's rules
ACL LOG        # security audit log (7.0+)
ACL LOG RESET  # clear the audit log

ACL WHOAMI と DELUSER

現在のユーザーを識別するのが、ACL WHOAMI です。ユーザーを取り除くのが、ACL DELUSER です(そのアクティブな接続も切断します)。ルールを削除せず一時的に無効化するのが、ユーザーの「off」への設定です。アクセスの停止に有用です。セキュリティイベント(拒否されたコマンド、失敗した認証)を記録するのが、ACL LOG です。不審な活動のために、監視しましょう。ACL SETUSER >newpass で、定期的にパスワードをローテーションしましょう。

redis-cli
# get the current authenticated user
ACL WHOAMI
# "appuser"

# switch user (re-authenticate)
AUTH adminuser "adminpass"
ACL WHOAMI
# "adminuser"

# delete a user (disconnects their clients)
ACL DELUSER tempuser

# temporarily disable a user (keeps the rules, blocks login)
ACL SETUSER appuser off
# the user cannot authenticate, but their rules are preserved
# re-enable:
ACL SETUSER appuser on

# rotate a user's password
ACL SETUSER appuser >newpassword

# remove a user's password
ACL SETUSER appuser <secretpassword  # remove this password
# or remove all passwords:
ACL SETUSER appuser resetpass

# view the audit log (denied commands, auth failures)
ACL LOG
ACL LOG COUNT 5  # last 5 entries
ACL LOG RESET    # clear the log

rename-command(コマンドの無効化)

危険なコマンドを無効化・改名するのが、rename-command です(redis.conf 内)です。無効化するには "" を、改名するには文字列を。再起動を要求します(実行時変更可能ではありません)。実行時変更可能でユーザーごとなのが、(-flushall、-@dangerous の)ACL です。Redis 6+ ではこちらを推奨しましょう。制限する価値のあるコマンド:FLUSHALL/FLUSHDB(データ喪失)、KEYS(サーバーをブロック)、CONFIG(セキュリティ)、DEBUG(クラッシュし得る)、SHUTDOWN(サーバーを停止)です。

redis-cli
# rename or disable dangerous commands (in redis.conf)
rename-command FLUSHALL ""
rename-command FLUSHDB ""
rename-command CONFIG "CONFIG_9f8a7b"
rename-command KEYS ""
rename-command DEBUG ""
rename-command SHUTDOWN "SHUTDOWN_7x9y"

# "" completely disables the command (returns error)
# a string renames it (must use the new name)

# Redis 6+: prefer ACLs instead of rename-command
# ACL SETUSER default -flushall -config -keys -@dangerous

# view available commands (after rename/restrictions)
COMMAND

# note: rename-command requires a restart (not changeable at runtime)
# ACLs are runtime-changeable and more flexible

# dangerous commands to restrict:
#   FLUSHALL, FLUSHDB  - delete all data
#   KEYS               - blocks server
#   CONFIG             - can change security settings
#   DEBUG              - can crash the server
#   SHUTDOWN           - stops the server
#   MONITOR            - performance impact

TLS/SSL の暗号化

転送中のデータを暗号化するのが、TLS です。本番には、信頼できないネットワークの上では特に、不可欠です。ネイティブに TLS をサポートするのが、Redis 6+ です。クライアントに証明書の提示を要求するのが、mTLS(tls-auth-clients yes)です。パスワードなしで、相互認証を提供します。クラスタ/sentinel のためには、ノード間通信の TLS も有効化しましょう。平文を無効化するのが、ポート 0 です。移行の間、両方のポートを一時的に実行しましょう。本番では、適切な CA 署名の証明書を必ず使いましょう。

redis-cli
# enable TLS in redis.conf (Redis 6+)
port 0                       # disable plain-text port
tls-port 6379
tls-cert-file /etc/redis/redis.crt
tls-key-file /etc/redis/redis.key
tls-ca-cert-file /etc/redis/ca.crt

# connect with TLS
redis-cli --tls --cert client.crt --key client.key \
  --cacert ca.crt -h host -p 6379

# mutual TLS (mTLS) for client authentication
tls-auth-clients yes         # require client certs
tls-auth-clients no          # don't require (default)
tls-auth-clients optional    # verify if provided

# TLS for cluster and replication
tls-cluster yes              # TLS between cluster nodes
tls-replication yes          # TLS between primary/replica

# mix TLS and plain text (transition period)
# port 6380
# tls-port 6379

# generate self-signed certs for testing:
# openssl req -x509 -newkey rsa:4096 -keyout redis.key \
#   -out redis.crt -days 365 -nodes
19

データのインポートとエクスポート

redis-cli --rdb(バックアップ)

オンラインバックアップを行うのが、redis-cli --rdb です。サーバーのファイルシステムに直接触れず、RDB をファイルへストリーミングします。ノンブロッキングであり(BGSAVE の背景の fork を使い)、本番に安全です。SSH と組み合わせれば、リモートの Redis をローカルのファイルへバックアップできます。redis-check-rdb でバックアップを検証しましょう。cron 経由で定期的なバックアップをスケジュールしましょう。リストアの手順を必ずテストしましょう — テストされていないバックアップはバックアップではありません。

redis-cli
# dump the RDB snapshot to a file (online backup)
redis-cli --rdb /backup/dump.rdb
# Output: RDB file written to /backup/dump.rdb

# dump RDB to a remote host's file (via SSH):
ssh remote-host "redis-cli --rdb /tmp/dump.rdb"

# the --rdb flag:
# - connects to Redis and requests a BGSAVE
# - streams the RDB to the specified file
# - non-blocking (uses the background fork)
# - safe to run on a production server

# verify the RDB file
redis-check-rdb /backup/dump.rdb

# restore: stop Redis, replace dump.rdb, restart
redis-cli SHUTDOWN
cp /backup/dump.rdb /var/lib/redis/dump.rdb
redis-server /etc/redis/redis.conf

# schedule regular backups:
# 0 2 * * * redis-cli --rdb /backup/dump-$(date +\%F).rdb

redis-cli --pipe(マッサ挿入)

Redis への一括データロードの最も速い方法が、redis-cli --pipe です。生の RESP をストリーミングし、最後までリプライを待ちません。printf かスクリプトで RESP を生成しましょう。エラーと合計のリプライを報告するのが、--pipe です。より単純/小さいロードのためには、(echo | redis-cli の)テキストコマンドのパイプが機能しますが、より遅いです。必ずベンチマークしましょう:数分で数百万のキーをロードできます。大きなロードの間、メモリに注意しましょう。

redis-cli
# --pipe: bulk load raw RESP data (fastest method)
# generate RESP and pipe it:

# example: bulk SET commands (bash)
for i in $(seq 1 100000); do
  printf '*3\r\n$3\r\nSET\r\n$%d\r\nkey:%d\r\n$%d\r\nvalue%d\r\n' \
    $((4 + ${#i})) $i $((5 + ${#i})) $i
done | redis-cli --pipe

# simpler text mode (slower but easier):
for i in $(seq 1 100000); do
  echo "SET key:$i value$i"
done | redis-cli

# --pipe mode output:
# All data transferred. Waiting for the last reply...
# Last reply received from server.
# errors: 0, replies: 100000

# prepare RESP from a CSV/data file:
# (each line: key,value)
while IFS=, read -r key value; do
  printf '*3\r\n$3\r\nSET\r\n$%d\r\n%s\r\n$%d\r\n%s\r\n' \
    ${#key} "$key" ${#value} "$value"
done < data.csv | redis-cli --pipe

DUMP と RESTORE

キーの値をバイナリの blob へシリアライズするのが、DUMP です(タイプと値を含みますが、TTL は含みません — RESTORE でミリ秒の TTL を指定しましょう)。それをキーへデシリアライズするのが、RESTORE で、異なる Redis インスタンスをまたいで機能します(移行に最適です)。バージョン固有であるのが、シリアライズされた形式です。Redis 4.x からの blob が、7.x でロードされないことがあるため、互換性を必ず検証しましょう。インスタンス内のコピーには、DUMP+RESTORE より、ネイティブの COPY のコマンド(6.2+)を推奨しましょう。

redis-cli
# DUMP: serialize a key's value (binary blob)
DUMP mykey
# returns a serialized blob (binary, includes type + value + TTL info)

# RESTORE: deserialize into a key
RESTORE newkey 0 <serialized_blob>
# 0 = no TTL (milliseconds); set a TTL otherwise
RESTORE newkey 3600000 <blob>   # 1 hour TTL
RESTORE newkey 0 <blob> REPLACE  # overwrite if exists

# copy a key (6.2+ does this natively with COPY)
# manual copy via DUMP + RESTORE:
SET source "value"
blob = DUMP source
RESTORE dest 0 blob

# DUMP/RESTORE preserve the type but NOT the TTL
# (TTL must be specified in RESTORE)

# DUMP/RESTORE work across different Redis instances
# (migrate data between servers)

# note: serialized format is version-specific
# a blob from Redis 4.x may not load in 7.x — verify compatibility

# use COPY (6.2+) instead for in-instance copies:
COPY source dest                # copy without TTL
COPY source dest REPLACE        # overwrite destination
COPY source dest DB 1           # copy to another database
COPY source dest REPLACE DB 1   # both

MIGRATE(サーバー間の移動)

Redis インスタンス間で、キーをアトミックに移動(かコピー)するのが、MIGRATE です。キーが決して両方の場所に同時にいません(アトミックです)。クラスタのリシャーディングの積み木です。ソースキーを保つのが、COPY で、デフォルトが削除です。既存の宛先キーを上書きするのが、REPLACE です。複数のキーのためには、キーとして空文字列を渡し、KEYS で列挙しましょう。大きな値のため、タイムアウトを十分に高く設定しましょう。転送の間、両端でブロックするのが、MIGRATE です。

redis-cli
# MIGRATE: atomically move a key from one Redis to another
# syntax: MIGRATE host port key|"" dest-db timeout [COPY] [REPLACE]
#         [AUTH password] [KEYS key1 key2 ...]

# move a single key (default: deletes from source after copy)
MIGRATE 192.168.1.20 6379 mykey 0 5000
# host, port, key, dest-db, timeout-ms

# copy without deleting from source
MIGRATE 192.168.1.20 6379 mykey 0 5000 COPY

# overwrite if the key exists on destination
MIGRATE 192.168.1.20 6379 mykey 0 5000 REPLACE

# migrate multiple keys (pass "" as the key, then KEYS ...)
MIGRATE 192.168.1.20 6379 "" 0 5000 KEYS key1 key2 key3

# authenticate with the destination
MIGRATE 192.168.1.20 6379 mykey 0 5000 AUTH destpassword

# MIGRATE is atomic: the key appears on exactly one instance at any moment
# timeout is in milliseconds — large keys need longer timeouts
# returns NOKEY if the key doesn't exist on source

COPY(インスタンス内のコピー)

同じインスタンス内で、キーをアトミックに複製するのが、COPY(6.2+)です。DUMP+RESTORE よりはるかに単純です。デフォルトでは TTL をコピーし「ません」(後で EXPIRE を使いましょう)。DB のオプション付きで、データベースをまたいで機能するのが、COPY です。既存の宛先を上書きするのが、REPLACE です。インスタンスをまたぐコピーのためには、(ネットワークをまたいでアトミックな)MIGRATE を使うしましょう。インスタンス内の複製のための、DUMP+RESTORE のパターンのモダンな置き換えが、COPY です。

redis-cli
# COPY: duplicate a key within the same instance (6.2+)
COPY source dest               # copy value (no TTL by default)
COPY source dest REPLACE       # overwrite destination if it exists
COPY source dest DB 1          # copy to another database
COPY source dest REPLACE DB 1  # both options

# before COPY existed, you needed DUMP + RESTORE:
SET src "hello"
blob = DUMP src
RESTORE dst 0 blob

# COPY preserves the type (string, list, hash, ...)
SET mystr "hello"
COPY mystr mystr_copy
TYPE mystr_copy               # "string"

# COPY does NOT copy TTL by default — use after EXPIRE if needed
SET temp "data" EX 3600
COPY temp temp_copy
TTL temp_copy                 # -1 (no TTL)
EXPIRE temp_copy 3600         # set TTL manually

# COPY is atomic and never blocks (unlike DUMP on huge keys)

redis-check-rdb と redis-check-aof

永続化ファイルの整合性を検証するのが、redis-check-rdb と redis-check-aof です。リストアの前に、バックアップ上で必ず実行しましょう。不完全な末尾を取り除くことで、切り詰められた AOF から回復するのが、redis-check-aof --fix です(確認を求めます)。マルチパートの AOF を使うのが(ベース + 段階的なもの)、Redis 7 で、manifest ファイルを確認しましょう。--fix を除き読み取り専用であるため、いつでも安全に実行できます。バックアップを確実に検証しましょう — 検証されていないバックアップはバックアップではありません。

redis-cli
# verify the integrity of an RDB file (offline, safe)
redis-check-rdb /var/lib/redis/dump.rdb
# outputs: [offset] Checksum OK | CRC error | file truncated

# verify an AOF file
redis-check-aof /var/lib/redis/appendonly.aof
# outputs: AOF analyzed: size=... ok_up_to=... ok_up_to_line=...

# fix a truncated AOF (interactive prompt)
redis-check-aof --fix /var/lib/redis/appendonly.aof

# Redis 7 multi-part AOF: check the manifest
redis-check-aof --manifest /var/lib/redis/appendonlydir/appendonly.aof.manifest

# truncate an RDB to a specific offset (recovery)
redis-check-rdb --fix /var/lib/redis/dump.rdb

# use cases:
# - verify a backup before restore
# - diagnose corruption after a crash
# - recover from a truncated AOF (removes the incomplete tail)
# - validate files copied across servers

# always run these checks BEFORE replacing production data files
20

パフォーマンステスト

redis-benchmark の基本

Redis の組み込みの負荷テストツールが、redis-benchmark です。同時クライアントをシミュレートし、スループット(requests/sec)とレイテンシのパーセンタイルを報告します。テストを選ぶのが、-t です(PING、SET、GET、INCR など)、リクエスト数を設定するのが、-n、ペイロードサイズを設定するのが、-d です。パフォーマンスの基準線を引くため、本番同等のハードウェア上で必ずベンチマークしましょう。出発点が、デフォルトの 50 の並列クライアントです。本物のワークロードに合わせ、-c を調整しましょう。影響を測るため、設定変化の前後にベンチマークを実行しましょう。

redis-cli
# redis-benchmark: built-in performance benchmarking tool
# runs commands against a Redis server and reports throughput/latency

# default benchmark (50 parallel clients, 100000 requests)
redis-benchmark
# default commands: PING, SET, GET, INCR, LPUSH, RPUSH, LPOP, RPOP,
#   SADD, HSET, SPOP, ZADD, ZPOPMIN, LRANGE_100, LRANGE_300, ...

# run a specific command only
redis-benchmark -t set,get -n 100000
# -t = test (comma-separated commands)
# -n = number of requests

# test a specific command with custom data
redis-benchmark -t set -n 100000 -d 100
# -d = data size in bytes (default 3)

# output example:
# ====== SET ======
#   100000 requests completed in 0.85 seconds
#   50 parallel clients
#   3 bytes payload
#   keep alive: 1
#   98.90% <= 1 milliseconds
#   100.00% <= 1 milliseconds
#   117647.05 requests per second

# run against a remote server with auth
redis-benchmark -h host -p 6379 -a password -t set,get -n 100000

パイプラインと同時実行のチューニング

2 つの最大のスループットのレバーが、-c(同時実行)と、-P(パイプラインのサイズ)です。並列クライアントを増やすのが、-c です(より多くの in-flight リクエスト)。ラウンドトリップごとにコマンドをバッチ化するのが、-P です(より少ないネットワークのオーバーヘッド)。組み合わせれば、スループットが 10〜20 倍に押し上げられます。純粋なレイテンシを測るのが、シングルクライアント(-c 1)のベンチマークで、スループットを測るのが、マルチクライアントです。ネットワーク帯域へボトルネックを移すのが、大きいペイロード(-d)です。本物のクライアントライブラリの挙動に合わせ、-c/-P を必ず調整しましょう。

redis-cli
# -c = number of parallel connections (clients)
redis-benchmark -t set -n 100000 -c 50     # default: 50 clients
redis-benchmark -t set -n 100000 -c 200    # 200 concurrent clients
redis-benchmark -t set -n 100000 -c 1      # single client (latency focus)

# -P = pipeline size (commands per round-trip)
redis-benchmark -t set -n 100000 -P 1      # no pipelining (baseline)
redis-benchmark -t set -n 100000 -P 16     # pipeline 16 commands
redis-benchmark -t set -n 100000 -P 100    # pipeline 100 commands

# combine -c and -P for max throughput
redis-benchmark -t set -n 100000 -c 50 -P 16

# typical results (localhost, small values):
#   -c 1  -P 1   -> ~100k req/s  (latency-bound)
#   -c 50 -P 1   -> ~600k req/s  (concurrency)
#   -c 50 -P 16  -> ~2M req/s    (pipelining)

# test with a larger payload (network-bound)
redis-benchmark -t set -n 100000 -d 1024   # 1KB values
redis-benchmark -t set -n 100000 -d 65536  # 64KB values

レイテンシのパーセンタイルと CSV 出力

平均だけでなく、レイテンシのパーセンタイル(P50、P99、P99.9)を必ず見ましょう。ユーザー体験を損なう、テールレイテンシのスパイクを隠すのが、平均です。P50 より 5 倍悪い P99 が、ジッター(GC、ネットワーク、遅いコマンド)を示します。時間をかけたトレンドの追跡のために、機械可読な結果を出力するのが、--csv です。影響を客観的に測るため、設定変化の前後にベンチマークを保存しましょう。P99 のレイテンシと requests/sec を一緒に追跡しましょう — 片方をもう片方を代償に最適化するのが、よくある罠です。

redis-cli
# --csv: CSV output (easy to parse / log)
redis-benchmark -t set,get -n 100000 --csv
# output: "test","rps","avg_latency_ms","min_latency_ms",...
# "SET","117647.05","0.284","0.144"
# "GET","125000.00","0.272","0.136"

# --precision: set decimal places for latency
redis-benchmark -t set -n 100000 --precision 4

# latency percentiles (Redis 6+):
# the default output shows "X% <= Y milliseconds" lines
# ====== SET ======
#   50.00% <= 0.239 milliseconds
#   99.00% <= 0.511 milliseconds
#   99.90% <= 1.023 milliseconds
#   100.00% <= 1.519 milliseconds

# focus on tail latency (P99, P99.9) — average hides outliers
# P99 > 5x P50 indicates jitter or GC pauses

# save results to a file for comparison
redis-benchmark -t set,get -n 100000 --csv > bench-$(date +%F).csv

# compare two runs (before/after a config change)
diff bench-2025-01-01.csv bench-2025-01-02.csv

クラスタと Lua のベンチマーク

キーをクラスタのスロットをまたいで分散するのが、--cluster モードです。現実的なクラスタのベンチマークには不可欠です(シングルノードのベンチマークが、クロススロットのルーティングのオーバーヘッドを見逃します)。ランダムキースペースのサイズを設定するのが、-r です(すべての操作が 1 キーに当たるのを避け、メモリ内のキャッシュ経由で数字が膨らむのを避けるため、大きい値を使いましょう)。Lua スクリプトをベンチマークするのが、--eval です。ベンチマークの複数スレッドを使うのが、--threads(Redis 6+)で、1 スレッドがサーバーを飽和させるのに十分な負荷を作れないときに有用です。現実的な数字のため、必ず -r を。

redis-cli
# benchmark a Redis Cluster (redis-benchmark supports cluster mode)
redis-benchmark --cluster -h node1 -p 7000 -t set,get -n 100000
# automatically distributes keys across cluster slots

# cluster mode with multiple nodes
redis-benchmark --cluster -h node1 -p 7000 -h node2 -p 7000 \
  -t set,get -n 100000 -c 50

# benchmark a Lua script (--eval)
redis-benchmark -n 100000 eval "return redis.call('SET', KEYS[1], ARGV[1])" 0 mykey hello
# note: key and args are positional after the script

# benchmark with random keys (--random-data + keyspace length)
redis-benchmark -t set -n 100000 -r 1000000
# -r 1000000 = random keys from a 1M keyspace (SET key:RAND_INT value)
# avoids hitting the same key (tests real-world distribution)

# use a random payload (not the same bytes each time)
redis-benchmark -t set -n 100000 -r 1000000 -d 100 --random-data

# only run the benchmark for a fixed time (seconds)
redis-benchmark -t set --threads 4 -n 100000
# --threads (6+) uses multiple threads (default 1, doesn't help single-core)

--idle とウォームアップ

PING だけで、純粋な接続/ネットワークのオーバーヘッドを測るのが、--idle です。打ち破れない基準線です。測定の前に、サーバーを必ずウォームアップしましょう(コールドキャッシュが性能を過小評価します):まず使い捨てのベンチマークを実行し、その後、測定するものを。継続的に動くのが(持続負荷のテストに有用)、--loop です。ランダムキースペースを再現可能にするのが、--seed です。A/B の比較には不可欠です。データベースを選ぶのが、--dbnum です(ベンチマークの間、本番データの汚染を避けるため、別の db を使うしましょう)。

redis-cli
# --idle: only send PINGs (no commands) — measure pure connection overhead
redis-benchmark -t ping -n 100000 --idle
# useful for measuring connection / network baseline latency

# --dbnum: select a specific database
redis-benchmark -t set -n 100000 --dbnum 1

# --clients: same as -c (alias)
redis-benchmark -t set -n 100000 --clients 100

# warm up the server before measuring (avoid cold-start bias)
redis-benchmark -t set -n 10000   # warmup run (discard results)
redis-benchmark -t set -n 100000  # measured run

# --loop: run the benchmark forever (Ctrl+C to stop)
redis-benchmark -t set -n 100000 --loop

# --seed: reproducible random keys (same -r sequence every run)
redis-benchmark -t set -n 100000 -r 1000000 --seed 42

# benchmark with a specific client socket buffer
redis-benchmark -t set -n 100000 --numdatadb 1

ベンチマークの解釈と落とし穴

数字を非現実的に膨らませるのが、ベンチマークの落とし穴です:(1) localhost 専用のベンチマークがネットワークレイテンシを見逃します。(2) -r なしでは、すべての操作が 1 キーに当たり(キャッシュにより膨らみます)。(3) 小さいペイロードが、メモリ/ネットワークを強制しません。(4) 永続化のオーバーヘッドの無視(AOF の fsync が、スループットを 2〜5 倍切り詰め得ます)。(5) マルチコアのサーバーを飽和させられない、単一のベンチマークスレッドです。現実的なベンチマークが使うもの:-r(ランダムキー)、-d(現実的なペイロード)、--threads(マルチスレッドのクライアント)、そして、本番同等の永続化とネットワークでのテストです。数字を共有するとき、ベンチマークのパラメータを必ず開示しましょう。

redis-cli
# COMMON PITFALL #1: benchmarking localhost only
# localhost numbers don't reflect real network latency
# always test over your production network path

# COMMON PITFALL #2: all keys the same (no -r)
# redis-benchmark -t set -n 100000
#   -> all SETs hit "key:0" — inflated by in-memory caching
# FIX: use -r to randomize keys
redis-benchmark -t set -n 100000 -r 1000000

# COMMON PITFALL #3: tiny payloads only
# 3-byte values don't reflect real memory/network pressure
# test with realistic sizes
redis-benchmark -t set -n 100000 -d 256 -r 1000000

# COMMON PITFALL #4: ignoring persistence overhead
# benchmark with AOF on vs off to see the durability cost:
redis-benchmark -t set -n 100000   # with current persistence settings
# (then) CONFIG SET appendonly no
redis-benchmark -t set -n 100000   # without AOF — compare

# COMMON PITFALL #5: single-threaded benchmark client
# one benchmark thread may not generate enough load
redis-benchmark -t set -n 100000 --threads 4 -c 100

# GOOD BENCHMARK (realistic):
redis-benchmark -t set,get -n 1000000 -c 50 -P 16 -r 1000000 -d 100 --threads 4 --csv

Was this helpful?