Skip to content

Redis Folha de referência

Armazenamento de estruturas de dados em memória, usado como banco de dados, cache e message broker.

01

Primeiros Passos

Conectar ao Redis

redis-cli é o cliente de linha de comando padrão. PING testa a conectividade (retorna PONG). Sempre use o comando AUTH ou a flag -a em produção. Evite pôr senhas na linha de comando em ambientes compartilhados — use a variável de ambiente REDISCLI_AUTH em vez disso. Redis moderno (6+) suporta usuários baseados em ACL com permissões delimitadas.

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

# connect with a specific host and port
redis-cli -h host.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

# test the connection
PING          # returns PONG
PING "hello"  # returns "hello"

Seleção de Banco e Básico

Bancos Redis são namespaces lógicos (numerados 0-15), não schemas isolados — compartilham a mesma memória. A maioria das aplicações usa apenas o db 0. FLUSHDB limpa o db atual; FLUSHALL limpa tudo. Múltiplos bancos são desencorajados em favor de instâncias Redis separadas ou prefixos de chave, já que compartilham uma única thread e não podem ser configurados individualmente.

redis
# 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

# get basic server info
INFO server
INFO memory
INFO replication

Chaves e Operações Gerais

KEYS bloqueia o servidor enquanto varre — nunca use em produção em datasets grandes; use SCAN em vez disso (baseado em cursor, não bloqueante). As chaves devem ser estruturadas com dois-pontos (user:1:profile) por legibilidade. EX define expiração em segundos; PX em milissegundos. TYPE retorna a estrutura de dados (string, list, hash, set, zset, stream).

redis
# set and get a key
SET user:1 "Alice"
GET user:1

# check if a key exists
EXISTS user:1          # 1 if exists, 0 if not

# delete keys
DEL user:1
DEL key1 key2 key3     # returns number deleted

# set a key with expiration (seconds)
SET session:abc "data" EX 3600

# find keys matching a pattern (avoid in production)
KEYS user:*
SCAN 0 MATCH user:* COUNT 100   # safer iteration

# rename a key
RENAME oldkey newkey

# get the type of a value stored at a key
TYPE user:1

Expiração e TTL

TTL retorna -2 para chaves inexistentes e -1 para chaves sem expiração. A expiração é preguiçosa — o Redis só verifica quando a chave é acessada ou durante varreduras periódicas em segundo plano. SET com EX é atômico (sem corrida entre SET e EXPIRE). Chaves expiradas não disparam eventos por padrão; habilite notificações de keyspace se precisar delas.

redis
# set expiration on an existing key
EXPIRE user:1 60        # 60 seconds
EXPIREAT user:1 1700000000  # Unix timestamp

# set expiration in milliseconds
PEXPIRE user:1 60000

# view remaining time to live (seconds)
TTL user:1              # -2 if no key, -1 if no expiry

# view TTL in milliseconds
PTTL user:1

# remove expiration (make key persistent)
PERSIST user:1

# set value AND expiration atomically
SET token "abc" EX 3600

SCAN e Iteração Segura

SCAN é a alternativa segura para produção ao KEYS — retorna um cursor que você segue até 0. COUNT é uma dica, não exato (pode retornar mais ou menos). SCAN oferece garantias fracas: pode retornar duplicatas ou perder chaves adicionadas durante a iteração, mas nunca bloqueia. Use HSCAN/SSCAN/ZSCAN para tipos de coleção. Sempre trate o loop do cursor no seu código.

redis
# SCAN: cursor-based iteration (non-blocking)
SCAN 0 MATCH user:* COUNT 100
# returns: [nextCursor, [key1, key2, ...]]
SCAN <nextCursor> MATCH user:* COUNT 100
# continue until cursor returns to 0

# scan a specific type
SCAN 0 TYPE hash

# HSCAN: iterate hash fields
HSCAN myhash 0 MATCH field* COUNT 100

# SSCAN: iterate set members
SSCAN myset 0 MATCH member* COUNT 100

# ZSCAN: iterate sorted set members
ZSCAN myzset 0 MATCH member* COUNT 100
02

Visão Geral dos Tipos de Dados

Estruturas de Dados Centrais

Escolher a estrutura de dados certa é a habilidade-chave do Redis. Strings para contadores/caches, hashes para objetos, lists para filas, sets para unicidade/tags, sorted sets para leaderboards/rankings, streams para logs de eventos. Cada operação numa estrutura de dados é atômica, então clientes concorrentes não podem corromper o estado. Escolha a estrutura que casa com seu padrão de acesso.

redis
# Redis is a data structure server, not just a key-value store
# Each key holds a typed data structure:

# String: binary-safe blob (up to 512MB)
SET key "value"
SET counter 100

# List: ordered, linked-list of strings
LPUSH mylist "a" "b"
RPUSH mylist "c"

# Hash: field-value map (like a small object)
HSET user:1 name "Alice" age 30

# Set: unordered collection of unique strings
SADD tags "redis" "db"

# Sorted Set (ZSet): set scored by a float
ZADD leaderboard 100 "alice" 200 "bob"

# Stream: append-only log with IDs
XADD mystream * field value

# Bitmap, HyperLogLog, Geo: built on strings/zsets

Escolhendo o Tipo Certo

Escolha o tipo pelo padrão de acesso: precisa de unicidade? Set. Precisa de ordenação por pontuação? Sorted set. Precisa atualizar um campo de um objeto? Hash (não uma string serializada). Precisa de contagens únicas aproximadas em escala? HyperLogLog (12KB para bilhões de itens). A escolha certa do tipo = código mais simples, operações atômicas e economia dramática de memória.

redis
# Use case -> data type mapping:
# Cache a string  -> String
SET api:response "json_blob"

# Store an object -> Hash (one key, multiple fields)
HSET user:1 name "Alice" email "[email protected]" age 30

# Queue / stack   -> List
LPUSH tasks "job1"   # push to head
RPOP tasks           # pop from tail (FIFO queue)

# Unique tags      -> Set
SADD post:1:tags "redis" "db" "cache"

# Leaderboard      -> Sorted Set
ZADD scores 100 "alice" 250 "bob"
ZREVRANGE scores 0 9     # top 10

# Event log        -> Stream
XADD events * type click user 1

# Count unique     -> HyperLogLog (approximate, fixed memory)
PFADD visitors "user1" "user2"

Codificação de Memória

Redis usa codificações compactas (listpack, intset) para estruturas pequenas — economizando 5-10x de memória — e troca para tabelas hash/skiplists automaticamente conforme crescem. OBJECT ENCODING revela a codificação atual. MEMORY USAGE reporta bytes. Você pode ajustar o limite (ex.: hash-max-listpack-entries), mas os padrões são bem escolhidos. Entender as codificações ajuda no planejamento de capacidade.

redis
# Redis optimizes storage based on size
# Inspect the internal encoding of a key
OBJECT ENCODING mykey

# String encodings:
#   "embstr"  - short strings (< 44 bytes)
#   "raw"     - long strings
#   "int"     - integer values

# Hash/List/Set/ZSet encodings:
#   "listpack" / "intset" - small (compact, memory-efficient)
#   "hashtable" / "list" / "skiplist" - large (faster, more memory)

# check memory usage of a key
MEMORY USAGE mykey

# sample memory usage stats
MEMORY STATS

# the encoding changes automatically as the structure grows

Comandos OBJECT e Memória

OBJECT IDLETIME é útil para achar chaves frias de cache (raramente acessadas). OBJECT FREQ funciona só com maxmemory-policy LFU. MEMORY USAGE com SAMPLES 0 conta exatamente (o padrão amostra em coleções grandes). COMMAND DOCS (Redis 7+) retorna documentação estruturada. Essas ferramentas de introspecção ajudam a depurar inchaço de memória e ajustar políticas de despejo.

redis
# OBJECT subcommands for introspection
OBJECT ENCODING mykey     # internal encoding
OBJECT REFCOUNT mykey     # reference count
OBJECT IDLETIME mykey     # seconds since last access
OBJECT FREQ mykey         # access frequency (LFU mode)

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

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

# help understand a command
COMMAND INFO GET
COMMAND DOCS SET

# COMMAND lists all commands (huge output)
COMMAND

Erros de Tipo e Verificação de Tipo

O tipo de uma chave é fixo pelo seu tempo de vida — não se pode reutilizar a mesma chave para um tipo diferente sem deletá-la primeiro. Erros WRONGTYPE protegem contra confusão acidental de tipos. Sempre verifique TYPE ao trabalhar com chaves de origem desconhecida. Essa tipagem estrita é a razão de os comandos Redis terem prefixo de tipo (HSET vs SET vs SADD).

redis
# each key has ONE type; using the wrong command fails
SET mykey "hello"
LPUSH mykey "x"        # WRONGTYPE error

# WRONGTYPE Operation against a key holding the wrong kind of value

# check the type before operating
TYPE mykey             # "string"
if [ "$(TYPE mykey)" = "string" ]; then ...

# TYPE returns: string|list|hash|set|zset|stream|none

# rename preserves the type
RENAME mykey newkey
TYPE newkey            # still "string"

# type is immutable; delete + recreate to change types
DEL mykey
LPUSH mykey "x"        # now a list
03

Strings

Operações Básicas de String

Strings são seguras para binário (podem guardar quaisquer bytes até 512MB, incluindo imagens ou JSON). SET com NX é a primitiva clássica de lock do Redis (define se não existe). GETSET é atômico e útil para trocar configurações. SETRANGE pode crescer uma string. Para dados estruturados, prefira Hashes a strings JSON serializadas — permitem atualizações no nível de campo.

redis
# set and get
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 mykey "new" EX 60 NX  # with expiry, only if new

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

# append to a string
APPEND mykey " world"   # "hello world"

# get substring
GETRANGE mykey 0 4      # "hello"
SETRANGE mykey 6 "redis"# "hello redis"

# get string length
STRLEN mykey            # 11

Contadores Numéricos

INCR/DECR são atômicos — seguros para acesso concorrente sem travas. Isso torna o Redis ideal para contadores, limitação de taxa (INCR + EXPIRE) e geração de IDs sequenciais. INCRBYFLOAT suporta decimais, mas usa precisão dupla (cuidado com arredondamento). Se o valor não for inteiro, INCR retorna erro. Contadores funcionam melhor combinados com EXPIRE para estatísticas por intervalo de tempo.

redis
# increment a numeric string atomically
INCR counter            # counter = counter + 1
INCRBY counter 10       # counter = counter + 10

# decrement
DECR counter            # counter = counter - 1
DECRBY counter 5        # counter = counter - 5

# floating point operations
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

Operações com Múltiplas Chaves

MSET/MGET agrupam operações numa única ida e volta — essencial para desempenho (o modelo single-threaded do Redis faz o custo por comando importar). MSETNX é atômico: ou todas as chaves são definidas ou nenhuma (tudo-ou-nada). GETDEL (6.2+) retorna e deleta atomicamente — útil para padrões de mensagem de leitura única. Agrupe comandos em lote sempre que possível para reduzir a latência de rede.

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

# get multiple keys at once
MGET k1 k2 k3           # ["v1", "v2", "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

# atomic get-and-delete (useful for queues)
GETDEL mykey            # returns value AND deletes key

Bitmaps (Baseados em String)

Bitmaps guardam flags booleanas para até 4 bilhões de usuários em ~512MB — extremamente eficientes em espaço para grandes populações. BITOP AND/OR/XOR/NOT combinam bitmaps (ex.: usuários ativos em múltiplos dias). BITCOUNT conta usuários ativos. Casos de uso: usuários ativos diários, feature flags, controle de presença. Posição = ID do usuário.

redis
# 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:daily:2025-01-01 5 1
SETBIT users:daily:2025-01-02 5 1
BITOP AND active-both users:daily:2025-01-01 users:daily:2025-01-02
BITCOUNT active-both        # users active on both days

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

