If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/facebook/rocksdb shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 18 active contributors
• Distributed ownership (top contributor 29% of recent commits)
• GPL-2.0 licensed
• CI configured
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live facebook/rocksdb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebook/rocksdb.

What it runs against: a local clone of facebook/rocksdb — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in facebook/rocksdb | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebook/rocksdb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebook/rocksdb.git
#   cd rocksdb
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of facebook/rocksdb and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "facebook/rocksdb(\\.git)?\\b" \\
  && ok "origin remote is facebook/rocksdb" \\
  || miss "origin remote is not facebook/rocksdb (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "include/rocksdb/db.h" \\
  && ok "include/rocksdb/db.h" \\
  || miss "missing critical file: include/rocksdb/db.h"
test -f "db/db_impl/db_impl.h" \\
  && ok "db/db_impl/db_impl.h" \\
  || miss "missing critical file: db/db_impl/db_impl.h"
test -f "db/version_set.h" \\
  && ok "db/version_set.h" \\
  || miss "missing critical file: db/version_set.h"
test -f "table/block_based/block_based_table_reader.h" \\
  && ok "table/block_based/block_based_table_reader.h" \\
  || miss "missing critical file: table/block_based/block_based_table_reader.h"
test -f "util/options.h" \\
  && ok "util/options.h" \\
  || miss "missing critical file: util/options.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/facebook/rocksdb"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RocksDB is an embeddable, persistent key-value store library optimized for fast storage on flash drives and RAM. Built on LSM (Log-Structured-Merge) tree architecture, it provides configurable trade-offs between write amplification, read amplification, and space amplification, with multi-threaded compactions enabling storage of multiple terabytes in a single database instance. Core library structured as C++ core (db/, table/, cache/, util/ directories contain LSM engine) wrapped by Java bindings (java/ directory, built via Maven), with CMake/Makefile dual build system. Examples in examples/ directory demonstrate C++ API usage; .github/actions/ contains reusable build/test automation; .clang-tidy and .clang-format enforce code standards.

Backend infrastructure engineers and database systems developers at scale (Facebook, LinkedIn, etc.) who need an embedded key-value store for high-throughput data ingestion, search indexing, and time-series storage without managing a separate database service.

Highly mature and production-ready: maintained by Facebook Database Engineering Team since inception, built atop Google LevelDB lineage, with extensive CI/CD via GitHub Actions (.github/workflows contains benchmark, clang-tidy, and multi-OS test pipelines). Active development visible across 26M+ LOC in C++ with comprehensive GitHub Actions automation for pre-commit checks.

Low risk for established use cases but non-negligible API surface: public interface constrained to include/ directory per README, but internal APIs explicitly may change without warning. Large C++ codebase (26.8M LOC) requires careful dependency compatibility; dual GPLv2/Apache 2.0 licensing requires legal review for commercial use. No single-point-of-failure risk given Facebook backing, but breaking changes possible across major versions.

Active CI/CD enhancement: .github/workflows shows recent investment in AI-assisted code review (claude-review.yml, codex-review.yml), benchmark automation (benchmark-linux.yml), and cross-platform testing. .github/scripts/compute-test-shard.sh indicates ongoing work on test distribution and performance validation.

git clone https://github.com/facebook/rocksdb.git
cd rocksdb
make -j$(nproc)  # Uses Makefile (194KB); CMake also available
# Or with CMake: mkdir build && cd build && cmake .. && make -j$(nproc)

Daily commands: RocksDB is a library, not a service. Link librocksdb.a or librocksdb.so into your application. Run examples: cd examples && make or execute compiled binaries from examples/rocksdb_simple.cc (C++) or rocksdb_example.java (Java via mvn compile exec:java).

• include/rocksdb/db.h — Primary public API interface defining DB, ColumnFamily, and core operations that all integrations depend on.
• db/db_impl/db_impl.h — Core DBImpl class implementing the LSM tree logic, compaction, and lifecycle management central to RocksDB's functionality.
• db/version_set.h — Version management system tracking LSM tree metadata and file layouts; critical for consistency and recovery.
• table/block_based/block_based_table_reader.h — SST file format parser and reader; fundamental to data retrieval path from persistent storage.
• util/options.h — Configuration options affecting performance, durability, and behavior across all RocksDB operations.
• db/write_batch.h — Atomic batch write abstraction enabling transactional semantics and write amplification optimization.
• CMakeLists.txt — Primary build configuration defining compilation targets, dependencies, and platform-specific settings.

Add a New Compaction Strategy

1. Create a new compaction picker class inheriting from CompactionPicker in db/ (db/compaction_picker.h)
2. Implement PickCompaction() method with your strategy logic (db/compaction_picker.cc)
3. Register the new picker in DBImpl::PickCompaction() based on options (db/db_impl/db_impl.cc)
4. Add configuration option to DBOptions struct (include/rocksdb/options.h)

Add a New Compression Algorithm

1. Add enum value in CompressionType in include/rocksdb/compression_type.h (include/rocksdb/compression_type.h)
2. Implement compress/decompress functions in util/compression.cc (util/compression.cc)
3. Update BlockBasedTableBuilder to handle new compression type (table/block_based/block_based_table_builder.cc)
4. Update BlockBasedTableReader to decompress new format (table/block_based/block_based_table_reader.cc)

Add a New Configuration Option

1. Add field to appropriate Options struct (DBOptions, ColumnFamilyOptions, etc.) (include/rocksdb/options.h)
2. Add option name string mapping in options_helper.cc (util/options_helper.cc)
3. Implement option parsing in GetOptionsFromString() (util/options_parser.cc)
4. Use option value in relevant implementation (e.g., DBImpl::VersionSet, CompactionPicker) (db/db_impl/db_impl.cc)

• Log-Structured-Merge (LSM) Tree — Optimizes write throughput by converting random I/O to sequential writes; reduces write amplification for flash storage while enabling efficient compaction
• Multi-level LSM with Level Compaction — Enables tunable tradeoffs between write amplification (WAF), read amplification (RAF), and space amplification (SAF) via level sizing and compaction strategy
• Write-Ahead Logging (WAL) — Provides crash recovery guarantees; enables atomic batch writes and point-in-time recovery
• Block-based SST Format with Compression — Reduces on-disk size via compression; enables efficient block-level caching and random access within files
• Multi-threaded Compaction — Allows background compaction to scale with CPU cores; prevents write stalls from I/O-heavy compaction on large datasets
• LRU Block Cache — Accelerates repeated reads by caching hot blocks in memory; configurable to balance memory usage and hit rate

• LSM design (write-optimized) vs. B-tree (read-optimized)

  • Why: RocksDB prioritizes write throughput and flash storage suitability over read latency guarantees.
  • Consequence: Reads may touch multiple levels before finding a key; background compaction consumes CPU/I/O continuously. Trade read-amplification for sustained write performance.

• Synchronous WAL writes (default) vs. async buffering

  • Why: Ensures durability on every write; critical for correctness on embedded systems.
  • Consequence: WAL write latency can bottleneck high-throughput workloads; group commits help amortize cost.

• Per-operation compaction vs. whole-database defragmentation

  • Why: Incremental compaction reduces pauses and enables online operation.
  • Consequence: Space amplification (SAF) can grow in steady state; levels must be sized carefully to bound fragmentation.

• Thread-local memtables + cross-memtable compaction

  • Why: Reduces lock contention on high-concurrency writes.
  • Consequence: Compaction complexity increases; careful memory management needed to prevent OOM from multiple memtables.

• Does not provide distributed replication or clustering (single-node embedded database)
• Does not guarantee linearizable consistency across concurrent transactions (eventual consistency model)
• Not a real-time database; background compaction and GC can cause unpredictable latency spikes
• Does not handle query languages (SQL); provides only key-value interface
• Not designed for small objects or frequent scans (LSM overhead favors batch/sequential access)

C++ standard: Codebase targets C++11 minimum but uses features up to C++17; compiler version mismatches cause silent failures. Platform-specific behavior: endianness assumptions in block encoding (table/format.h); test on both big- and little-endian systems. Snapshots must be released: Calling GetSnapshot() without ReleaseSnapshot() blocks compaction and causes unbounded memory growth—common bug in long-running applications. Java GC pauses: JNI bindings allocate off-heap, but GC pause during compaction can deadlock if not configured correctly (see java/rocksjni.* for context).

