← CatZep/Engineering Guides/Reference/System Internals Guides

← Back to index

Redis — Internal Architecture

A developer's guide to how Redis actually works under the hood: the single-threaded event loop, the data structures and their encodings, the RESP protocol, expiry and eviction, persistence, replication, and how it scales out with Sentinel and Cluster.

Redis is an in-memory data structure server. Unlike a traditional database that keeps data on disk and caches hot pages in memory, Redis keeps the entire dataset in RAM and treats disk only as a durability backstop. Its second defining choice is that command execution is single-threaded: one logical thread runs commands one at a time, which removes locks and makes every individual command atomic. Those two decisions — memory-resident data and a single-threaded execution model — explain almost everything else about how Redis behaves, from its microsecond latencies to the way it persists, replicates, and shards. This guide walks through the internals a developer needs to reason about Redis confidently.

Concepts explained in this guide

Read these definitions first, or use the linked terms as you go. The examples and limitations are local to this guide; companion pages are optional.

1. Design Goals and Core Ideas

Every internal decision in Redis traces back to a small set of goals. Keeping them in mind makes the rest of the architecture predictable.

2. Architecture and the Event Loop

At its core Redis is a single process running an event loop. It uses the operating system's efficient I/O readiness mechanism (epoll on Linux, kqueue on BSD/macOS) to wait for many client sockets at once and wake up only when one of them has data ready. There is no thread per connection; one thread multiplexes thousands of clients.

One iteration of the loop does the following:

• Poll for readiness: epoll_wait() returns the set of file descriptors that have data to read or room to write. Redis registers a callback per event type.
• Read and parse: for a readable client socket, Redis reads the bytes and parses the RESP request into a command plus arguments.
• Dispatch and execute: the command name is looked up in the command table and executed against the keyspace. Because this happens on one thread, the command runs to completion with nothing else touching the data — that is the source of atomicity.
• Build and queue the reply: the result is serialized into RESP and queued on the client's output buffer, to be written when the socket is writable.
• Run background work: the loop also fires time events — active expiration, incremental rehashing, client timeouts, and similar housekeeping.

I/O threads (Redis 6.0+). Profiling showed that on busy servers a large share of CPU was spent in the kernel reading request bytes and writing reply bytes, not in executing commands. Redis 6 added an optional pool of I/O threads that parallelize only the socket read/parse and reply-write steps. The actual command execution remains single-threaded, so atomicity and the no-locks model are preserved while throughput on multi-core machines improves.

while server_running:
  events = epoll_wait(fds)            # block until sockets ready
  for fd in events.readable:
    buf = read(fd)                    # (optionally on an I/O thread)
    cmd, args = parse_resp(buf)
    reply = dispatch(cmd, args)       # executes on the MAIN thread, atomically
    queue_output(fd, reply)
  for fd in events.writable:
    write(fd, output_buffer[fd])      # (optionally on an I/O thread)
  run_time_events()                   # expiry, rehashing, timeouts

3. Data Structures and Internal Encodings

Redis exposes a handful of data types — string, list, hash, set, sorted set, and stream — but each type can be stored internally in more than one way. Redis picks a compact encoding when a value is small and transparently upgrades to a general encoding once it grows past a configurable threshold. The command behavior is identical; only memory layout and performance characteristics change.

The key encodings are:

4. RESP Protocol and Command Flow

Clients talk to Redis using RESP (REdis Serialization Protocol) — a simple, line-oriented, binary-safe protocol that is easy to parse and human-readable on the wire. A request is an array of bulk strings: the command name followed by its arguments. The reply is a single RESP value whose type depends on the command.

RESP uses a one-byte type prefix to tell the parser what follows:

The full flow for a single command is short, which is the point — minimal per-command overhead:

# Client sends: SET foo bar  ->  *3\r\n$3\r\nSET\r\n$3\r\nfoo\r\n$3\r\nbar\r\n
function handle_request(socket):
  bytes = socket.read()
  argv  = parse_resp(bytes)            # ["SET", "foo", "bar"]
  cmd   = command_table.lookup(argv[0])
  if cmd is None:
    return reply_error("unknown command")
  if not cmd.arity_ok(argv):
    return reply_error("wrong number of arguments")
  result = cmd.proc(argv)              # mutate the keyspace, atomically
  return encode_resp(result)           # "+OK\r\n"

Pipelining falls out of this design for free: a client may send many requests back to back without waiting for each reply. Redis reads them all, executes them in order, and sends the replies in order, which amortizes network round-trip time across many commands. MULTI/EXEC transactions go one step further by queuing commands and executing the whole batch as one uninterrupted unit on the single thread.