Operações Bitfield

BITFIELD empacota múltiplos contadores pequenos numa única string — ex.: 1000 contadores diários como u8 em 1KB. OVERFLOW SAT satura no máximo (bom para estatísticas), FAIL retorna nil em overflow (bom para tetos), WRAP dá a volta (padrão, geralmente indesejado). É muito mais eficiente em memória que chaves separadas para muitos contadores pequenos.

redis
# BITFIELD: multiple counters in one string (compact)
# store up to 2^63 counters, each 1-64 bits, in a single key

# set a 8-bit unsigned counter at offset 0
BITFIELD mycount SET u8 0 100

# increment a counter (with overflow control)
BITFIELD mycount INCRBY u8 0 10   # returns 110
BITFIELD mycount INCRBY u8 0 10   # returns 120

# overflow control: WRAP (default), SAT, FAIL
BITFIELD mycount OVERFLOW SAT INCRBY u8 0 200  # saturates at 255
BITFIELD mycount OVERFLOW FAIL INCRBY u8 0 999 # returns nil (overflow)

# read multiple counters in one call
BITFIELD mycount GET u8 0 GET u8 8 GET u8 16
04

Hashes

Básico de Hashes

Hashes são ideais para guardar objetos — uma chave por objeto, campos por propriedade. Isso vence serializar JSON, porque você pode atualizar campos individuais atomicamente (HSET) sem ler-modificar-escrever. HGETALL retorna cada um dos campos; para hashes grandes, prefira HSCAN. Hashes usam codificação listpack quando pequenos (abaixo de ~128 campos), tornando-os eficientes em memória.

redis
# 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 multiple fields
HMGET user:1 name age       # ["Alice", "30"]

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

# get all field names or values
HKEYS user:1                # [name, age, email]
HVALS user:1                # [Alice, 30, [email protected]]

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

Operações de Campo do Hash

HSETNX fornece 'definir se não existe' no nível de campo (útil para inicialização única). HINCRBY em campos de hash é atômico — perfeito para contadores por usuário (contagem de logins, visualizações). Hashes se auto-deletam quando o último campo é removido (HDEL). HMSET está obsoleto, já que HSET agora aceita múltiplos campos; sempre use HSET.

redis
# 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

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

# increment a numeric field atomically
HINCRBY user:1 age 1         # age = 31
HINCRBY user:1 age -5        # age = 26
HINCRBYFLOAT user:1 score 0.5

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

# set multiple fields (same as HSET with multiple)
HMSET user:1 a 1 b 2         # deprecated, use HSET

Iteração de Hash

HGETALL bloqueia o servidor para hashes grandes — use HSCAN para iteração em produção. HSCAN é baseado em cursor: chame repetidamente até o cursor voltar a 0. COUNT é uma dica. HRANDFIELD (6.2+) é útil para amostragem (ex.: feature flags aleatórias). Para hashes com milhões de campos, considere dividi-los em múltiplas chaves por sharding.

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

# iterate all fields
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

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

Expiração de Hash (Redis 7.4+)

TTL no nível de campo (7.4+) é um recurso importante para hashes — antes era preciso chaves separadas ou gambiarras para expirar campos individuais. Útil para objetos com tempos de vida mistos (um perfil de usuário em que o token de sessão expira, mas o nome persiste). Versões antigas do Redis exigem guardar campos expiráveis como chaves separadas com o próprio EXPIRE.

redis
# before 7.4, expiration was only at the key level
EXPIRE user:1 3600    # the whole hash expires

# Redis 7.4+: field-level TTL (HEXPIRE)
HEXPIRE user:1 60 FIELDS 1 session_token
# expires only the session_token field in 60 seconds

# get TTL of a specific field
HPTTL user:1 FIELDS 1 session_token

# persist a specific field (remove its TTL)
HPERSIST user:1 FIELDS 1 session_token

# get all fields and their expiration times
HEXPIRETIME user:1 FIELDS 1 session_token

Casos de Uso de Hash

Hashes brilham para objetos e contadores agrupados. Uma técnica de memória poderosa: quando você tem muitas chaves de string pequenas, agrupe-as num único hash — a codificação listpack usa muito menos custo que milhares de chaves individuais (cada uma com metadados). Esse 'key bucketing' pode cortar o uso de memória em 5-10x para valores pequenos.

redis
# 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. Group small key-value pairs into one hash (memory savings)
# instead of SET k1 v1; SET k2 v2 -> HSET bucket k1 v1 k2 v2
05

Lists

Básico de Listas (Push/Pop)

Listas são de dupla ponta, então LPUSH+RPOP = fila (FIFO), LPUSH+LPOP = pilha (LIFO). BLPOP/BRPOP bloqueiam até um item estar disponível — a fundação das filas Redis (sem polling). Sempre defina um timeout no BLPOP para tratar desconexões. Listas são O(1) para operações de cabeça/cauda, mas O(N) para acesso no meio.

redis
# lists are ordered sequences of strings (linked lists)
# push to head (left) or tail (right)
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
LPOP mylist 2             # ["a", ...]

# 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

Indexação e Intervalos de Lista

LRANGE 0 -1 retorna a lista inteira. LTRIM é um padrão comum para limitar o tamanho da lista (ex.: manter só os últimos 100 eventos). LREM remove por valor (count: positivo=cabeça, negativo=cauda, 0=tudo). LINDEX é O(N) para elementos do meio — listas são otimizadas para acesso nas pontas. Para acesso aleatório por índice, use outra estrutura.

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

# get a range of elements
LRANGE mylist 0 -1        # all elements
LRANGE mylist 0 2         # first 3 elements
LRANGE mylist -3 -1       # last 3 elements

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

# get length
LLEN mylist

# trim to a range (removes everything outside)
LTRIM mylist 0 99         # keep only first 100 elements

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

Lista como Fila

BRPOPLPUSH/BLMOVE move um item atomicamente da fonte ao destino — o consumidor pode processá-lo com segurança, e se cair, o item continua no destino (padrão de fila confiável). Isso vence BRPOP+processamento, porque um crash após BRPOP perde o item. Após processar, delete da lista de destino.

redis
# 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
LPUSH source "item"
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

Inserção e Remoção em Lista

LINSERT é O(N) — use com parcimônia em listas grandes. LPOS acha posições de elementos sem removê-los. LMPOP (7.0+) faz pop de múltiplas listas numa chamada, útil para filas priorizadas. Para operações frequentes no meio da lista, uma lista é a escolha errada — considere um sorted set ou outro modelo de dados.

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

# remove elements by value
LREM mylist 1 "value"     # remove first occurrence from head
LREM mylist -1 "value"    # remove first occurrence from tail
LREM mylist 0 "value"     # remove ALL occurrences

# pop and push in one atomic operation
RPOPLPUSH source dest

# get and remove from both ends (6.2+)
LPOP mylist 2             # pop 2 from head
LMPOP 2 mylist LEFT COUNT 3  # (7.0+) pop from one of multiple lists

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

Casos de Uso de Lista

Listas são melhores para sequências com padrões de acesso nas pontas: filas, pilhas, feeds, buffers. LTRIM as torna ideais para logs/feeds limitados. Para limitação de taxa, uma lista de timestamps + LTRIM é uma janela deslizante simples. Para filas ordenadas/priorizadas, use um sorted set. Listas não suportam deduplicação — use um set para isso.

redis
# 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 <timestamp>
LTRIM rate:user:1 0 99
LLEN rate:user:1           # request count in window
06

Sets

Básico de Sets

Sets guardam valores únicos — perfeitos para tags, categorias e deduplicação. SISMEMBER é O(1) — muito mais rápido que checar uma lista. SMEMBERS pode bloquear em sets grandes; use SSCAN para iteração. SRANDMEMBER não remove; SPOP sim. Sets usam intset (array ordenado) quando cada um dos membros são inteiros — muito eficiente em memória.

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

# remove a member
SREM tags "cache"

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

# get the number of members
SCARD tags                 # 2

# get all members (avoid on large sets)
SMEMBERS tags              # ["redis", "db"]

# get a random member
SRANDMEMBER tags           # one random member
SRANDMEMBER tags 3         # 3 random (may repeat)
SRANDMEMBER tags -3        # 3 unique random

# pop a random member (removes it)
SPOP tags                  # removes and returns one

Operações de Set

Operações de set são o superpoder do Redis — união, interseção e diferença em O(N) sem processamento no cliente. Casos de uso: amigos em comum (SINTER), visitantes únicos (SUNION), filtragem por tags (SINTER de sets de tags). SINTERCARD (7.0+) retorna só a contagem, mais rápido quando não precisa dos membros. Guarde os resultados para evitar recomputar.

redis
# 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

Iteração e Movimentação de Set

SMOVE é atômico — útil para transições de estado (ex.: mover um usuário do set 'pending' para o 'active'). SSCAN é a forma segura de iterar sets grandes. SMISMEMBER (7.4+) verifica pertinência em lote, reduzindo idas e voltas. BSPOP (7.0+) bloqueia como BLPOP, mas para sets — útil para padrões dirigidos a eventos em que a ordem não importa.

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

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

# pop multiple random members (6.2+)
SPOP myset 3               # removes and returns 3 members

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

# check multiple memberships at once (7.4+)
SMISMEMBER myset "a" "b" "c"
# returns [1, 0, 1]

Casos de Uso de Set

Sets são a escolha padrão para unicidade e relações. O padrão SINTER para seguidores/amigos em comum é um clássico. Para 'visitantes por dia' com cardinalidade enorme, considere HyperLogLog (aproximado, mas com 12KB fixos). Para dados únicos ordenados (leaderboards), use um sorted set. Sets são sem ordem — se a ordem importa, use uma list ou sorted set.

redis
# 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
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"

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

Sets vs Outros Tipos

A seleção de tipo é a decisão central de design no Redis. Set para unicidade + pertinência rápida (sem ordem). Sorted set para rankings/ordenação (custa mais memória). List para sequências com duplicatas. Hash para objetos campo-valor. Na dúvida, esboce seus padrões de acesso: leituras, escritas, ordenação e requisitos de unicidade — o tipo certo se torna óbvio.

redis
# Set: unordered, unique, O(1) membership check
SADD myset "a" "b"
SISMEMBER myset "a"       # O(1)

# Sorted Set: unique + ordered by score
ZADD myzset 1 "a" 2 "b"
ZRANK myzset "a"          # 0 (rank)

# List: ordered, allows duplicates, O(N) search
LPUSH mylist "a" "a"
LPOS mylist "a"           # 0 (first match)

# Hash: field-value pairs, no ordering
HSET myhash a 1 b 2

# Choose:
# - need uniqueness only?           -> Set
# - need uniqueness + ordering?     -> Sorted Set
# - need ordering + allow dups?     -> List
# - need key-value mapping?         -> Hash
07

Sorted Sets

Básico de Sorted Sets

Sorted sets (zsets) são a estrutura mais poderosa do Redis — membros únicos ordenados por pontuação, com operações O(log N). As opções do ZADD (NX/XX/GT/LT) habilitam atualizações condicionais: GT só atualiza se a nova pontuação for maior (ótimo para rastrear 'melhor pontuação'). Pontuações são doubles; membros são únicos. Empates são resolvidos lexicograficamente.

redis
# 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: conditional)
ZADD leaderboard NX 300 "new"
ZADD leaderboard GT 300 "alice"  # only if new score is greater

# 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

Consultas de Intervalo

ZRANGE retorna por rank (índice); ZRANGEBYSCORE retorna por pontuação. O prefixo '(' torna a pontuação exclusiva. Redis 6.2 unificou esses em ZRANGE com opções BYSCORE/BYLEX/REV. WITHSCORES inclui a pontuação na saída. Para leaderboards, ZREVRANGE 0 9 dá o top 10. ZRANGESTORE (6.2+) guarda o resultado numa nova chave.