• Log-Structured-Merge (LSM) Tree — RocksDB's core data structure trades random reads for sequential writes; understanding LSM trade-offs (WAF/RAF/SAF) is essential to tune performance for your workload
• Write-Ahead Logging (WAL) — RocksDB uses WAL for durability guarantees; misconfigured fsync policies can silently lose data on crash despite RocksDB appearing to acknowledge writes
• Bloom Filters — RocksDB uses Bloom filters in SST metadata to skip files during Gets; understanding false positive rates affects point-lookup performance by orders of magnitude
• Compaction Strategy — RocksDB supports leveled and universal compaction modes (db/compaction_picker.cc); choice directly impacts write amplification and query latency tail percentiles
• MVCC (Multi-Version Concurrency Control) — RocksDB snapshots (db/snapshot.h) implement MVCC to allow concurrent reads during writes; misunderstanding snapshot lifetime causes memory leaks
• Block Cache and LRU Eviction — Uncompressed block cache (cache/lru_cache.cc) is primary hot-path bottleneck; cache miss rates directly determine read latency variance across your entire application
• Consistent Hashing / Hash Functions — RocksDB's internal key hashing for partitioning (util/hash.cc) must be stable; poor hash distribution leads to unbalanced LSM levels and performance cliff at specific data sizes

• google/leveldb — Direct predecessor; RocksDB forked and enhanced LevelDB with multi-threaded compaction and better configurability
• facebookincubator/mysql-5.7 — MyRocks storage engine integrates RocksDB as MySQL backend, demonstrating production embedding
• tikv/tikv — Distributed key-value store built on RocksDB as its local storage engine for consistency
• cockroachdb/cockroach — Originally used RocksDB as storage layer; architectural peer solving similar scale problems
• facebook/folly — Utility library used by RocksDB for concurrency primitives (.github/actions/build-folly/ indicates tight integration)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Windows-specific GitHub Action workflow for comprehensive CI coverage

The repo has .github/actions/windows-build-steps/action.yml but no dedicated Windows CI workflow file in .github/workflows/. Currently, Windows testing appears to be missing from the main PR validation pipeline (pr-jobs.yml, pr-jobs-candidate.yml). This is critical for a cross-platform storage library since Windows has different file I/O semantics, memory management, and path handling that can cause regressions.

• [ ] Create .github/workflows/windows-ci.yml with matrix strategy for Windows Server 2019/2022 and MSVC versions
• [ ] Integrate existing .github/actions/windows-build-steps/action.yml into the new workflow
• [ ] Add Windows-specific test matrix covering Debug/Release builds and different architectures (x86/x64)
• [ ] Reference Directory.Build.props for Windows-specific build configuration
• [ ] Ensure workflow runs on pull_request and push to main branch

Add comprehensive benchmarking regression detection to benchmark-linux.yml

The repo has .github/workflows/benchmark-linux.yml and .github/actions/perform-benchmarks/action.yml, but no automated regression detection or comparison against baseline benchmarks. For a performance-critical database library, benchmarks are only useful if they alert maintainers to performance regressions. The current setup appears to run benchmarks but doesn't fail on degradation.

• [ ] Extend .github/workflows/benchmark-linux.yml to store benchmark results as artifacts with consistent naming
• [ ] Add step to download baseline benchmark results from main branch using .github/actions/cache-* patterns
• [ ] Implement JSON comparison logic in .github/scripts/ (similar to parse-claude-review.js structure) to detect >5-10% regressions
• [ ] Add automatic comment on PRs with benchmark comparison results using .github/scripts/post-pr-comment.js pattern
• [ ] Configure workflow to fail if critical benchmarks (e.g., put/get operations) regress beyond threshold

Create Python/Java binding integration tests in CI pipeline

The repo has .github/actions/install-maven/action.yml and .github/actions/install-jdk8-on-macos/action.yml, indicating Java support, and the file structure suggests bindings exist. However, there's no dedicated workflow testing Python bindings or ensuring Java/Python APIs are validated against C++ changes. Language binding regressions can silently break downstream users.

