valkey-io/valkey

A flexible distributed key-value database that is optimized for caching and other realtime workloads.

25,314 stars C 13 components 5 connections

Distributed key-value database forked from Redis, optimized for caching

Client commands flow through protocol parsing, command lookup, execution, and response generation, with optional persistence logging

Under the hood, the system uses 3 feedback loops, 4 data pools, 4 control points to manage its runtime behavior.

Structural Verdict

A 13-component repository with 5 connections. 867 files analyzed. Loosely coupled — components are relatively independent.

How Data Flows Through the System

Client commands flow through protocol parsing, command lookup, execution, and response generation, with optional persistence logging

Accept Connection — Server accepts client TCP connections and sets up read handlers
Parse Protocol — Read and parse Redis protocol (RESP) from client socket buffer
Lookup Command — Find command in command table and validate arguments
Execute Command — Call command handler function to modify data structures
Log to AOF — Append command to append-only file for durability if enabled
Send Response — Format and send response back to client through socket
Replicate — Forward command to slave nodes if replication is configured

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Redis Database (in-memory)
Main key-value store with multiple database slots

AOF Buffer (buffer)
Write buffer for append-only file persistence

Replication Backlog (buffer)
Circular buffer storing recent commands for partial resync

Client Output Buffers (buffer)
Per-client buffers for responses waiting to be sent

Feedback Loops

Memory Management (circuit-breaker, balancing) — Trigger: Memory usage exceeds maxmemory limit. Action: Apply eviction policy (LRU, LFU, etc.) to free memory. Exit: Memory usage drops below threshold.
Replication Reconnect (retry, balancing) — Trigger: Connection to master lost. Action: Attempt to reconnect with exponential backoff. Exit: Successful reconnection or manual intervention.
AOF Rewrite (auto-scale, balancing) — Trigger: AOF file size exceeds configured threshold. Action: Create new AOF file with current database snapshot. Exit: Rewrite completed and old AOF replaced.

Delays & Async Processing

Key Expiration (scheduled-job, ~1ms intervals) — Expired keys are lazily deleted during access or periodic cleanup
AOF Fsync (async-processing, ~1 second (configurable)) — Write durability depends on fsync policy (always/everysec/no)
RDB Background Save (async-processing, ~variable (depends on data size)) — Fork-based snapshots may cause brief latency spikes

Control Points

maxmemory (threshold) — Controls: Maximum memory usage before eviction kicks in. Default: 0 (disabled)
save (runtime-toggle) — Controls: RDB save intervals based on key changes. Default: 900 1 300 10 60 10000
appendonly (feature-flag) — Controls: Whether AOF persistence is enabled. Default: no
cluster-enabled (feature-flag) — Controls: Enables Redis Cluster mode for horizontal scaling. Default: no

Technology Stack

C (language)
Primary implementation language

CMake (build)
Build system

jemalloc (library)
Memory allocator

Lua (library)
Embedded scripting engine

hdr_histogram (library)
Latency measurement

Google Test (testing)
Unit testing framework

linenoise (library)
Line editing for CLI

fast_float (library)
Fast floating point parsing

Key Components

server.c main() (function) — Main entry point that initializes the server, loads configuration, and starts the event loop src/server.c
networking.c (module) — Handles client connections, command parsing, and Redis protocol implementation src/networking.c
processCommand (function) — Central command dispatcher that validates and executes Redis commands src/server.c
db.c (module) — Core database operations like key lookup, expiration, and database selection src/db.c
object.c (module) — Redis object system managing different data types and their encodings src/object.c
rdb.c (module) — Implements RDB snapshot format for persistence and point-in-time backups src/rdb.c
aof.c (module) — Append-only file persistence for durability and crash recovery src/aof.c
cluster.c (module) — Redis Cluster implementation for horizontal scaling and sharding src/cluster.c
replication.c (module) — Master-slave replication for high availability and read scaling src/replication.c
module.c (module) — Module API system allowing third-party extensions to add new commands and data types src/module.c
scripting.c (module) — Lua scripting engine integration for server-side computation src/scripting.c
jemalloc (module) — Memory allocator optimized for multi-threaded applications with low fragmentation deps/jemalloc/
+1 more components

Configuration

codecov.yml (yaml)

coverage.status.patch.default.informational (boolean, unknown) — default: true
coverage.status.project.default.informational (boolean, unknown) — default: true
comment.require_changes (boolean, unknown) — default: false
comment.require_head (boolean, unknown) — default: false
comment.require_base (boolean, unknown) — default: false
comment.layout (string, unknown) — default: condensed_header, diff, files
comment.hide_project_coverage (boolean, unknown) — default: false
comment.behavior (string, unknown) — default: default
+1 more parameters

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Repository Repositories

Frequently Asked Questions

What is valkey used for?

Distributed key-value database forked from Redis, optimized for caching valkey-io/valkey is a 13-component repository written in C. Loosely coupled — components are relatively independent. The codebase contains 867 files.

How is valkey architected?

valkey is organized into 5 architecture layers: Core Server, Data Structures, Networking & Protocol, Persistence & Replication, and 1 more. Loosely coupled — components are relatively independent. This layered structure keeps concerns separated and modules independent.

How does data flow through valkey?

Data moves through 7 stages: Accept Connection → Parse Protocol → Lookup Command → Execute Command → Log to AOF → .... Client commands flow through protocol parsing, command lookup, execution, and response generation, with optional persistence logging This pipeline design reflects a complex multi-stage processing system.

What technologies does valkey use?

The core stack includes C (Primary implementation language), CMake (Build system), jemalloc (Memory allocator), Lua (Embedded scripting engine), hdr_histogram (Latency measurement), Google Test (Unit testing framework), and 2 more. A focused set of dependencies that keeps the build manageable.

What system dynamics does valkey have?

valkey exhibits 4 data pools (Redis Database, AOF Buffer), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle circuit-breaker and retry. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does valkey use?

5 design patterns detected: Event-driven Architecture, Object System with Reference Counting, Command Table Dispatch, Modular Data Types, Dual Persistence.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.