AGENTS.md

This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository.

While working on Apache Kvrocks, please remember:

  • Always use English in code and comments.
  • Only add meaningful comments when the code's behavior is difficult to understand.
  • Add or update tests to cover externally observable behavior and regressions when you change or add functionality.
  • Always run the formatter before submitting changes.
  • For non-trivial behavior, storage format, replication, or cluster changes, first look for an existing issue, discussion, or mailing list context before implementing.

Build and Development Commands

Building

# Configure with Ninja when you want faster incremental builds.
# The default generator is Makefiles unless --ninja is specified.
./x.py build --ninja

# Build kvrocks and utilities
./x.py build                    # Build to ./build directory
./x.py build -j N               # Build with N parallel jobs
./x.py build --unittest         # Build with unit tests
./x.py build -DENABLE_OPENSSL=ON  # Build with TLS support
./x.py build --ninja            # Use Ninja build system
./x.py build --skip-build       # Only run CMake configure
./x.py build -DCMAKE_BUILD_TYPE=Debug  # Debug build

# Run a local server
./build/kvrocks -c kvrocks.conf

# Fetch dependencies
./x.py fetch-deps               # Fetch dependency archives

If the build directory was configured with Ninja, prefer incremental rebuilds like cd build && ninja -j16 kvrocks instead of re-running CMake.

Testing

# Build and run C++ unit tests
./x.py build --unittest
./x.py test cpp

# Run Go integration tests
./x.py test go

# Re-run a specific Go test name.
# x.py test go currently forwards extra flags to "go test" but still runs "./...".
./x.py test go build -run TestKMetadata

Lint

You must run the formatter and linters before submitting code changes. This ensures code quality and consistency across the project. It requires installing clang-format, clang-tidy, and golangci-lint locally. Please refer to the CONTRIBUTING.md for setup instructions.

# Format code (must pass before submitting)
./x.py format

# Check code format (fails if not formatted)
./x.py check format

# Run clang-tidy
./x.py check tidy

# Run golangci-lint for Go tests
./x.py check golangci-lint

Architecture Overview

Apache Kvrocks is a distributed key-value NoSQL database compatible with the Redis protocol, using RocksDB as its storage engine.

Core Structure

  • src/server/: Main server orchestration, connection handling, and worker threads. The Server class manages the event loop, worker threads, and coordinates all components.
  • src/storage/: RocksDB integration layer. Key classes:
    • Storage: Manages RocksDB instance, column families, and write batches
    • Context: Passes snapshot and batch between APIs for transactional consistency
  • src/commands/: Redis protocol command implementations. Each command type has a corresponding Commander subclass.
  • src/types/: Redis data structure implementations (String, Hash, List, Set, ZSet, Stream, etc.)
  • src/cluster/: Cluster management, slot migration, and replication.
  • src/search/: Full-text search and vector search (HNSW) implementation.
  • src/config/: Server configuration parsing and management.
  • src/cli/: Command-line interface utilities.
  • src/common/: Shared utilities and helper functions.
  • src/stats/: Statistics and metrics collection.

Key Patterns

  • Column Families: 8 column families are used - PrimarySubkey, Metadata, SecondarySubkey, PubSub, Propagate, Stream, Search, Index.
  • Command Registration: Commands are registered via the REDIS_REGISTER_COMMANDS macro with flags like kCmdWrite, kCmdReadOnly, kCmdBlocking, etc.
  • Write Batch with Index: Used for transactional mode to group writes before commit.
  • Worker Thread Model: Libevent-based async I/O with dedicated worker threads.
  • Namespace Isolation: Token-based multi-tenancy using the __namespace column family.

Data Encoding

  • METADATA_ENCODING_VERSION=1 (default): Encodes 64-bit size and expire time in milliseconds.
  • METADATA_ENCODING_VERSION=0: Legacy encoding.

Refer to https://kvrocks.apache.org/community/data-structure-on-rocksdb for more details.

Coding Style and Naming Conventions

  • C++ formatting follows .clang-format (Google-based, 2-space indent, 120-column limit, sorted includes).
  • Use .cc/.h file extensions with snake_case filenames.
  • Types use PascalCase; match existing patterns in nearby code.
  • Use existing utilities and helper functions when possible; avoid reinventing the wheel.
  • Go code should stay gofmt-clean and comply with tests/gocase/.golangci.yml.

Testing Guidelines

You could provide Go tests for integration-level verification of command behaviors and C++ unit tests for internal logic. Focus on testing new features or bug fixes, and avoid adding tests that don't verify meaningful behavior changes.

  • Go Integration Tests (tests/gocase/): Use *_test.go files, organized by feature (unit/, integration/, tls/).
  • C++ Unit Tests (tests/cppunit/): Use *_test.cc files with GoogleTest framework.
  • Add or update tests alongside behavior changes.
  • Prefer focused unit tests; add integration coverage when commands or replication/storage behaviors change.
  • Use ./x.py test ... entry points for consistent setup.

Commit Message Format

Use conventional commits with a scope indicating the affected component:

feat(rdb): add DUMP support for SortedInt type
fix(replication): prevent WAL exhaustion from slow consumers
fix(string): add empty string value check for INCR to match Redis behavior
perf(hash): use MultiGet to reduce RocksDB calls in HMSET
chore(deps): Bump rocksdb to v10.10.1
chore(ci): bump crate-ci/typos action to v1.43.1
chore(tests): replace to slices.Reverse() in go test

Common scopes: server, storage, commands, cluster, search, types, replication, rdb, stream, hash, string, list, set, zset, deps, ci, tests, conf.

Common Tasks

Adding a New Command

  1. Create or update the command handler in src/commands/.
  2. Implement the Commander subclass with Parse() and Execute() methods.
  3. Register the command using REDIS_REGISTER_COMMANDS macro with appropriate flags.
  4. Add the underlying data operation in src/types/ if needed.
  5. Add C++ unit tests in tests/cppunit/.
  6. Add Go integration tests in tests/gocase/.

Adding a New Data Type

  1. Implement the type in src/types/ following existing patterns.
  2. Define the metadata encoding in src/storage/.
  3. Add command handlers in src/commands/.
  4. Register commands with the REDIS_REGISTER_COMMANDS macro.
  5. Add tests for both the type operations and command handlers.

Debugging

  1. Check server logs (configurable log level in kvrocks config).
  2. Use the DEBUG command for runtime inspection.
  3. Use sanitizers via build flags for memory and thread issues.
  4. Refer to tests/lsan-suppressions and tests/tsan-suppressions for known suppression rules.

Important Notes

  • Kvrocks aims for Redis protocol compatibility; always verify behavior against Redis when implementing or fixing commands.
  • All changes must pass ./x.py check format, and you should run ./x.py check tidy, ./x.py check golangci-lint, and the relevant tests when the touched code requires them.
  • Don't change public command behavior unless requested.
  • RocksDB is the core storage dependency; be cautious with storage-layer changes.
  • Adding a new column family breaks forward compatibility; avoid this if possible and prefer using existing column families.
  • Prefer focused patches over broad refactors when contributing.
  • Some website or documentation tasks may belong in the separate website repository rather than this repository.
  • If AI assistance is used, keep the generated changes reviewable and be able to explain and defend the final patch.

Security

Security model: SECURITY.md → THREAT_MODEL.md

Agents that scan this repository should consult SECURITY.md and the linked THREAT_MODEL.md for the project's threat model — in-scope / out-of-scope declarations, the security properties claimed and disclaimed (namespace isolation, admin/namespace token separation, the Lua sandbox), the adversary model, and known non-findings — before reporting issues.