redis
# 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)

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

# descending order
ZREVRANGE leaderboard 0 2            # top 3 (highest scores)
ZREVRANGEBYSCORE leaderboard 200 100 # 200 down to 100

# 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

Operações de Pontuação e Ranks

ZINCRBY ajusta uma pontuação atomicamente e reordena — perfeito para leaderboards ao vivo. ZREMRANGEBYRANK é ótimo para manter um zset limitado (ex.: manter só o top 1000). ZCOUNT dá a contagem num intervalo sem buscar membros. ZMSCORE (6.2+) busca pontuações em lote, reduzindo idas e voltas para consultas de múltiplos membros.

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

# get the score
ZSCORE leaderboard "alice"

# remove a member
ZREM leaderboard "bob"

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

# count members in a score range
ZCOUNT leaderboard 100 200

# get the rank
ZRANK leaderboard "alice"          # ascending rank
ZREVRANK leaderboard "alice"       # descending rank (0 = highest)

# get multiple members' scores at once
ZMSCORE leaderboard "alice" "bob"  # ["250", "200"]

Intervalos Lexicográficos (BYLEX)

BYLEX habilita consultas de intervalo por membros quando as pontuações são iguais — transformando um sorted set num índice de strings auto-ordenado. Casos de uso: autocomplete (guarde palavras com pontuação 0, consulte intervalos de prefixo), dicionários ordenados. '[a' significa inclusivo, '(a' exclusivo, '-' início, '+' fim. Só funciona quando todas as pontuações são idênticas.

redis
# 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

Agregações de Sorted Set

ZUNIONSTORE/ZINTERSTORE combinam zsets com agregação configurável (SUM/MIN/MAX) e pesos — poderoso para pontuação ponderada (ex.: relevância = match_texto*2 + recência*1). Redis 6.2 adicionou ZUNION/ZINTER/ZDIFF, que retornam resultados sem guardar (um comando a menos). São O(N*M) — cuidado com muitos sets grandes. A contagem de sets precede os nomes dos sets.

redis
# ZUNIONSTORE / ZINTERSTORE: 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
08

Pub/Sub

Básico de Pub/Sub

Pub/Sub é dispara-e-esquece: as mensagens são entregues aos inscritos conectados no momento, sem persistência. Se nenhum inscrito está escutando, a mensagem se perde. Isso o torna inadequado para entrega confiável — use Streams para isso. Pub/Sub é ideal para notificações em tempo real, chat e fan-out em que perdas ocasionais são aceitáveis. Inscritos precisam estar conectados para receber.

redis
# subscribe to channels (in one client)
SUBSCRIBE news alerts

# publish a message to a channel (from another client)
PUBLISH news "Breaking: Redis 7.4 released"

# pattern subscription (glob-style)
PSUBSCRIBE news.*

# unsubscribe
UNSUBSCRIBE news
PUNSUBSCRIBE news.*

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

Pub/Sub Sharded (7.0+)

Pub/Sub Sharded (7.0+) resolve um problema do modo Cluster: o Pub/Sub regular transmite cada PUBLISH a cada um dos nós do cluster, desperdiçando banda. O Pub/Sub Sharded roteia mensagens só ao shard dono da chave do canal — muito mais eficiente em clusters grandes. Use SSUBSCRIBE/SPUBLISH em implantações Cluster. O nome do canal determina o shard (como uma chave).

redis
# 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)

Padrões e Casos de Uso de Pub/Sub

Pub/Sub é perfeito para padrões de fan-out: um publicador, muitos inscritos (salas de chat, dashboards ao vivo, invalidação de cache). PSUBSCRIBE com padrões glob (user:*:login) habilita roteamento flexível. A limitação principal é a falta de persistência — se um inscrito desconecta, perde mensagens. Para entrega confiável, pareie Pub/Sub com um Stream como backup, ou simplesmente use Streams.

redis
# 1. Real-time chat
# client subscribes to their room
SUBSCRIBE chat:room:42
# server publishes messages
PUBLISH chat:room:42 "Alice: hello"

# 2. Cache invalidation
# subscribe to invalidation channel
SUBSCRIBE cache:invalidate
# when data changes, publish
PUBLISH cache:invalidate "user:123"

# 3. Event notifications (with PSUBSCRIBE patterns)
PSUBSCRIBE user:*:login
# matches user:1:login, user:2:login, etc.

# 4. Live dashboards
SUBSCRIBE metrics:*
# push real-time updates to dashboards

# 5. Multiplayer game state
PUBLISH game:room:1 "player_moved:5:10"

Notificações de Keyspace

Notificações de keyspace permitem que clientes reajam a eventos do ciclo de vida das chaves (set, delete, expire, evict). Configure com notify-keyspace-events. São dispara-e-esquece (sem persistência) e não confiáveis — se o servidor Redis reinicia, eventos pendentes se perdem. Para processamento confiável de eventos, use Streams. Notificações de keyspace são ótimas para efeitos colaterais como limpeza ou aquecimento de cache.

redis
# 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

Pub/Sub vs Streams

Pub/Sub é para mensagens efêmeras em tempo real; Streams são para mensagens duráveis e reproduzíveis. Um híbrido comum: Pub/Sub para notificações ao vivo (rápido, com perdas) + Streams como fonte da verdade (durável, reproduzível). Novos inscritos leem o Stream para se atualizar e depois assinam o Pub/Sub para atualizações ao vivo. Para a maioria dos sistemas de produção que exigem confiabilidade, Streams são o padrão melhor.

redis
# Pub/Sub: fire-and-forget, no persistence
PUBLISH channel "msg"   # lost if no subscribers

# Streams: persistent, replayable, consumer groups
XADD mystream * msg "hello"   # stored forever (or capped)

# Pub/Sub pros: simple, low latency, fan-out
# Pub/Sub cons: no persistence, no replay, no consumer groups

# Streams pros: persistent, replayable, consumer groups, ACK
# Streams cons: more complex, requires cleanup (XADD MAXLEN)

# when to use each:
# - real-time notifications (loss OK)     -> Pub/Sub
# - chat with presence                    -> Pub/Sub + Streams
# - reliable task queue                   -> Streams
# - event sourcing / audit log            -> Streams
# - fan-out to transient subscribers      -> Pub/Sub
09

Transações e Pipelining

Transações MULTI/EXEC

MULTI/EXEC agrupa comandos num bloco atômico e sequencial — nenhum outro cliente pode se intercalar. Os comandos são enfileirados (retornando QUEUED) e executados juntos no EXEC. Um erro de enfileiramento (nome de comando ruim) aborta a transação inteira. Um erro de runtime (tipo errado numa chave) pula só aquele comando — o resto executa. Isso difere das transações SQL.

redis
# MULTI starts a transaction; commands are queued
MULTI
SET counter 1
INCR counter
INCR counter
GET counter
EXEC
# returns: [OK, 2, 3, "3"]

# discard a transaction (cancels all queued commands)
MULTI
SET x 1
DISCARD

# errors during queuing (syntax) abort the whole transaction
# errors during EXEC (e.g., wrong type) skip only that command

WATCH (Lock Otimista)

WATCH implementa lock otimista: se uma chave observada muda entre WATCH e EXEC, a transação é abortada (EXEC retorna nil). Este é o padrão Redis padrão para atomicidade de ler-modificar-escrever (já que o Redis não tem travas de linha). Sempre repita no nil. WATCH é verificado na hora do EXEC, não durante o enfileiramento. UNWATCH cancela as observações (também ocorre no DISCONNECT).

redis
# WATCH monitors keys; if any change before EXEC, the 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

Pipelining (Idas e Voltas em Lote)

Pipelining agrupa comandos para reduzir idas e voltas de rede — dramaticamente mais rápido que comandos individuais pela rede. Diferente de MULTI/EXEC, comandos pipelined NÃO são atômicos (outros clientes podem se intercalar). Use pipelining para operações em massa onde atomicidade não importa (inserções e leituras em massa) e MULTI/EXEC quando precisar de atomicidade. A maioria dos clientes faz pipelining automaticamente dentro de MULTI/EXEC.

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

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

# vs MULTI/EXEC: pipelining does NOT guarantee atomicity
# other clients can interleave between pipelined commands

# raw protocol example (RESP):
# *1\r\n$4\r\nPING\r\n*1\r\n$4\r\nPING\r\n
# (send multiple commands at once, read multiple replies)

Scripts Lua (Atômicos)

Scripts Lua são a forma Redis de fazer operações atômicas complexas — o script roda como uma única unidade atômica (sem intercalação). EVALSHA reexecuta um script carregado pelo hash (evita reenviar o script). Mantenha os scripts curtos (eles bloqueiam o servidor). Scripts têm requisitos de determinismo (sem chamadas aleatórias/de tempo) para replicação. Redis 7+ usa FUNCTIONS como alternativa mais estruturada.

redis
# Lua scripts run atomically — no other command runs during execution
# EVAL: run a script
EVAL "return redis.call('GET', KEYS[1])" 1 mykey

# 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"

# load a script once, then run by SHA hash (efficient)
SCRIPT LOAD "return redis.call('GET', KEYS[1])"
# returns a SHA1 hash
EVALSHA <sha1> 1 mykey

# check if a script is loaded
SCRIPT EXISTS <sha1>

Functions (Redis 7.0+)

Functions (7.0+) melhoram os scripts EVAL: são nomeadas (não só hasheadas), organizadas em bibliotecas e persistem entre reinícios (scripts EVAL são efêmeros). Isso as torna mais fáceis de gerenciar e implantar. FCALL invoca uma função pelo nome. Functions são a forma moderna de adicionar lógica atômica no servidor. Como scripts, precisam ser determinísticas para a replicação.

redis
# 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

# get the function's code
FUNCTION DUMP mylib

# delete a library
FUNCTION DELETE mylib

# functions persist across restarts (unlike EVAL scripts)
10

Persistência

Snapshots RDB

Snapshots RDB são arquivos binários compactos, ideais para backups e recuperação de desastres. BGSAVE bifurca o processo (copy-on-write) para que a thread principal não bloqueie, mas datasets grandes ainda podem causar picos de memória durante a bifurcação. As regras 'save' disparam snapshots automáticos conforme a taxa de mudança. RDB arrisca perder dados escritos após o último snapshot — pareie com AOF pela durabilidade.

redis
# RDB: point-in-time snapshot of the dataset (compact binary)
# trigger a snapshot manually:
SAVE              # blocks until done (use with care)
BGSAVE            # forks a background process (non-blocking)
LASTSAVE          # Unix timestamp of the last successful save

# 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 (default: dump.rdb in the working dir)
CONFIG GET dbfilename
CONFIG GET dir

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

AOF (Append-Only File)

AOF acrescenta cada comando de escrita a um log — muito mais durável que RDB (no máximo 1 segundo de perda de dados com everysec). 'always' faz fsync a cada escrita (muito lento, use só para dados críticos). BGREWRITEAOF compacta o log (reescreve-o como o conjunto mínimo de comandos). Arquivos AOF são maiores e mais lentos de carregar que RDB. Redis 7 usa um formato AOF multi-partes (base + incremental).

redis
# 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

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

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

Híbrido RDB + AOF

Rodar RDB + AOF juntos dá o reinício rápido do RDB e a durabilidade do AOF. Desde o Redis 7, o AOF é um arquivo multi-partes: um snapshot base RDB + log incremental de comandos — combinando carga rápida com perda mínima de dados. aof-use-rdb-preamble (padrão yes) põe um snapshot RDB no início do AOF, para recuperação mais rápida. Esta é a configuração de produção recomendada.

redis
# use BOTH RDB and AOF for the best of both worlds
# redis.conf:
#   save 900 1          # RDB snapshots
#   appendonly yes      # AOF enabled
#   aof-use-rdb-preamble yes  # RDB header in AOF (faster load)

# on restart, Redis loads AOF (more complete)
# the AOF file can start with an RDB snapshot (faster load)
# followed by incremental AOF commands

# disaster recovery: keep both RDB and AOF backups
# RDB for fast restores, AOF for minimal data loss

# check what's enabled
CONFIG GET save
CONFIG GET appendonly

# monitor persistence operations
INFO persistence

Backup e Restauração

Faça backup do arquivo RDB (compacto, rápido) regularmente — é um snapshot consistente mesmo com o Redis rodando (copy-on-write). Para AOF, faça backup do diretório appendonly inteiro (multi-partes do Redis 7). Restaure parando o Redis, trocando os arquivos e reiniciando. Para se recuperar de um comando ruim, edite o AOF para removê-lo antes do reinício. Sempre teste os backups com redis-check-rdb/aof.

redis
# backup: copy the RDB file while Redis runs
cp /var/lib/redis/dump.rdb /backup/dump-$(date +%F).rdb

# or trigger a BGSAVE first for a consistent snapshot
BGSAVE
# wait for LASTSAVE to update, then copy the file

# AOF backup: copy the AOF manifest + files
cp /var/lib/redis/appendonly.aof.* /backup/

# restore: stop Redis, replace the data files, start
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)
redis-check-rdb /var/lib/redis/dump.rdb
redis-check-aof /var/lib/redis/appendonly.aof

Trocas de Persistência

A escolha da persistência depende das suas necessidades de durabilidade. Cache puro: desative a persistência para velocidade máxima. Dados críticos: RDB+AOF (recomendado). Um padrão comum: desativar persistência no primário (pelo desempenho) e persistir numa réplica (descarrega o I/O de disco). AOF everysec é o ponto ideal — no máximo 1 segundo de perda de dados com impacto mínimo de desempenho. Sempre teste a recuperação.

redis
# choosing a persistence strategy:

# 1. RDB only (cache, re-buildable data)
#    save 3600 1
#    appendonly no
#    -> fast restart, some data loss on crash

# 2. AOF only (durability-critical, everysec)
#    save ""
#    appendonly yes
#    appendfsync everysec
#    -> up to 1s data loss, larger files

# 3. RDB + AOF (recommended production default)
#    save 3600 1
#    appendonly yes
#    aof-use-rdb-preamble yes
#    -> durability + fast restart

# 4. No persistence (pure cache, ephemeral)
#    save ""
#    appendonly no
#    -> maximum speed, all data lost on restart

# 5. Replica-only persistence (offload from primary)
#    primary: no persistence (max performance)
#    replica: RDB + AOF (persist here instead)
11

Clustering

Básico do Redis Cluster

Redis Cluster divide os dados entre nós usando 16.384 slots de hash. CRC16(chave) % 16384 determina o slot. Operações multi-chave (MGET, transações) exigem chaves no mesmo slot — use hash tags ({user:1}) para forçar chaves relacionadas juntas. Cada primário pode ter réplicas para HA. O cluster trata o failover automaticamente quando um primário falha.

redis
# Redis Cluster shards data across multiple nodes (16,384 slots)
# each key maps to a slot: CRC16(key) % 16384

# 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 status
redis-cli -p 7000 CLUSTER INFO
redis-cli -p 7000 CLUSTER NODES

# count slots assigned
CLUSTER COUNTKEYSINSLOT 1234

# get the slot for a key
CLUSTER KEYSLOT mykey   # e.g., 1234

# multi-key operations require keys in the SAME slot
# 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 {})

Hash Tags e Ops Multi-chave

Hash tags ({...}) forçam chaves ao mesmo slot, habilitando operações multi-chave num cluster. Mas use-as com juízo — abusar de uma tag (ex.: {users}:1, {users}:2) cria um hotspot num shard. Projete as hash tags em torno dos padrões de acesso: agrupe chaves acessadas juntas (os dados de um usuário, os itens de um pedido), mas mantenha chaves não relacionadas separadas. Este é o desafio central de modelagem de dados em cluster.

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

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)
# - too narrow -> can't do multi-key ops

Resharding do Cluster

Resharding move slots entre nós sem indisponibilidade — o Redis migra chaves uma por vez enquanto atende requisições. Adicione nós e depois rebalanceie para espalhar a carga. A ferramenta CLI --cluster cuida da orquestração complexa. Sempre rode --cluster check após mudanças. Resharding é lento (migração chave a chave), então planeje a capacidade com antecedência em vez de fazer resharding sob carga.

redis
# move slots from one node to another (resharding)
redis-cli --cluster reshard host1:7000
# prompts for: how many slots, target node, source nodes

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

# add a new replica to an existing primary
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>

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

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

Failover do Cluster

O failover do cluster é automático: se um primário fica inalcançável além de cluster-node-timeout (padrão 15s), sua réplica é promovida. Failover manual é para manutenção (atualizações sem indisponibilidade). TAKEOVER arrisca split-brain — use só em emergências. Sem réplicas, um primário falho deixa seus slots indisponíveis (cluster fora). Sempre rode com réplicas em produção. CLUSTER NODES mostra a topologia.

redis
# when a primary fails, its replica is promoted automatically
# manual failover (for maintenance):
redis-cli -p 7001 CLUSTER FAILOVER         # replica -> primary
redis-cli -p 7001 CLUSTER FAILOVER FORCE   # without primary agreement
redis-cli -p 7001 CLUSTER FAILOVER TAKEOVER # force, may split brain

# view the cluster topology
CLUSTER NODES
CLUSTER SHARDS    # (7.0+)

# a node flagged as FAIL after timeout is removed
# cluster- node-timeout 15000   (15 seconds in redis.conf)

# if a cluster has no replica for a failing primary,
# that slot range becomes unavailable until the primary returns
# (or you manually fix it)

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

Cluster vs Sentinel vs Único

Instância única para desenvolvimento. Sentinel para HA quando os dados cabem numa máquina (um primário + réplicas + sentinels para monitoramento/failover). Cluster para escala horizontal quando os dados excedem uma máquina ou o rendimento de escrita é muito alto. O Cluster adiciona complexidade (hash tags, limites multi-chave). Serviços gerenciados (Redis Cloud, ElastiCache, MemoryDB) cuidam do fardo operacional — prefira-os, a menos que tenha fortes razões para self-hosting.

redis
# Single Redis: one instance, no HA, no scaling
#    simplest, fine for dev/small cache

# Sentinel: 1 primary + replicas + sentinel monitors
#    HA (automatic failover), no sharding
#    good when dataset fits on one machine
#    sentinel.conf: sentinel monitor mymaster host 6379 2

# Cluster: sharded across N primaries + replicas
#    HA + horizontal scaling
#    good for large datasets / high throughput
#    more complex (multi-key limitations)

# choose:
# - dev / tiny cache              -> single
# - production, data fits in RAM  -> sentinel (HA)
# - data > single machine RAM     -> cluster (sharding)
# - very high write throughput    -> cluster (shard writes)

# managed Redis (Redis Cloud, ElastiCache) handles
# sentinel/cluster ops for you
12

Sentinel (Alta Disponibilidade)

Setup do Sentinel

Sentinel fornece HA sem sharding: monitora um primário, promove uma réplica em falha e reconfigura clientes. Quorum (o último número) é quantos sentinels precisam concordar que um primário caiu — defina (N/2)+1 para N sentinels. Implante 3 sentinels em máquinas separadas para tolerância a falhas. down-after-milliseconds deve ser > jitter de rede; baixo demais causa failovers falsos.

redis
# 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

Comandos do Sentinel

Clientes conectam aos Sentinels para descobrir o primário atual e depois conectam a ele. No failover, os clientes consultam os Sentinels de novo para achar o novo primário. SENTINEL failover aciona um failover manual (para atualizações rolando). ckquorum verifica se você tem sentinels suficientes para um quorum — rode isto no monitoramento. Todas as principais bibliotecas clientes Redis suportam Sentinel nativamente.

redis
# query sentinel state
redis-cli -p 26379 SENTINEL masters          # all monitored primaries
redis-cli -p 26379 SENTINEL master mymaster  # details of one primary
redis-cli -p 26379 SENTINEL replicas mymaster
redis-cli -p 26379 SENTINEL sentinels mymaster

# find the current primary address
SENTINEL get-master-addr-by-name mymaster

# force a failover (manual, for maintenance)
SENTINEL failover mymaster

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

# check the number of OK sentinels
SENTINEL ckquorum mymaster
# "OK 3 usable Sentinels" or "NOQUORUM" warning

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

Processo de Failover

O failover é automático, mas causa breve interrupção de escrita (segundos). SDOWN é a opinião de um sentinel; ODOWN é o consenso do quorum. O líder sentinel eleito escolhe a réplica mais atualizada para promover. Quando o velho primário retorna, torna-se réplica — escritas que ele aceitou durante a partição de rede se PERDEM (risco de split-brain). Assine +switch-master para alertas.

redis
# when a primary is down longer than down-after-milliseconds:
# 1. sentinels mark it 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-*

Réplicas de Leitura e Escala

Réplicas descarregam leituras do primário — úteis para cargas de muita leitura (análises, relatórios). A replicação é assíncrona, então os dados da réplica podem atrasar (normalmente milissegundos, mas pode crescer sob carga). Use READONLY para ler das réplicas. Réplicas graváveis (4.0+) aceitam escritas não replicadas — úteis para dados temporários ou caches por réplica, mas escritas se perdem no failover. Monitore o atraso das réplicas.

redis
# replicas can serve reads (eventually consistent)
REPLICAOF 192.168.1.10 6379    # become a replica of this primary
REPLICAOF NO ONE               # promote to primary (manual)

# check replication status
INFO replication
# role:slave, master_host, master_link_status:up, ...

# replica lag (bytes and seconds lagging behind primary)
# master_repl_offset vs slave_repl_offset

# clients can route reads to replicas for read scaling
# but beware: replica data may be stale (replication lag)

# Redis Sentinel + clients: configure read preference
#   READONLY command enables reads on a replica

# writable replicas (Redis 4.0+): accept writes that are
# local-only (not replicated) — useful for ephemeral data
#   replica-read-only no   (in redis.conf)

Entranhas da Replicação

A replicação é assíncrona e unidirecional (primário para réplica). A sincronização inicial envia um RDB completo e depois a fila de comandos; PSYNC habilita resync parcial após desconexões curtas (usando o backlog de replicação — ajuste repl-backlog-size). Uma mudança de ID de replicação (no reinício do primário ou failover) força um resync completo. Replicação em cadeia (réplica de réplica) reduz a carga do primário em fan-out grande.

redis
# replication is asynchronous: primary -> replica (one-way)
# initial sync: full RDB transfer + buffered commands
# subsequent: streaming command log

# trigger a full resync (force replica to reload everything)
redis-cli -p 6380 REPLICAOF NO ONE
redis-cli -p 6380 REPLICAOF 192.168.1.10 6379

# partial resync (PSYNC): if the replica disconnects briefly,
# it can resume from the replication backlog (no full resync)
#   repl-backlog-size 1mb    (tune for longer disconnects)

# monitor replication in real-time
redis-cli -p 6379 INFO replication
# master_repl_offset, slave_read_repl_offset, backlog_size

# chain replication: a replica of a replica (tree topology)
# reduces load on the primary for many replicas
REPLICAOF replica-host 6380   # chain off another replica

# replication ID changes on every primary restart -> full resync
13

Streams

Básico de Stream (XADD/XREAD)