5. Expiry and Eviction

Expiry removes an entry after its configured time; eviction makes room under a memory policy. These are different. Lazy expiry on access and active sampling reclaim expired keys, but TTL does not prove the underlying source value is fresh. A recently cached stale value can still be within its TTL.

Expiry uses authority clocks/configuration; wall clocks can jump. Replication and command type affect observed behavior. Eviction policies such as approximate LRU/LFU choose candidates under their supported algorithm, not an exact universal ordering. Limits, buffers, overhead, persistence/fork memory, and non-evictable state also affect memory pressure.

noeviction rejects appropriate memory-growing work rather than guaranteeing all commands succeed. Use actual policy and workload measurements; approximate algorithms and defaults depend on release/configuration.

6. Persistence: RDB and AOF

RDB snapshots provide a recoverable point-in-time image. fork/copy-on-write lets a child write while the parent continues, but fork can pause and copied pages can consume substantial extra memory. Writes since the last valid snapshot are not preserved by that snapshot alone.

AOF records operations under its configured flush/sync policy. always requests frequent durable completion; everysec targets periodic fsync, but disk stalls/scheduling/errors can exceed a strict one-second loss bound. no leaves more to operating-system behavior. Persistence may be disabled; format defaults do not imply it is enabled.

Modern AOF designs can use multiple files/manifests and snapshot preambles. Rewrite, file publication, recovery ordering, storage behavior, and backup validation are release-specific. Do not equate 'appended' with power-loss durable or promise zero blocking during rewrite.

7. Replication

Replication is normally asynchronous: acknowledged primary state may be absent from a promoted replica. Backlog/PSYNC handles supported partial resynchronization; falling outside retained history requires a supported full sync. Replication IDs/offsets and the snapshot boundary must agree.

WAIT can wait for replication acknowledgements for prior writes on the relevant connection, reducing some risks. It does not turn Redis into a consensus/linearizable durable store or guarantee the failover procedure selects a copy with every acknowledged write. Durability-related commands/options such as supported AOF-wait policies have their own release-specific scope.

Sentinel coordinates failover; Redis Cluster has its own cluster/failover protocol and is not literally Sentinel wrapped around each shard. Both retain declared failure assumptions. Hard quota/financial invariants need a store/protocol whose loss and ownership contracts actually enforce them.

8. High Availability and Scale

Replication by itself gives you read scaling and a warm copy, but a human still has to react when the master dies, and the whole dataset must fit on one machine. Redis solves the first problem with Sentinel and the second with Cluster.

Sentinel: automatic failover

Sentinel is a separate process (run in odd numbers, typically three or five, for quorum) that monitors a master and its replicas. When enough sentinels agree the master is unreachable, they elect a leader among themselves, promote a suitable replica to master, reconfigure the other replicas to follow it, and tell clients where the new master is. Sentinel provides high availability but not sharding — the entire dataset still lives on one master at a time.

Cluster: sharding the keyspace

Redis Cluster partitions the keyspace across many master shards. The mechanism is a fixed map of 16384 hash slots. Every key is assigned to a slot by CRC16(key) mod 16384, and every slot is owned by exactly one shard. To distribute data you simply distribute slot ownership; each shard typically also has replicas for HA, so Cluster folds in the Sentinel-style failover too.

Resharding moves slots from one shard to another online, key by key, while the cluster keeps serving traffic. The combination of a fixed slot count, deterministic CRC16 hashing, and MOVED/ASK redirects lets the cluster rebalance without a coordinator and without taking the keyspace offline.

# client-side routing in a Redis Cluster
function cluster_route(key):
  slot = crc16(hash_tag(key)) % 16384  # {tag} forces co-location
  node = slot_map[slot]                # cached topology
  resp = send(node, command)
  if resp.is_moved():                  # wrong shard, topology changed
    slot_map[resp.slot] = resp.addr    # update cache
    return send(resp.addr, command)
  if resp.is_ask():                    # slot mid-migration
    return send(resp.addr, ASKING + command)  # one-shot redirect
  return resp

Worked example: a command is atomic but a pair is racy

Two clients read the same counter and each then writes an increment.

Run and change the example

Download guide_labs.py. Python 3.10+, standard library only. In its directory, run:

python3 guide_labs.py transactions
python3 guide_labs.py test

The SQLite teaching model contrasts atomic local effects with a deliberately racy read/modify/write sequence; it is not a Redis server.

The program tests its stated finite contracts. It is an educational model, not an implementation of the named production product or a proof of unmodeled distributed faults.

9. Summary

The whole system is built from a few reinforcing ideas: