alh477/streamdb repository overview

⁠StreamDB (Official Docker Image)

StreamDB is a lightweight, thread-safe embedded key-value database implemented in C, specifically optimized for suffix-based searches using a reverse trie data structure.

This image provides a self-contained, Nix-determined environment for building and running StreamDB applications with zero external dependencies.

⁠Key Features

• Reverse Trie Architecture: lookup for keys ending with a specific suffix.
• Atomic Persistence: Uses a temp-file and rename strategy to ensure crash-safe writes.
• Thread-Safe: All operations are protected by a recursive mutex.
• Nix-Determined: Built with Nix for bit-for-bit reproducibility and a minimal security footprint.

⁠🛠 Usage

⁠1. Running the Test Suite

Verify the build integrity on your specific hardware (e.g., AMD Ryzen or Intel) by running the built-in test suite:

docker run --rm streamdb:2.0.0

⁠2. Using as a Development Environment

The image includes the libraries (/lib) and headers (/include) needed to link against StreamDB:

• Include path: /include/streamdb.h
• Library path: /lib/libstreamdb.so

⁠3. Persistent Storage

To use the auto-persistence feature, mount a local directory to the container's working directory (/tmp by default in this image):

docker run -it -v $(pwd)/data:/tmp streamdb:2.0.0

⁠📊 Performance Characteristics

StreamDB is optimized for specific workloads where traditional B-Trees or Hash Tables struggle:

⁠Image Structure

This image is built using pkgs.dockerTools.buildLayeredImage for optimal caching.

• Base: Minimal closure including glibc and libpthread.
• Binaries: test_streamdb.
• Utilities: busybox for basic shell access.

⁠📝 Configuration

The database can be initialized with a persistence file and an auto-flush interval:

// Example Initialization (C11)
StreamDB* db = streamdb_init("mydb.dat", 5000); // 5-second auto-flush

⁠License

This library is licensed under LGPL-2.1.