Streams são a estrutura de mensagens durável do Redis — append-only, reproduzível, com grupos de consumidores. Os IDs são baseados em timestamp (gerados automaticamente com *). XREAD com $ acompanha o stream (só entradas novas); com 0 lê desde o início. MAXLEN limita o stream (~ para aproximado é muito mais rápido). Streams resolvem o problema de falta de persistência do Pub/Sub e são a forma recomendada de construir filas confiáveis.

redis
# streams are append-only logs with IDs (durable, replayable)
# XADD: add an entry (auto-generate ID with *)
XADD mystream * sensor temp 25.5
# returns an ID like "1700000000000-0" (timestamp-sequence)

# add with a specific ID (must be greater than the last)
XADD mystream 1700000001000-0 sensor temp 26.0

# read entries
XREAD COUNT 10 STREAMS mystream 0        # from the beginning
XREAD COUNT 10 STREAMS mystream $        # new entries only (tail)

# block for new entries (like BLPOP for lists)
XREAD BLOCK 30000 STREAMS mystream $     # blocks up to 30s

# get the length
XLEN mystream                            # number of entries

# capped stream (keep only last N entries)
XADD mystream MAXLEN 1000 * field value
XADD mystream MAXLEN ~ 1000 * field value  # ~ = approx (faster)

Grupos de Consumidores

Grupos de consumidores habilitam processamento paralelo: cada entrada é entregue a exatamente um consumidor do grupo. '>' lê entradas novas; '0' lê as pendentes (não confirmadas) deste consumidor. XACK marca uma entrada como processada. Entradas pendentes (entregues mas não confirmadas) formam um log de processamento — use XPENDING para achar mensagens travadas e XCLAIM para reatribuí-las a outro consumidor após um timeout.

redis
# create a consumer group at a specific position
XGROUP CREATE mystream mygroup $        # only new entries
XGROUP CREATE mystream mygroup 0        # all existing entries
XGROUP CREATE mystream mygroup 0 MKSTREAM  # create stream if missing

# read entries as a consumer (assigns pending entries)
XREADGROUP GROUP mygroup consumer1 COUNT 10 STREAMS mystream >
# '>' = never-delivered entries

# read pending entries (for this consumer, not yet acked)
XREADGROUP GROUP mygroup consumer1 STREAMS mystream 0

# acknowledge processing (removes from pending)
XACK mystream mygroup <id1> <id2>

# view pending entries (pending entries list)
XPENDING mystream mygroup
# returns: count, min-id, max-id, consumers

# view a consumer's pending entries
XPENDING mystream mygroup - + 10 consumer1

Processamento e Recuperação de Stream

XAUTOCLAIM é chave para processamento confiável: reatribui entradas pendentes há demais (consumidor caiu ou travou) a um consumidor saudável. O min-idle-time impede roubar entradas ainda sendo processadas. XTRIM limita o tamanho do stream (essencial para memória). XRANGE lê um intervalo por ID. XINFO revela o estado de stream/grupo/consumidor para monitoramento. Esta é uma fila de mensagens completa e durável.

redis
# XCLAIM: reassign a pending entry to another consumer
# (after the original consumer died or is too slow)
XCLAIM mystream mygroup consumer2 60000 <entry-id>
# 60000 = min idle time (ms) before claiming

# XAUTOCLAIM (6.2+): auto-claim stale pending entries
XAUTOCLAIM mystream mygroup consumer2 60000 0 COUNT 10
# claims entries idle > 60s, returns them to consumer2

# view stream info
XINFO STREAM mystream FULL
XINFO GROUPS mystream
XINFO CONSUMERS mystream mygroup

# delete an entry (rarely needed)
XDEL mystream <id>

# trim the stream (free memory)
XTRIM mystream MAXLEN 10000
XTRIM mystream MINID 1700000000000   # remove older than this ID

# range queries
XRANGE mystream - +                   # all entries
XRANGE mystream 1700000000000 - 1700000009999 -

Casos de Uso de Stream

Streams são excelentes para filas confiáveis, event sourcing e dados de série temporal. O padrão de grupo de consumidores (XADD + XREADGROUP + XACK) é um substituto completo das filas baseadas em lista, com retry embutido (entradas pendentes) e recuperação (XAUTOCLAIM). Para séries temporais, MAXLEN mantém a memória limitada. Streams são a estrutura Redis mais completa — use-as sempre que precisar de durabilidade e processamento ordenado.

redis
# 1. Reliable task queue (replaces lists + BRPOPLPUSH)
XADD tasks * type email payload '{"to":"[email protected]"}'
XREADGROUP GROUP workers worker1 COUNT 1 STREAMS tasks >
# process and XACK on success

# 2. Event sourcing / audit log
XADD events * user 1 action login ip 1.2.3.4
# replay with XRANGE for reconstruction

# 3. Real-time analytics (time-windowed)
XADD metrics * cpu 75 mem 60
XRANGE metrics - +           # query by time range

# 4. Chat history (capped)
XADD chat:room:1 MAXLEN ~ 1000 * user alice msg "hello"
XREAD COUNT 20 STREAMS chat:room:1 0

# 5. IoT sensor data (with TTL via trimming)
XADD sensors:temp MAXLEN ~ 86400 * value 22.5  # keep last day

Streams vs Outras Filas

Streams são a fila nativa do Redis — mais simples que Kafka/RabbitMQ e suficiente para a maioria das cargas que cabem na RAM. Faltam-lhes o paralelismo por partição do Kafka (um stream = um shard), mas grupos de consumidores fornecem paralelismo de workers. Para rendimento muito alto ou durabilidade em disco, Kafka vence. Para roteamento complexo, RabbitMQ vence. Para a maioria dos apps que já usam Redis, Streams são o padrão certo para mensagens confiáveis.

redis
# Redis Streams vs Lists (for queues):
# Lists: LPUSH/BRPOP, simple, NO retry/recovery
# Streams: consumer groups, ACK, pending, XAUTOCLAIM

# Redis Streams vs Kafka:
# Streams: in-memory (RAM-bounded), simpler, single-node or cluster
# Kafka: disk-based, partitioned, higher throughput at scale

# Redis Streams vs RabbitMQ:
# Streams: simpler, fewer features, in-memory
# RabbitMQ: rich routing, exchanges, acknowledgments, disk

# Streams capacity: limited by RAM (use MAXLEN/MINID to trim)
# Streams persistence: RDB/AOF (like any Redis data)

# choose Streams when:
# - you need a queue but already use Redis
# - dataset fits in RAM
# - you want simplicity over Kafka's scale
# - you need consumer groups with retry
14

HyperLogLog, Bitmaps e Geo

HyperLogLog (Cardinalidade)

HyperLogLog (HLL) conta elementos únicos com ~0.81% de erro usando 12KB fixos — conta bilhões de itens com memória constante. Perfeito para análises como visitantes únicos diários/semanais/mensais. PFMERGE combina HLLs (ex.: únicos mensais a partir dos diários). A troca é a aproximação — use um Set quando precisar de contagens exatas ou testes de pertinência (SISMEMBER), HLL quando só precisar da contagem.

redis
# HyperLogLog: approximate unique count with fixed 12KB memory
# perfect for counting unique visitors, IPs, etc. at scale

# add elements (returns 1 if the cardinality changed)
PFADD visitors:2025-01-01 "user:1" "user:2" "user:3"

# get the approximate unique count
PFCOUNT visitors:2025-01-01        # ~3

# merge multiple HLLs (e.g., monthly uniques from daily)
PFMERGE visitors:2025-01 visitors:2025-01-01 visitors:2025-01-02

# accuracy: ~0.81% standard error
# memory: always ~12KB regardless of element count (up to 2^64)

# vs a Set for unique counting:
# SADD + SCARD: exact, but O(N) memory (grows with count)
# PFADD + PFCOUNT: approximate, fixed 12KB memory
# 1 million uniques: Set ~10MB, HLL always 12KB

Imersão em Bitmaps

Bitmaps guardam um bit por usuário — 1 milhão de usuários = 125KB, 4 bilhões = 512MB. BITOP AND/OR/XOR/NOT combina bitmaps (retenção, análise de churn). BITPOS acha o primeiro bit definido. Casos de uso: usuários ativos diários, feature flags, presença, grupos de teste A/B. Limitação: exige IDs de usuário inteiros densos (lacunas desperdiçam espaço). Para dados esparsos, prefira um Set ou HyperLogLog.

redis
# bitmaps: boolean operations on a string's bits
# ideal for per-user flags over a large user base (user ID = bit position)

# mark user 7 as "active today"
SETBIT active:2025-01-01 7 1

# check if user 7 was active
GETBIT active:2025-01-01 7          # 1

# count active users
BITCOUNT active:2025-01-01

# users active on BOTH days (AND)
BITOP AND active:both active:2025-01-01 active:2025-01-02
BITCOUNT active:both

# users active on EITHER day (OR)
BITOP OR active:either active:2025-01-01 active:2025-01-02

# users active on day 1 but NOT day 2 (XOR or AND NOT)
BITOP XOR diff active:2025-01-01 active:2025-01-02

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

# memory: 1 million users = 125KB (1 bit per user)

Geoespacial (GEO)

Comandos GEO guardam pontos geográficos e suportam consultas de raio/caixa — construídos sobre sorted sets (pontuação = geohash). GEOSEARCH (6.2+, substitui GEORADIUS) acha pontos próximos com opções ricas (WITHCOORD, WITHDIST, ASC/DESC). A distância é computada numa esfera. A precisão é boa para a maioria dos apps. Para GIS complexo (polígonos, rotas), use um banco espacial dedicado. GEO é perfeito para recursos 'encontrar por perto'.

redis
# GEO: built on sorted sets, stores (lng, lat, name) points
# add locations (longitude, latitude, name)
GEOADD places -73.99 40.73 "Park" -73.98 40.75 "Museum" -74.00 40.70 "Cafe"

# get coordinates of a member
GEOPOS places "Park"               # [["-73.99","40.73"]]

# distance between two members (meters by default)
GEODIST places "Park" "Museum"     # "1623.5"
GEODIST places "Park" "Museum" km  # "1.623"

# find members within a radius (meters)
GEOSEARCH places FROMMEMBER "Park" BYRADIUS 1000 m ASC
# members within 1km of Park, sorted by distance

# find members within a bounding box
GEOSEARCH places FROMLONLAT -73.99 40.73 BYBOX 2 2 km

# GEOSEARCH also returns distance and coordinates
GEOSEARCH places FROMMEMBER "Park" BYRADIUS 500 m WITHCOORD WITHDIST

Operações Geoespaciais

GEO é implementado sobre sorted sets — o geohash das coordenadas é a pontuação. Isso significa que você pode usar comandos Z* para algumas operações (ZREM, ZRANGE). GEOSEARCH retorna resultados ricos (distância, coordenadas, geohash). COUNT limita os resultados (use com ASC para os N mais próximos). GEOSEARCHSTORE salva resultados para processamento posterior. A precisão do geohash degrada perto dos polos — suficiente para a maioria dos apps reais.

redis
# add multiple points at once
GEOADD cities -122.41 37.78 "San Francisco" -74.00 40.71 "New York"

# get the geohash of a member
GEOHASH places "Park"              # ["dr5reg..."]

# remove a member (uses ZREM internally)
ZREM places "Cafe"

# count members in an area (using ZCOUNT on the underlying zset)
ZCOUNT places -180 180             # all members

# GEOSEARCH with a center point and limiting results
GEOSEARCH places FROMLONLAT -73.99 40.73 \
  BYRADIUS 2000 m ASC COUNT 5      # nearest 5 within 2km

# GEOSEARCHSTORE: store results in a new key (6.2+)
GEOSEARCHSTORE nearby FROMLONLAT -73.99 40.73 BYRADIUS 1000 m

