A pure Go implementation of RocksDB with bit-compatible on-disk formats.

---

Overview

RockyardKV is a pure Go implementation of RocksDB. It reads and writes RocksDB databases without CGo or C++ dependencies.

The project targets bit-compatible file formats with RocksDB. Files created by RockyardKV can be read by C++ RocksDB, and vice versa.

Built with a lot of respect for RocksDB - the foundational storage engine that inspired this work. No affiliation or endorsement implied.

Note

Project status: Core storage operations work with verified format compatibility. Durability semantics are under active verification. Refer to docs/status/ for compatibility details and known limitations.

Features

• Storage: LSM-tree with leveled, universal, and FIFO compaction; column families; snapshots; Bloom filters; Snappy, LZ4, Zstd, and Zlib compression
• Write path: Merge operators, range deletions, SST ingestion, write stall control
• Transactions: Optimistic and pessimistic modes with deadlock detection
• Operations: Backup engine, checkpoints, compaction filters, TTL, rate limiting
• Deployment: Read-only mode, secondary instances, Direct I/O

Installation

go get github.com/aalhour/rockyardkv

Requires Go 1.25 or later.

Quick start

Open a database and perform basic operations:

package main

import (
    "log"

    "github.com/aalhour/rockyardkv"
)

func main() {
    opts := rockyardkv.DefaultOptions()
    opts.CreateIfMissing = true

    database, err := rockyardkv.Open("/tmp/mydb", opts)
    if err != nil {
        log.Fatal(err)
    }
    defer database.Close()

    // Write a key-value pair
    err = database.Put(rockyardkv.DefaultWriteOptions(), []byte("key"), []byte("value"))
    if err != nil {
        log.Fatal(err)
    }

    // Read the value back
    value, err := database.Get(rockyardkv.DefaultReadOptions(), []byte("key"))
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("value: %s", value)
}

Documentation

Refer to the docs directory for detailed guides:

• Status - Compatibility, limitations, and verification
• Configuration - All options, compression, checksums, and C++ compatibility
• Integration guide - Add RockyardKV to your application
• Examples - Working code examples for common use cases
• Architecture - Internal design and package structure
• Migration guide - Migrate from C++ RocksDB or CGo wrappers
• Performance tuning - Optimize for your workload
• Testing - Run and extend the test suite

Command-line tools

The cmd/ directory contains utilities for database inspection and testing. Refer to cmd/README.md for details.

Compatibility

RockyardKV targets RocksDB v10.7.5 (commit 812b12b). Run make test-e2e-golden to verify format compatibility using C++ oracle tools.

Refer to docs/status for the compatibility matrix and verification details.

Benchmarks

Refer to docs/benchmarks.md for performance measurements.

Contributing

Refer to CONTRIBUTING.md for development setup and guidelines.

License

Apache 2.0. Refer to LICENSE for the full text.