What is PugDB?

PugDB is the public name of F4KVS: a Rust-native LSM you can embed or self-host. Built so a real corpus — memoirs, RAG chunks — is still there after restart, not only faster on a chart.

Alpha embed (GO 2026-07-23): C/Go FFI + LSM for memoirs/RAG preprod. Pins v0.2.5 + v0.3.6. The server cluster remains lab — not a generic production GO. Core KV is well-tested; some distributed features will still change.

Core Definition

PugDB is a high-performance key-value storage system that provides:

  • Restart proof: 50× SIGKILL crash-loop with 0 loss; 1.66M soak cache ops with 10/10 anchors; 100k RAG chunks held after reopen
  • Low Latency: P50 latency 0.04–0.09ms, P99 latency 0.17–0.46ms
  • Stable Core (Beta): 5,597 automated tests, 1,627 QL tests, 67.6% QL line coverage (as of 2026-08-22)
  • Privacy-First Design: Built with encryption support, audit logging, and offline-first capabilities
  • Rust-Native: Leverages Rust's memory safety and modern async/await patterns

Key Characteristics

High Performance

The number we care about first is still there after restart. Product-shaped meso ingest holds 100,050 / 100,050 keys. Server YCSB (10k, partitioned) is 4.1× vs PostgreSQL and 2.63× vs ScyllaDB (2026-08-22) — published on /bench, not as a RocksDB pitch. P50 0.04–0.09ms, P99 0.17–0.46ms on that campaign.

Rust-Native Architecture

Built entirely in Rust, PugDB leverages:

  • Async/Await: Full Tokio integration for excellent concurrency
  • Memory Safety: Rust's compile-time guarantees eliminate entire classes of bugs
  • Modern Patterns: Clean, idiomatic Rust code that's maintainable and performant

Multi-Language Support via FFI

While PugDB is built in Rust, it can be used from any programming language through C-compatible FFI bindings:

  • C/C++: Direct C-compatible API for native integration
  • Python, Go, Node.js: Language bindings can be built on top of the C FFI
  • Zero Overhead: FFI bindings provide direct access to PugDB's core functionality
  • Cross-Platform: Works on all platforms where Rust compiles

The FFI crate (v0.2.5) is the production embed path — C ABI + Go wrappers over v0.3.6. Other languages can bind the same header.

Stable Core (Beta)

The foundation of PugDB is stable and well-tested:

  • Core key-value operations (get, put, delete, exists)
  • Memory storage engines (HashMap, BTreeMap) - Beta - Well Tested
  • Graceful shutdown and recovery
  • Memory leak detection
  • Monitoring hooks and metrics collection

Privacy-Focused Design

PugDB is built with privacy and data sovereignty in mind:

  • Encryption support for data at rest and in transit
  • Audit logging capabilities
  • Offline-first architecture
  • Local-first data storage patterns

Modular Architecture

PugDB follows a clean, layered architecture that separates concerns:

  • Foundation Layer: Core abstractions and memory storage
  • Extensions Layer: Advanced storage engines, query language, monitoring
  • Distributed Layer: Server, client, and clustering capabilities
  • Cloud Layer: S3-compatible storage and intelligent tiering
  • Application Layer: CLI tools and utilities

Main Features

Multiple Storage Engines

  • Memory Storage: HashMap and BTreeMap backends - Beta - Well Tested (813 tests, 80%+ coverage)
  • LSM-Tree Storage: Beta - Well Tested - 51 unit tests + integration tests, comprehensive crash recovery
  • Partitioned Storage: Beta - Well Tested - Extensive integration tests, 6+ test suites, stress-tested concurrency

Compression Support

Efficient data compression with multiple algorithms: LZ4, Zstd, Gzip, and Snappy.

Monitoring and Metrics

Built-in observability for production deployments: Prometheus metrics integration, health check endpoints, performance monitoring hooks, and resource usage tracking.

Query Language

Beta (Approaching Production) SQL support with 1,627+ tests and 67.6% line coverage: Window functions and JOINs GA; subqueries, optimization, and transactions in active hardening.

Performance Highlights

See /bench for product-shaped numbers. The small YCSB A/B/D 10k campaign (last updated: 2026-08-22):

  • Throughput: 4.1× vs PostgreSQL (3.7×–4.5×), 2.63× vs ScyllaDB (2×–3.8×)
  • Latency: P50 latency 0.04–0.09ms, P99 latency 0.17–0.46ms
  • Batch Operations: Optimized with connection reuse
  • Concurrency: Excellent scaling up to 32 threads
  • Memory Efficiency: Consistent performance with memory pools

*Benchmark Methodology: Results from single-threaded sequential YCSB workloads. Both PugDB and competitors tested identically. Real-world performance with concurrent workloads may differ.*

Quality Metrics

PugDB maintains high quality standards with comprehensive testing:

  • Test Coverage: 5,597 automated tests across server monorepo crates (commit bd52a3c)
  • Code Coverage: f4kvs-ql 67.6% line coverage (smoke tier) — as of 2026-08-22
  • Stable Components (Beta): Core (1227 tests), network (109), clustering (630)
  • Beta Components: Query language (1627 tests) and observability (87 tests)

Note: PugDB is the new name for F4KVS. All references to F4KVS in documentation and code will gradually transition to PugDB.

← Back to Docs Why PugDB? →