# the underlying structure is a sorted set, so:
ZRANGE places 0 -1                 # list all members
ZSCORE places "Park"               # geohash score

Escolhendo Tipos Especializados

Redis oferece muitas estruturas especializadas além das cinco centrais. HyperLogLog para cardinalidade aproximada, Bitmaps para flags booleanas densas, GEO para proximidade. Módulos adicionam filtros Bloom (teste de pertinência com falsos positivos), Top-K (os mais pesados) e RedisTimeSeries (séries temporais otimizadas). Case a estrutura à forma dos seus dados e às necessidades de precisão — a escolha certa pode economizar ordens de magnitude de memória.

redis
# Cardinality counting (unique elements):
#   exact, need membership test  -> Set (SADD/SISMEMBER/SCARD)
#   approximate, huge scale      -> HyperLogLog (PFADD/PFCOUNT)
#   per-time-bucket uniques      -> HLL per day, PFMERGE for ranges

# Boolean flags over a dense ID space:
#   small number of flags        -> Set of active IDs
#   millions of users            -> Bitmap (SETBIT/BITCOUNT)
#   multiple counters compactly  -> BITFIELD

# Geographic points:
#   "find nearby" queries        -> GEO (GEOADD/GEOSEARCH)
#   complex GIS                  -> use PostGIS/external

# Time-series data:
#   simple, capped               -> Stream (XADD MAXLEN)
#   dedicated TS module          -> RedisTimeSeries (module)

# Probabilistic structures (modules):
#   Bloom filter                 -> RedisBloom (BF.ADD/BF.EXISTS)
#   Top-K                        -> RedisBloom (TOPK)
15

Segurança

Autenticação e ACLs

ACLs do Redis 6+ substituem o modelo de senha única — crie usuários com permissões delimitadas. A sintaxe: on (habilitado), >senha, ~padrao (padrões de chave), +comando/-comando, +@categoria/-@categoria (ex.: +@read, -@dangerous). Sempre crie um usuário de menor privilégio para cada app. Salve as ACLs num arquivo para persistência. Nunca use o usuário padrão em produção — desative-o ou defina uma senha forte.

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

# Redis 6+: ACL system with users and permissions
# add a user with limited access
ACL SETUSER appuser on >secretpassword ~app:* +get +set +del -@dangerous

# list users
ACL LIST
ACL WHOAMI                # current user

# view a user's permissions
ACL GETUSER appuser

# delete a user
ACL DELUSER appuser

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

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

Criptografia TLS/SSL

TLS criptografa dados em trânsito — essencial em produção, especialmente em redes não confiáveis. Redis 6+ suporta TLS nativamente. mTLS (tls-auth-clients yes) exige que clientes apresentem um certificado, fornecendo autenticação mútua sem senhas. Para cluster/sentinel, habilite TLS também na comunicação entre nós. Porta 0 desativa texto puro; durante a migração, você pode rodar ambas as portas temporariamente.

redis
# enable TLS in redis.conf (Redis 6+)
# generate certs first (or use a real CA):
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-cluster yes              # TLS between cluster nodes
tls-replication yes          # TLS between primary/replica
tls-auth-clients yes         # require client certs

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

Segurança de Rede

Redis não tem controle de acesso de rede nativo — use bind + protected-mode + um firewall. NUNCA exponha o Redis à internet (incontáveis violações por Redis aberto sem auth). protected-mode bloqueia conexões externas quando nenhuma senha está definida. rename-command desativa comandos perigosos (FLUSHALL, CONFIG, KEYS), mas ACLs (6.0+) são a abordagem moderna. Ponha o Redis numa sub-rede privada; acesse via VPN ou bastion.

redis
# bind to specific interfaces (never 0.0.0.0 in prod)
bind 127.0.0.1 10.0.0.5
protected-mode yes            # blocks external access if no password

# require authentication
requirepass "strong-random-password"

# rename dangerous commands (or disable them)
rename-command FLUSHALL ""
rename-command FLUSHDB ""
rename-command CONFIG "CONFIG_9f8a7b"
rename-command KEYS ""

# Redis 6+: better to use ACLs instead of rename-command
# ACL SETUSER default -flushall -config -keys

# disable debug commands
# ACL SETUSER default -@dangerous

# use a firewall / security group to restrict access
# Redis should NEVER be directly internet-accessible
# (the 2018+ ransom attacks scanned for open Redis instances)

Auditoria e Logs

SLOWLOG registra comandos lentos para auditoria de desempenho — defina o limiar ao seu SLO (ex.: 10ms). MONITOR registra cada comando (enorme impacto de desempenho — só depuração). LATENCY MONITOR ajuda a achar picos de latência. CLIENT LIST mostra clientes conectados (fique atento a vazamentos). Defina loglevel como 'notice' em produção (debug é verboso demais). Envie os logs a um sistema central para análise.

redis
# log slow commands (slowlog)
CONFIG SET slowlog-log-slower-than 10000   # 10ms in microseconds
CONFIG SET slowlog-max-len 128             # keep 128 entries
SLOWLOG GET 10                             # last 10 slow commands
SLOWLOG RESET

# log to a file (redis.conf)
logfile /var/log/redis/redis.log
loglevel notice    # debug|verbose|notice|warning

# monitor all commands (debugging only — huge perf impact)
MONITOR

# latency monitoring
CONFIG SET latency-monitor-threshold 100   # 100ms
LATENCY HISTORY event-name
LATENCY DOCTOR                              # analysis report

# client list (who's connected)
CLIENT LIST
CLIENT GETNAME
CLIENT SETNAME "my-app"

Boas Práticas de Segurança

A segurança do Redis é em camadas: rede (bind/firewall), autenticação (senha/ACL), transporte (TLS), restrição de comandos (ACL/rename) e auditoria (slowlog/monitor). A regra nº 1: nunca exponha o Redis direto à internet — ele não tem limitação de taxa nem proteção contra força bruta embutidas. Criptografe arquivos RDB/AOF no nível do disco (contêm seus dados em texto puro). Mantenha o Redis atualizado com patches de segurança.

redis
# 1. NEVER expose Redis to the public internet
bind 127.0.0.1
protected-mode yes

# 2. Use strong passwords or ACLs
requirepass "<64-char-random-string>"
# or ACLs with least privilege

# 3. Enable TLS for transit encryption
tls-port 6379

# 4. Restrict dangerous commands
ACL SETUSER default -@dangerous -flushall -keys

# 5. Use a firewall / security group
# allow only app servers on the Redis port

# 6. Rotate credentials regularly
ACL SETUSER appuser on >newpassword ~app:* +@read +@write

# 7. Audit access
LOGICALDB MONITOR  # or use an audit module

# 8. Encrypt sensitive data at rest (disk encryption)
# RDB/AOF files can contain sensitive data

# 9. Keep Redis updated (security patches)
# 10. Isolate environments (separate dev/staging/prod)
16

Desempenho e Otimização

Fundamentos de Desempenho

Redis é single-threaded para execução de comandos — um comando lento bloqueia todas as conexões de clientes. Nunca use KEYS, SMEMBERS ou DEL em estruturas grandes em produção. Use a família SCAN, HSCAN e UNLINK (delete assíncrono) em vez disso. Agrupe comandos com pipeline para reduzir idas e voltas. Conheça o Big-O de cada comando: O(1) e O(log N) são seguros; comandos O(N) devem ser limitados (LRANGE com intervalos pequenos).

redis
# Redis is single-threaded (mostly) — avoid blocking commands
# DANGEROUS on large datasets (block the server):
KEYS *              # use SCAN instead
SMEMBERS bigset     # use SSCAN
HGETALL bighash     # use HSCAN
DEL hugekey         # use UNLINK (async delete)
FLUSHDB             # use FLUSHDB ASYNC

# use UNLINK instead of DEL for large keys (non-blocking)
UNLINK bigkey       # deletes in a background thread

# favor pipelining and batch commands
MGET k1 k2 k3       # one round-trip, not three GETs
LPUSH list a b c    # one command, not three

# prefer structurally efficient commands
# O(1): GET, SET, HGET, SISMEMBER, ZSCORE
# O(log N): ZADD, ZRANGE
# O(N): LRANGE, SMEMBERS, KEYS, SORT

Pipelining e Operações em Lote

Pipelining é a maior alavanca de desempenho do Redis — agrupar comandos numa única ida e volta de rede pode dar aceleração de 10-100x. Cada ida e volta custa latência de rede (~0.1-1ms); 1000 comandos individuais = 100-1000ms, mas com pipeline = ~1ms. Não abuse do pipeline (respostas enfileiradas consomem memória). Faça benchmark com redis-benchmark -P para achar seu ponto ideal. Transações usam pipelining automaticamente.

redis
# pipelining: send many commands without waiting for replies
# (reduces round-trip time — huge speedup over network)

# example (Node.js with ioredis):
const pipeline = redis.pipeline()
for (let i = 0; i < 1000; i++) {
  pipeline.set(`key:${i}`, "value")
}
await pipeline.exec()        # one round-trip for 1000 commands

# transactions (MULTI/EXEC) are automatically pipelined
redis.multi().set("k", "v").incr("c").exec()

# MSET/MGET batch in one command
MSET k1 v1 k2 v2 k3 v3
MGET k1 k2 k3

# benchmark pipelining
redis-benchmark -t set -n 100000 -P 16   # -P = pipeline size

# don't pipeline too many at once (memory for queued replies)
# batch in groups of 100-1000

Otimização de Memória

Memória é a restrição primária do Redis. Use a estrutura certa: hashes para objetos (a codificação listpack é 5-10x menor que chaves separadas). Ajuste os limiares de codificação para manter as estruturas em forma compacta. 'Key bucketing' (agrupar chaves pequenas num hash) reduz drasticamente o custo por chave. Defina maxmemory + uma política de despejo para prevenir OOM. Monitore used_memory e a razão de fragmentação.

redis
# use the right data structure (memory vs speed trade-offs)
# store small objects as hashes (listpack encoding is compact)
HSET user:1 name "Alice" age 30   # better than 3 string keys

# tune encoding thresholds (redis.conf)
hash-max-listpack-entries 128     # hash -> hashtable above this
hash-max-listpack-value 64        # field value size limit
list-max-listpack-size -2         # listpack max size
set-max-intset-entries 512        # intset -> hashtable above this
zset-max-listpack-entries 128

# use hashes for many small keys (key bucketing)
# instead of SET user:1:clicks 5; SET user:2:clicks 3
# use HSET clicks user:1 5 user:2 3

# monitor memory
INFO memory | grep used_memory_human
MEMORY STATS

# set maxmemory and an eviction policy
maxmemory 4gb
maxmemory-policy allkeys-lru

Políticas de Despejo

A política de despejo controla o comportamento quando a memória enche. Para cache puro: allkeys-lru ou allkeys-lfu (LFU melhor para padrões de acesso enviesados). Para banco de dados: noeviction (escritas falham em vez de perder dados). Para uso misto: volatile-lru (despeja só chaves com TTL, mantém as persistentes). LFU (4.0+) acompanha a frequência de acesso, frequentemente superando LRU. Monitore evicted_keys para dimensionar maxmemory corretamente.

redis
# when maxmemory is reached, Redis evicts keys per the policy
# maxmemory-policy options:

# no eviction (writes fail with OOM error)
maxmemory-policy noeviction

# LRU (Least Recently Used) — approximate LRU
allkeys-lru         # evict any key (cache use case)
volatile-lru        # only evict keys with TTL set

# LFU (Least Frequently Used) — better for skewed access
allkeys-lfu
volatile-lfu

# random eviction
allkeys-random
volatile-random

# TTL-based (evict soonest-expiring)
volatile-ttl

# for a cache: allkeys-lru or allkeys-lfu (best hit rate)
# for a database: noeviction (never lose data silently)
# mixed (some persistent, some cache): volatile-lru

