ShutterDB

Persistent binary caches for C++20.

Store previews, compiled shaders and build artifacts between runs. Cache manages a disk budget and evicts old entries; DB retains values until you delete them. Both store binary keys and values in a local file.

ShutterDB builds as a static library with no dependencies beyond the C++ standard library and OS APIs.

#include <shutter/cache.hpp>
#include <iostream>

int main() {
    shutter::Cache cache("assets.shdb", {.max_bytes = 256 * 1024 * 1024});
    cache.put("hello", "world");
    cache.sync();

    if (auto value = cache.get_string("hello")) {
        std::cout << *value << '\n';
    }
}

• LRU eviction and automatic compaction keep the main cache file within its budget.
• Batched writes share a sync(); individual writes can synchronize on each call.
• CRC32C checks validate headers, keys and values during reads and recovery.
• The shutter CLI inspects, verifies, compacts and repairs incomplete tails.

API	Retention	Default writes
Cache	Evicts entries to meet a disk budget	Buffered; call sync() at checkpoints
DB	Retains records until explicitly deleted	Synchronized on each write

Each file has one owning handle; calls on that handle are serialized. Compaction uses temporary space beyond the cache budget. See cache behavior and durability for the storage contract.

Install

Build from source with CMake 3.21+ and a C++20 compiler:

git clone https://github.com/ivanimmanuel-dev/ShutterDB.git
cd ShutterDB
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure

The CLI is build/shutter, or build/Release/shutter.exe with Visual Studio. The latest release includes a source archive and Linux/Windows packages with the CLI, library, headers and CMake configuration.

Use in your project

Install the library and headers:

cmake --install build --config Release --prefix /your/install/prefix

Link the exported target:

find_package(ShutterDB CONFIG REQUIRED)
target_link_libraries(myapp PRIVATE ShutterDB::ShutterDB)

Configure your project with -DCMAKE_PREFIX_PATH=/your/install/prefix. Vendoring and FetchContent are also supported.

Command line

With shutter on your PATH:

shutter init app.shdb
shutter set hello world --db app.shdb
shutter get hello --db app.shdb
shutter verify --db app.shdb
shutter compact --db app.shdb

Use --value-file to store a binary file and get --raw to read it back. The CLI reference covers commands, JSON output and exit codes.

Asset caches

Use content hashes as keys for previews, compiled shaders and build artifacts. The image example turns PNG/JPEG sources into cached PNG previews, preserves transparency and reuses identical content across filenames and restarts.

Opening validates the complete log and rebuilds its index. Keep a handle open for repeated access; compaction reclaims overwritten and deleted records. The performance results measure bounded-cache eviction and write pauses, and compare storage operations with SQLite and RocksDB.

Documentation

Guide	Contents
Getting started	Build, install, vendor and link
C++ API	Operations, options, ownership and limits
Cache API · Image example	Disk budgets, eviction and PNG/JPEG previews
CLI	Commands and examples
Durability	Synchronization, recovery and backups
Errors	Error codes and verification reports
Architecture · File format	Storage internals and format v1
Performance	Cache latency, storage comparison and measurements
Testing	Test suites, sanitizers, stress and fuzzing
Benchmarks	Build and run the benchmark tools

Contributing · Security · Changelog · MIT license