• [ ] Create .github/workflows/bindings-ci.yml with separate jobs for Java and Python binding tests
• [ ] Reuse existing .github/actions/install-maven/action.yml and .github/actions/install-jdk8-on-macos/action.yml in Java binding tests
• [ ] Add Python binding tests using setup-python action with multiple Python versions (3.8, 3.9, 3.10, 3.11)
• [ ] Add matrix strategy to test on both Linux and macOS using pre-steps actions
• [ ] Include basic integration tests that exercise put/get/delete operations through language bindings to catch API breakage

• Add missing unit tests for edge cases in util/option_helper.cc—currently sparse coverage for enum-to-string conversions used by option serialization
• Implement missing Java bindings for CompactionFilterFactory in java/src/main/java/org/rocksdb/—several C++ callbacks exposed but Java wrappers incomplete
• Improve error messages in db/version_edit.cc to include file numbers in corruption reports—currently fails silently on malformed manifest files making debugging hard

RocksDB demonstrates generally good security practices as an established open-source database library. The main concerns are around third-party AI code review integrations without explicit data governance, potential credential handling in GitHub Actions scripts, and the absence of a formal security policy. No critical vulnerabilities were identified in the visible file structure. The codebase appears to follow standard open-source security practices with proper issue tracking and contribution guidelines. Recommendations focus on improving responsible disclosure mechanisms and securing CI/CD processes.

• Medium · AI Code Review Integration Without Security Governance — .github/workflows/claude-review.yml, .github/workflows/codex-review.yml, .github/workflows/ai-review-analysis.yml. The repository contains GitHub Actions workflows for AI-based code review (claude-review.yml, codex-review.yml, ai-review-analysis.yml) that automatically analyze and comment on pull requests. These workflows may expose sensitive code patterns, proprietary algorithms, or security-sensitive logic to third-party AI services without explicit data governance or code sanitization. Fix: Implement code filtering to exclude sensitive files from AI review, add explicit approval gates for sensitive PR analysis, document data retention policies with AI service providers, and ensure compliance with data privacy requirements.
• Medium · Potential Credential Exposure in GitHub Actions Scripts — .github/scripts/build-ai-review-comment.js, .github/scripts/post-pr-comment.js. The .github/scripts directory contains JavaScript files (build-ai-review-comment.js, post-pr-comment.js) that interact with GitHub APIs and potentially handle authentication tokens. If these scripts are not properly secured, they could expose GitHub tokens or other credentials through logging, error messages, or insecure storage. Fix: Review all scripts for proper secret handling, ensure tokens are never logged or exposed in error messages, use GitHub's built-in secret masking, implement proper token scope restrictions, and regularly rotate any exposed credentials.
• Low · Missing Security Policy Documentation — Repository root (missing SECURITY.md). While CONTRIBUTING.md and CODE_OF_CONDUCT.md are present, there is no visible SECURITY.md file for reporting security vulnerabilities responsibly. This could discourage responsible disclosure and lead to vulnerabilities being disclosed publicly. Fix: Create a SECURITY.md file following the standard format (https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) with clear instructions for reporting security issues privately and expected response timelines.
• Low · Watchman Configuration File Present — .watchmanconfig. The .watchmanconfig file is present but its content is not visible. Watchman is a file watching service that could potentially be misconfigured to expose sensitive paths or create race conditions in build processes. Fix: Review the watchman configuration to ensure it does not watch sensitive directories, does not expose internal build artifacts, and follows security best practices for file system monitoring.
• Low · Build Tool Scripts Require Security Audit — buckifier/buckify_rocksdb.py, buckifier/targets_builder.py, buckifier/util.py, buckifier/targets_cfg.py. The buckifier directory contains Python scripts (buckify_rocksdb.py, targets_builder.py, util.py) that automate build processes. These scripts could potentially execute arbitrary code or have injection vulnerabilities if they process untrusted input. Fix: Conduct a security audit of Python build scripts, validate all external inputs, avoid using eval() or exec(), use safe parsing methods (e.g., ast.literal_eval), and implement input sanitization for any dynamic code generation.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.