Benchmarking

redis-benchmark mede rendimento e latência sob carga. -c (concorrência) simula clientes; -P (pipelining) testa desempenho em lote. --latency mostra o tempo de ida e volta em tempo real. Para resultados precisos, rode o benchmark de uma máquina perto do Redis (a rede domina). Redis 6+ suporta --threads para benchmark multithread. Desempenho típico de nó único: 100K+ ops/seg em hardware comum.

redis
# redis-benchmark: built-in performance testing
redis-benchmark -t set,get -n 100000 -c 50
# -t: test commands, -n: number of requests, -c: concurrent clients

# test with pipelining
redis-benchmark -t set -n 100000 -c 50 -P 16

# test a specific command with a specific key
redis-benchmark -t get -n 100000 -r 100000 -q
# -r: random keys (INSERT random keys for testing)

# latency check (100 requests, shows distribution)
redis-cli --latency
redis-cli --latency-history    # rolling update
redis-cli --latency-dist       # histogram

# in-memory test (no network overhead)
redis-benchmark -t set -n 100000 -q --threads 4

# monitor while benchmarking
redis-cli INFO stats | grep instantaneous_ops_per_sec
17

Administração

Info do Servidor e Monitoramento

INFO é o comando primário de monitoramento — verifique as seções de memória, clientes, persistência e estatísticas regularmente. MEMORY DOCTOR e LATENCY DOCTOR fornecem análise automatizada. SLOWLOG captura comandos lentos. CLIENT LIST mostra todas as conexões (fique atento a vazamentos — cada uma consome memória). Configure monitoramento externo (Prometheus + redis_exporter, Datadog) para gráficos históricos e alertas de memória, conexões e atraso de replicação.

redis
# 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 keyspace         # keys per database

# real-time stats
LATENCY DOCTOR        # latency analysis
MEMORY DOCTOR         # memory analysis

# live monitoring (subscribe to a special channel)
SUBSCRIBE __redis__:invalidate

# slow query log
SLOWLOG GET 10
SLOWLOG LEN

# client connections
CLIENT LIST
CLIENT KILL ID <id>   # disconnect a client

Gestão de Clientes

CLIENT LIST identifica conexões por endereço, nome e comando atual — inestimável para achar vazamentos ou clientes travados. CLIENT SETNAME rotula conexões para identificação fácil (defina no seu app ao conectar). CLIENT PAUSE bloqueia clientes brevemente para migrações/snapshots seguros. Defina um timeout para limpar conexões ociosas. maxclients impede esgotamento de conexões (cada cliente usa certa memória).

redis
# list all connected clients
CLIENT LIST
# id, addr, name, age, idle, flags, db, cmd

# name your connections (for identification)
CLIENT SETNAME "my-app-worker-1"

# get the current client's info
CLIENT INFO

# get the current client's ID
CLIENT ID

# kill a client
CLIENT KILL ADDR 1.2.3.4:12345
CLIENT KILL ID 42
CLIENT KILL TYPE normal    # kill all normal clients

# pause clients (for maintenance, 10 seconds)
CLIENT PAUSE 10000

# set a timeout for idle clients
CONFIG SET timeout 300    # 5 minutes

# max clients
CONFIG SET maxclients 10000

Configuração

CONFIG SET muda configurações em runtime (sem reinício); CONFIG REWRITE as persiste no redis.conf. Sempre teste mudanças de config em staging. Configurações-chave de produção: maxmemory + política de despejo (prevenir OOM), save + appendonly (persistência), tcp-keepalive (detectar clientes mortos), timeout (limpar conexões ociosas). Versione seu redis.conf. CONFIG GET * mostra tudo — útil para auditoria.

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

# change config at runtime
CONFIG SET maxmemory 4gb
CONFIG SET maxmemory-policy allkeys-lru
CONFIG SET slowlog-log-slower-than 10000

# persist config changes to redis.conf
CONFIG REWRITE

# view all config (large output)
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

Depuração e Solução de Problemas

OBJECT ENCODING revela a representação interna (depuração de memória). OBJECT IDLETIME acha chaves frias (candidatas ao despejo). MEMORY USAGE por chave identifica os comilões de memória. DEBUG SLEEP testa como seu app trata latência. LATENCY acompanha eventos (expiração, despejo, chaves rápidas). Desfragmentação ativa (4.0+) recupera automaticamente memória fragmentada online. Use comandos DEBUG com parcimônia em produção.

redis
# check if a key exists and its type
EXISTS mykey
TYPE mykey
OBJECT ENCODING mykey
OBJECT IDLETIME mykey     # seconds since last access

# memory usage per key
MEMORY USAGE mykey

# find keys blocking the server (DEBUG SLEEP for testing)
DEBUG SLEEP 2             # blocks for 2 seconds (testing only)

# check the latency
LATENCY HISTORY event
LATENCY GRAPH event

# object frequency (LFU mode)
OBJECT FREQ mykey

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

# last saved RDB timestamp
LASTSAVE

# active defragmentation (4.0+)
CONFIG SET activedefrag yes
MEMORY MALLOC-STATS

Atualizações e Manutenção

Para atualizações sem indisponibilidade, use replicação: atualize as réplicas primeiro, faça failover, depois atualize o velho primário. Para clusters, faça reinícios rolando um nó por vez (failover de primários primeiro). Sempre faça backup (BGSAVE + copiar RDB) antes de atualizar. Leia as notas de release para mudanças quebradoras. Teste em staging. Redis mantém compatibilidade retroativa entre versões menores, mas versões maiores podem ter passos de migração.

redis
# upgrade a standalone Redis:
# 1. save the dataset
SAVE
# 2. stop Redis
redis-cli SHUTDOWN
# 3. replace the binary
# 4. start the new version
redis-server /etc/redis/redis.conf

# upgrade a primary/replica pair (zero downtime):
# 1. upgrade the REPLICA first
SHUTDOWN
# 2. start new version on replica
# 3. promote replica to primary (SENTINEL FAILOVER)
# 4. upgrade the old primary (now a replica)
# 5. failback if desired

# upgrade a cluster:
# 1. upgrade one node at a time (rolling)
# 2. for each node: CLUSTER FAILOVER (if primary), upgrade, restart

# always back up before upgrading
# check the release notes for breaking changes
# test the upgrade in staging first

# rolling restart of a cluster (script)
for node in $nodes; do
  redis-cli -h $node CLUSTER FAILOVER
  redis-cli -h $node SHUTDOWN
  ssh $node "systemctl start redis"
done
18

Padrões Comuns

Padrão de Cache (Cache-Aside)

Cache-aside é o padrão Redis mais comum: leia do cache, recue ao banco em miss, popule o cache. Defina um TTL para limitar a obsolescência. Para escritas, ou write-through (atualize o cache na escrita do banco) ou invalidação (delete a chave do cache). A invalidação é mais segura (sem corrida para repopular), mas o write-through mantém o cache quente. Proteção contra cache stampede: use um lock ou padrão 'dogpile' para impedir que muitas requisições batam no banco simultaneamente num miss.

redis
# cache-aside: app checks cache, falls back to DB, fills cache
# pseudo-code:
function get_user(id):
  # 1. check cache
  data = GET("user:" + id)
  if data:
    return JSON.parse(data)

  # 2. cache miss -> query database
  data = db.query("SELECT * FROM users WHERE id = ?", id)

  # 3. fill cache (with TTL to avoid stale data)
  SET("user:" + id, JSON.stringify(data), "EX", 3600)

  return data

# write-through: update cache when DB changes
function update_user(id, data):
  db.update(id, data)
  SET("user:" + id, JSON.stringify(data), "EX", 3600)

# cache invalidation:
DEL("user:" + id)   # when the DB record is deleted

Locks Distribuídos

Locks distribuídos com SET NX EX são simples, mas exigem cuidado: sempre defina um TTL (prevenir deadlocks se o portador cair) e use um token único para liberar só o próprio lock (checagem-e-delete atômica via Lua). Para mais segurança através de cenários de falha, o algoritmo Redlock usa múltiplas instâncias Redis independentes. Locks não são perfeitamente seguros (deriva de relógio, pausas de GC) — para garantias fortes de correção, considere um sistema de consenso (etcd, ZooKeeper). Locks Redis servem para a maioria da coordenação prática.

redis
# SET NX with expiry = simple distributed lock
SET lock:resource "token-abc" NX EX 10
# returns OK if acquired, nil if already held

# release: only delete if the value matches (avoid releasing others' locks)
# (requires a Lua script for atomicity)
EVAL "
  if redis.call('GET', KEYS[1]) == ARGV[1] then
    return redis.call('DEL', KEYS[1])
  end
  return 0
" 1 lock:resource "token-abc"

# Redlock algorithm (multi-instance, higher safety):
# 1. get the time
# 2. SET NX on N (usually 5) independent Redis instances
# 3. if acquired on majority (3/5) within validity window -> locked
# 4. otherwise, release on all instances and retry

# lock options:
#   EX 10        # expire after 10 seconds (safety)
#   NX           # only if not exists
#   "token"      # unique value per lock holder (for safe release)

Limitação de Taxa

Janela fixa (INCR+EXPIRE) é a mais simples, mas permite 2x de rajada nas fronteiras da janela. Janela deslizante (sorted set de timestamps) é mais precisa, mas usa mais memória. Token bucket permite rajadas até um máximo. Cada um pode ser atômico com scripts Lua (importante para correção sob concorrência). Para limitação por usuário em escala, a abordagem de janela fixa costuma bastar e é muito eficiente em memória.

redis
# fixed window rate limiter (simple)
# INCR + EXPIRE on first request
count = INCR("rate:user:1")
if count == 1:
  EXPIRE("rate:user:1", 60)   # 60-second window
if count > 100:
  return "Rate limited"

# sliding window rate limiter (sorted set)
now = current_time_millis()
ZADD("rate:user:1", now, now)         # add current request
ZREMRANGEBYSCORE("rate:user:1", 0, now - 60000)  # remove old
EXPIRE("rate:user:1", 60)
count = ZCARD("rate:user:1")          # current count
if count > 100:
  return "Rate limited"

# token bucket (Lua script for atomicity)
# maintains a bucket of tokens refilled over time
# see: https://redis.io/docs/patterns/distributed-locks/

# GCRA (Generic Cell Rate Algorithm) — elegant single-key version

Leaderboard e Ranking

Sorted sets tornam leaderboards triviais: ZADD para atualizar pontuações, ZREVRANGE para o top N, ZREVRANK para a posição de um jogador. ZINCRBY atualiza pontuações atomicamente. Para leaderboards por intervalo de tempo (diário/semanal), use uma chave por período com TTL. Paginação usa ZREVRANGE com offset. Para ranks percentis, combine ZCARD e ZREVRANK. Este é um dos casos de uso mais naturais e poderosos do Redis.

redis
# sorted set = perfect for leaderboards
ZADD leaderboard 100 "alice" 250 "bob" 150 "carol"

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

# a player's rank
ZREVRANK leaderboard "alice"     # 0-indexed from top

# 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

Armazenamento de Sessões

Redis é o armazenamento de sessões clássico: rápido, suporta TTL (expiração automática) e é compartilhado entre servidores de app. Use um hash por sessão com TTL deslizante (renove a cada requisição). Acompanhe as sessões de um usuário num set para recursos de 'logout em qualquer dispositivo'. Num cluster, use hash tags ({user:1}) para manter a sessão e o índice de sessões de um usuário no mesmo shard. Rotacione IDs de sessão em login/mudanças de privilégio, por segurança.

redis
# Redis is ideal for web sessions (fast, expiring, shared)
# store session as a hash with TTL
HSET session:abc123 user_id 1 last_active 1700000000 data "..."
EXPIRE session:abc123 1800     # 30-minute timeout

