# facebook/rocksdb architecture

> Architecture diagram of the GitHub repository facebook/rocksdb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/rocksdb
- Repository: https://github.com/facebook/rocksdb
- Video tour (about a minute): https://gitdiagram.com/facebook/rocksdb/video

## Overview

RocksDB is an embeddable persistent key-value store built around an LSM design. A caller opens a database and uses its public API to read or write key-value data; internally, the product also manages storage files, compaction, caches, and backup/restore. The README establishes the LSM and multithreaded-compaction roles, while the source index exposes selected implementation dependencies. Many detailed runtime connections are not shown in the excerpts, so those are omitted rather than inferred.

Main entry points: [`db/db_impl/db_impl.cc`](https://github.com/facebook/rocksdb/blob/main/db/db_impl/db_impl.cc) (Database implementation), [`utilities/backup/backup_engine.cc`](https://github.com/facebook/rocksdb/blob/main/utilities/backup/backup_engine.cc) (Backup and restore), [`include/rocksdb/db.h`](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/db.h) (DB API), [`db/wal_manager.cc`](https://github.com/facebook/rocksdb/blob/main/db/wal_manager.cc) (WAL manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_dbapi["DB API<br/>[db.h]"]
  node_options["DB options<br/>[options.h]"]
end

subgraph group_engine["Database Engine"]
  node_dbimpl["Database implementation<br/>[db_impl.cc]"]
  node_memtable["Memtable<br/>[memtable.cc]"]
  node_wal["WAL manager<br/>[wal_manager.cc]"]
  node_read["Read iteration<br/>[db_iter.cc]"]
  node_flush["Flush jobs<br/>[flush_job.cc]"]
  node_compact["Compaction jobs<br/>[compaction_job.cc]"]
  node_versions["Version metadata<br/>[version_set.cc]"]
end

subgraph group_storage["Storage and Files"]
  node_blob["Blob files"]
  node_env["Environment API<br/>[env.h]"]
  node_filesystem["File system API<br/>[file_system.h]"]
  node_filewriter["Writable file writer"]
end

subgraph group_services["Caches and Backups"]
  node_cache["Block and object caches<br/>[cache.cc]"]
  node_reservation["Cache reservations"]
  node_backupapi["Backup API<br/>[backup_engine.h]"]
  node_backup["Backup and restore<br/>[backup_engine.cc]"]
  node_copy["File copy engine<br/>[copy_engine.cc]"]
end

subgraph group_primitives["Core Primitives"]
  node_slice["Slice values<br/>[slice.h]"]
  node_status["Status results<br/>[status.h]"]
  node_coding["Binary encoding<br/>[coding.h]"]
  node_port["Platform abstraction<br/>[port.h]"]
  node_logging["Logging interface<br/>[logging.h]"]
end

node_caller(("Database caller"))

node_caller -->|"calls"| node_dbapi
node_dbapi -.->|"serves requests"| node_dbimpl
node_dbimpl -.->|"updates"| node_memtable
node_dbimpl -.->|"manages logs"| node_wal
node_dbimpl -.->|"serves reads"| node_read
node_dbimpl -.->|"schedules flush"| node_flush
node_dbimpl -.->|"runs compaction"| node_compact
node_wal -->|"references"| node_versions
node_dbimpl -.->|"uses blob storage"| node_blob
node_dbimpl -.->|"uses caches"| node_cache
node_reservation -->|"reserves space"| node_cache
node_backupapi -->|"implements operations"| node_backup
node_backup -->|"submits copy work"| node_copy
node_backup -->|"copies files"| node_filesystem
node_filewriter -->|"writes through"| node_filesystem
node_dbimpl -.->|"uses configuration"| node_options
node_dbimpl -.->|"uses environment"| node_env

click node_dbapi "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/db.h"
click node_options "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/options.h"
click node_dbimpl "https://github.com/facebook/rocksdb/blob/main/db/db_impl/db_impl.cc"
click node_memtable "https://github.com/facebook/rocksdb/blob/main/db/memtable.cc"
click node_wal "https://github.com/facebook/rocksdb/blob/main/db/wal_manager.cc"
click node_read "https://github.com/facebook/rocksdb/blob/main/db/db_iter.cc"
click node_flush "https://github.com/facebook/rocksdb/blob/main/db/flush_job.cc"
click node_compact "https://github.com/facebook/rocksdb/blob/main/db/compaction/compaction_job.cc"
click node_versions "https://github.com/facebook/rocksdb/blob/main/db/version_set.cc"
click node_blob "https://github.com/facebook/rocksdb/blob/main/db/blob/blob_file_partition_manager.cc"
click node_env "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/env.h"
click node_filesystem "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/file_system.h"
click node_filewriter "https://github.com/facebook/rocksdb/blob/main/file/writable_file_writer.h"
click node_cache "https://github.com/facebook/rocksdb/blob/main/cache/cache.cc"
click node_reservation "https://github.com/facebook/rocksdb/blob/main/cache/cache_reservation_manager.h"
click node_backupapi "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/utilities/backup_engine.h"
click node_backup "https://github.com/facebook/rocksdb/blob/main/utilities/backup/backup_engine.cc"
click node_copy "https://github.com/facebook/rocksdb/blob/main/utilities/copy_engine/copy_engine.cc"
click node_slice "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/slice.h"
click node_status "https://github.com/facebook/rocksdb/blob/main/include/rocksdb/status.h"
click node_coding "https://github.com/facebook/rocksdb/blob/main/util/coding.h"
click node_port "https://github.com/facebook/rocksdb/blob/main/port/port.h"
click node_logging "https://github.com/facebook/rocksdb/blob/main/logging/logging.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dbapi,node_options toneBlue
class node_dbimpl,node_memtable,node_wal,node_read,node_flush,node_compact,node_versions,node_caller toneAmber
class node_blob,node_env,node_filesystem,node_filewriter toneMint
class node_cache,node_reservation,node_backupapi,node_backup,node_copy toneRose
class node_slice,node_status,node_coding,node_port,node_logging toneIndigo
```

## Components

### Public API

- [DB API](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/db.h): `include/rocksdb/db.h`
- [DB options](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/options.h): `include/rocksdb/options.h`

### Database Engine

- [Database implementation](https://github.com/facebook/rocksdb/blob/main/db/db_impl/db_impl.cc): `db/db_impl/db_impl.cc`
- [Memtable](https://github.com/facebook/rocksdb/blob/main/db/memtable.cc): `db/memtable.cc`
- [WAL manager](https://github.com/facebook/rocksdb/blob/main/db/wal_manager.cc): `db/wal_manager.cc`
- [Read iteration](https://github.com/facebook/rocksdb/blob/main/db/db_iter.cc): `db/db_iter.cc`
- [Flush jobs](https://github.com/facebook/rocksdb/blob/main/db/flush_job.cc): `db/flush_job.cc`
- [Compaction jobs](https://github.com/facebook/rocksdb/blob/main/db/compaction/compaction_job.cc): `db/compaction/compaction_job.cc`
- [Version metadata](https://github.com/facebook/rocksdb/blob/main/db/version_set.cc): `db/version_set.cc`

### Storage and Files

- [Blob files](https://github.com/facebook/rocksdb/blob/main/db/blob/blob_file_partition_manager.cc): `db/blob/blob_file_partition_manager.cc`
- [Environment API](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/env.h): `include/rocksdb/env.h`
- [File system API](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/file_system.h): `include/rocksdb/file_system.h`
- [Writable file writer](https://github.com/facebook/rocksdb/blob/main/file/writable_file_writer.h): `file/writable_file_writer.h`

### Caches and Backups

- [Block and object caches](https://github.com/facebook/rocksdb/blob/main/cache/cache.cc): `cache/cache.cc`
- [Cache reservations](https://github.com/facebook/rocksdb/blob/main/cache/cache_reservation_manager.h): `cache/cache_reservation_manager.h`
- [Backup API](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/utilities/backup_engine.h): `include/rocksdb/utilities/backup_engine.h`
- [Backup and restore](https://github.com/facebook/rocksdb/blob/main/utilities/backup/backup_engine.cc): `utilities/backup/backup_engine.cc`
- [File copy engine](https://github.com/facebook/rocksdb/blob/main/utilities/copy_engine/copy_engine.cc): `utilities/copy_engine/copy_engine.cc`

### Core Primitives

- [Slice values](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/slice.h): `include/rocksdb/slice.h`
- [Status results](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/status.h): `include/rocksdb/status.h`
- [Binary encoding](https://github.com/facebook/rocksdb/blob/main/util/coding.h): `util/coding.h`
- [Platform abstraction](https://github.com/facebook/rocksdb/blob/main/port/port.h): `port/port.h`
- [Logging interface](https://github.com/facebook/rocksdb/blob/main/logging/logging.h): `logging/logging.h`

### Other components

- **Database caller**

## Connections

- Database caller → DB API: calls (evidence: `README.md`)
- DB API → Database implementation: serves requests
- Database implementation → Memtable: updates
- Database implementation → WAL manager: manages logs
- Database implementation → Read iteration: serves reads
- Database implementation → Flush jobs: schedules flush
- Database implementation → Compaction jobs: runs compaction
- WAL manager → Version metadata: references (evidence: `db/wal_manager.cc`)
- Database implementation → Blob files: uses blob storage
- Database implementation → Block and object caches: uses caches
- Cache reservations → Block and object caches: reserves space (evidence: `cache/cache_reservation_manager.h`)
- Backup API → Backup and restore: implements operations
- Backup and restore → File copy engine: submits copy work (evidence: `utilities/backup/backup_engine.cc`)
- Backup and restore → File system API: copies files (evidence: `utilities/backup/backup_engine.cc`)
- Writable file writer → File system API: writes through (evidence: `file/writable_file_writer.h`)
- Database implementation → DB options: uses configuration
- Database implementation → Environment API: uses environment