# update session (and refresh TTL)
HSET session:abc123 last_active 1700001000
EXPIRE session:abc123 1800     # sliding expiration

# destroy a session
DEL session:abc123

# list active sessions for a user (index by user)
SADD user:1:sessions "session:abc123"
SMEMBERS user:1:sessions       # all session IDs

# cluster-friendly: use a hash tag for the user's sessions
SADD {user:1}:sessions "session:abc123"
# enables multi-key operations on the user's session data

# rotate session ID on privilege change (security)
RENAME session:old session:new
EXPIRE session:new 1800
19

Scripting Lua

Básico de EVAL

EVAL roda scripts Lua atomicamente — enquanto um script roda, nenhum outro comando executa, tornando-o ideal para operações atômicas de múltiplos passos. KEYS e ARGV passam dados do chamador; nunca construa chaves por concatenação de string no script (viola as regras do cluster). redis.call lança erros (interrompe), redis.pcall os retorna. Scripts são cacheados pelo hash SHA1, então chamadas repetidas usam EVALSHA por eficiência.

redis
# run a Lua script inline
EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 mykey "hello"
# 1 = number of keys
# mykey = KEYS[1]
# "hello" = ARGV[1]

# return types: string/integer/boolean/table (nil/true/false)
EVAL "return 42" 0
EVAL "return {1, 2, 3}" 0
EVAL "return redis.call('GET', KEYS[1])" 1 mykey

# 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 e Cache de Scripts

EVALSHA roda um script previamente carregado pelo seu hash SHA1, evitando reenviar o corpo do script a cada chamada — um grande ganho de banda para apps que rodam o mesmo script repetidamente. Em cache miss (após SCRIPT FLUSH ou reinício), Redis retorna NOSCRIPT; clientes capturam isso e recuam para EVAL + SCRIPT LOAD. Sempre use bibliotecas (redis-py, ioredis) que tratam isso de forma transparente.

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

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

# check if a script is cached
SCRIPT EXISTS "fa00..." "abcd..."
# returns: 1) 1  2) 0

# flush the script cache
SCRIPT FLUSH

# list all running scripts (NOSCRIPT errors = cache miss -> reload)
SCRIPT DEBUG SYNC   # blocking debug mode
SCRIPT DEBUG NO     # disable

Operações Atômicas

Scripts Lua são a forma canônica de fazer operações atômicas de múltiplos comandos no Redis (sem corrida de MULTI/EXEC). Compare-and-set, aquisição de semáforo e migrações de fila se beneficiam de tudo isso. Scripts bloqueiam o servidor enquanto rodam — mantenha-os curtos e evite loops sobre muitas chaves (podem travar outros clientes). Para trabalho muito longo, use Redis Functions (Redis 7.0+), que são declaradas e versionadas como stored procedures.

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

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

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

Redis Functions (7.0+)

Redis Functions (7.0+) são a substituição moderna de scripts EVAL ad hoc: são registradas, nomeadas e versionadas como stored procedures de banco. Uma biblioteca agrupa múltiplas funções; FCALL as invoca. Functions são persistidas em RDB/AOF (sobrevivem a reinícios), diferentemente dos caches efêmeros de EVAL. Tornam o scripting mais sustentável para lógica não trivial, e são mais fáceis de auditar e versionar.

redis
# register a library of functions
FUNCTION LOAD "#!lua name=mylib
redis.register_function('myset', function(keys, args)
  return redis.call('SET', keys[1], args[1])
end)

redis.register_function('double', function(keys, args)
  local v = tonumber(redis.call('GET', keys[1]))
  return redis.call('SET', keys[1], v * 2)
end)
"

# call a function
FCALL myset 1 mykey "hello"
FCALL double 1 counter

# list libraries
FUNCTION LIST
FUNCTION LIST WITHCODE

# delete a library
FUNCTION DELETE mylib

# dump and restore (for backup / migration)
FUNCTION DUMP
FUNCTION RESTORE <payload>

Depurando Scripts

Use redis.log() para emitir mensagens ao log do Redis para depuração sem afetar os valores de retorno. redis-cli --ldb é um depurador Lua interativo: defina breakpoints, percorra o código passo a passo, inspecione locais. SCRIPT DEBUG SYNC faz o servidor bloquear no script, para que o depurador possa avançar passo a passo. Sempre teste scripts em staging — um loop descontrolado pode travar o servidor Redis inteiro. Mantenha os scripts determinísticos (sem random/tempo) para correção da replicação.

redis
# LOG writes to the Redis log (visible in redis-cli)
EVAL "redis.log(redis.LOG_NOTICE, 'hello from lua'); return 1" 0
# levels: LOG_DEBUG, LOG_VERBOSE, LOG_NOTICE, LOG_WARNING

# return the error object on pcall failure
EVAL "local ok, err = pcall(function()
  error('something broke')
end)
return {ok=tostring(ok), err=tostring(err)}" 0

# debugger (Redis 5.0+)
SCRIPT DEBUG SYNC   # synchronous, blocking
TDEBUG              # step / continue / print
# use redis-cli --ldb to launch debugger:
#   redis-cli --ldb --eval myscript.lua key1 key2 , arg1 arg2

# print variables in the debugger
print myvar
step
continue
20

Monitoramento e Solução de Problemas

INFO e LATENCY

INFO é o comando de monitoramento mais importante — reporta memória, clientes, replicação e rendimento numa tacada só. Fique de olho em mem_fragmentation_ratio (ideal ~1.0–1.5); >1.5 desperdiça memória, <1 significa que o Redis está trocando para disco (catastrófico para a latência). LATENCY DOCTOR analisa eventos lentos recentes e sugere correções. Monitore keyspace_misses vs keyspace_hits para acompanhar sua taxa de acerto do cache.

redis
# INFO: server, clients, memory, stats, replication, cpu
INFO                # everything
INFO memory         # memory section only
INFO replication    # replica lag, master link
INFO stats          # ops/sec, keyspace hits/misses

# key metrics to watch:
#   used_memory_rss        # RSS from OS (real footprint)
#   mem_fragmentation_ratio # >1.5 = fragmentation, <1 = swapping (bad!)
#   connected_clients       # client connections
#   instantaneous_ops_per_sec
#   keyspace_misses         # cache hit ratio = hits / (hits + misses)

# LATENCY: samples slow events
LATENCY HISTORY event-name
LATENCY DOCTOR      # human-readable diagnosis
LATENCY RESET

# LATENCY GRAPH event-name (ASCII art)

SLOWLOG e CLIENT LIST

SLOWLOG captura comandos mais lentos que o limiar configurado (padrão 10ms) — inestimável para achar as consultas que causam picos de latência. Operações de KEYSPACE como KEYS * e SMEMBERS em sets enormes são culpadas comuns. CLIENT LIST mostra cada conexão com tempo ocioso e comando atual; use CLIENT SETNAME para rotular as conexões do seu app, para que você identifique a qual pool um cliente travado pertence.

redis
# SLOWLOG: record slow commands (over slowlog-log-slower-than, default 10ms)
CONFIG SET slowlog-log-slower-than 10000   # 10ms in microseconds
CONFIG SET slowlog-max-len 128             # keep last 128 entries

SLOWLOG GET          # last 10 slow commands
SLOWLOG GET 5        # last 5
SLOWLOG RESET        # clear

# each entry: id, timestamp, duration (us), command args, client, addr

# CLIENT LIST: see all connected clients
CLIENT LIST
# fields: id, addr, fd, name, age, idle, flags, db, cmd, ...

# kill a stuck client
CLIENT KILL ADDR 10.0.0.1:12345
CLIENT KILL ID 42

# name your connections for easier debugging
CLIENT SETNAME my-app-worker

MEMORY e OBJECT

MEMORY USAGE reporta os bytes exatos de uma chave (com SAMPLES 0 para precisão total em coleções grandes). OBJECT ENCODING revela o formato interno do Redis — estruturas pequenas usam codificações compactas (listpack, ziplist) que são eficientes em CPU e memória, atualizando automaticamente para tabelas hash / skiplists conforme crescem. Conhecer a codificação ajuda a explicar por que uma chave é maior ou mais lenta que o esperado.

redis
# MEMORY USAGE: bytes used by a single key
MEMORY USAGE key
MEMORY USAGE bigset SAMPLES 0   # scan all elements (accurate)

# MEMORY STATS: detailed allocator stats
MEMORY STATS

# MEMORY DOCTOR: diagnosis
MEMORY DOCTOR

# OBJECT ENCODING: see internal representation
OBJECT ENCODING mylist      # quicklist / ziplist / listpack / hashtable
OBJECT REFCOUNT mykey
OBJECT IDLETIME mykey       # seconds since last access
OBJECT FREQ mykey           # LFU access frequency (only with maxmemory-policy LFU)

# why is my key so big? use DEBUG OBJECT (careful, can be slow)
DEBUG OBJECT mykey

Bigkey e Varredura de Keyspace

Nunca use KEYS em produção — bloqueia o servidor. SCAN é a alternativa baseada em cursor e não bloqueante; itere até o cursor voltar a 0. --bigkeys e --memkeys são helpers da CLI construídos sobre SCAN que revelam as maiores chaves sem bloquear. Chaves grandes (especialmente coleções com milhões de elementos) causam picos de latência durante expiração/despejo — ache-as e divida-as (ex.: faça shard de um sorted set enorme por tempo).

redis
# find big keys safely (production-safe, samples)
redis-cli --bigkeys
# scans keyspace, reports largest of each type

# more accurate: --memkeys (memory usage per key)
redis-cli --memkeys
redis-cli --hotkeys      # with LFU policy, finds frequently-accessed keys

# SCAN: iterate keys without blocking (never use KEYS *)
SCAN 0 MATCH user:* COUNT 100
# returns: next-cursor, [key1, key2, ...]
SCAN <next-cursor> ...
# cursor 0 = done

# scan a hash field-by-field
HSCAN myhash 0 COUNT 100
SSCAN myset 0 MATCH prefix*
ZSCAN myzset 0

# inspect a key's TTL (left to live)
TTL mykey           # seconds (-1 = no expire, -2 = no key)
PTTL mykey          # milliseconds

Saúde e Failover do Cluster

CLUSTER NODES e CLUSTER INFO são as checagens primárias de saúde do cluster — procure cluster_state:ok e que cada um dos slots está atribuído (16384 no total). CLUSTER FAILOVER numa réplica aciona uma troca de mestre controlada; FORCE pula a sincronização inicial (mais rápido, mas leve risco de perda de dados) e TAKEOVER contorna o consenso do cluster (use só em emergências). Sempre rode --cluster check após reshards ou incidentes, para capturar slots órfãos ou estados de split-brain.

redis
# cluster node status
CLUSTER NODES
# fields: id, addr, flags (master/slave/fail?), slots, ping/pong

# cluster-wide health
CLUSTER INFO
# cluster_state:ok / cluster_slots_assigned / cluster_slots_ok
# cluster_known_nodes

# slot ownership (which node owns a key)
CLUSTER KEYSLOT mykey    # hash slot number
CLUSTER COUNTKEYSINSLOT 1234

# reshard slots (use redis-cli --cluster reshard)
redis-cli --cluster reshard 127.0.0.1:7000 \
  --cluster-from <node-id> --cluster-to <node-id> \
  --cluster-slots 1000 --cluster-yes

# manual failover (on a replica)
CLUSTER FAILOVER          # wait for sync
CLUSTER FAILOVER FORCE    # skip sync (faster, slight data loss risk)
CLUSTER FAILOVER TAKEOVER # no consensus (emergency only)

# verify cluster after changes
redis-cli --cluster check 127.0.0.1:7000
redis-cli --cluster fix 127.0.0.1:7000    # auto-repair minor issues

Was this helpful?