DecentDB logo

Language: Nim License: Apache-2.0 Tests: passing

 ___ _ ___ ___ 
 | \ ___ __ ___ _ _| |_| \| _ )
 | |) / -_) _/ -_) ' \ _| |) | _ \
 |___/\___\__\___|_||_\__|___/|___/
 

ACID first. Everything else... eventually.

DecentDB is a embedded relational database engine focused on durable writes, fast reads, and predictable correctness. It targets a single process with one writer and many concurrent readers under snapshot isolation. DecentDB provides a PostgreSQL-like SQL interface with ACID transactions, efficient B+Tree storage, and concurrent read access. It is not intended to be the best embedded database engine, but not terrible, a decent better than some engine.

• 🔒 ACID Transactions - Write-ahead logging with crash-safe recovery
• 🌳 B+Tree Storage - Efficient tables and secondary indexes with page caching
• 🐘 PostgreSQL-like SQL - Familiar DDL/DML syntax with JOINs, CTEs, Window Functions, and Rich Types (UUID, DECIMAL)
• 👥 Concurrent Reads - Snapshot isolation allows multiple readers with one writer
• 🔎 Trigram Index - Fast text search for LIKE '%pattern%' queries
• 🧪 Comprehensive Testing - Unit tests, property tests, crash injection, and differential testing
• 🔄 Foreign Key Constraints - Automatic indexing and referential integrity enforcement
• 📊 Rich Query Support - Aggregates, UPSERT, Set Operations, and Scalar Functions
• ⚡ Triggers - AFTER and INSTEAD OF triggers for complex logic
• 📦 Single File Database - Portable database stored in a single file
• 🌐 Cross-Platform - Runs on Linux, macOS, and Windows
• 🚀 Bulk Load Operations - Optimized high-performance data loading
• 🛠️ Rich CLI Tool - Unified command-line interface for all database operations
• 📁 Import/Export Tools - CSV and JSON data import/export capabilities
• 🧩 Parameterized Queries - Safe parameter binding to prevent SQL injection
• 🧾 Transaction Support - BEGIN, COMMIT, ROLLBACK for atomic operations

MehSQL - Native cross platform DecentDB SQL Query tool.

Decent performance...

How this chart is produced

• The chart is generated from benchmark runs using nimble bench_embedded_chart.
• Values are normalized vs SQLite (baseline = 1.0).
• For "lower is better" metrics (latency, DB size), the score is inverted so higher bars mean better.
• Full methodology and raw results live in benchmarks/embedded_compare/.

Supported engines

• DecentDB (native API)
• SQLite (via C API)
• DuckDB (via C API) - when library is available

Regenerate

# Run full benchmark pipeline (all engines, aggregate, chart)
nimble bench_embedded_pipeline
# Or run individual steps:
nimble bench_embedded_sample # Run all engines
nimble bench_embedded_aggregate # Aggregate results
nimble bench_embedded_chart # Generate chart
# Run specific engines only:
./build/run_benchmarks /tmp/bench_out --engines=decentdb,sqlite
./build/run_benchmarks /tmp/bench_out --engines=all

• Nim (includes nim + nimble)
• Python 3
• libpg_query (C library + headers)

nimble build

# Create and query a database
decentdb exec --db ./my.ddb --sql "CREATE TABLE users (id INT PRIMARY KEY, name TEXT, email TEXT)"
decentdb exec --db ./my.ddb --sql "INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')"
decentdb exec --db ./my.ddb --sql "SELECT * FROM users"

decentdb repl --db ./my.ddb

# Create tables with constraints
decentdb exec --db ./my.ddb --sql "CREATE TABLE orders (
 id INT PRIMARY KEY,
 user_id INT REFERENCES users(id),
 amount FLOAT64,
 created_at INT
)"
# Insert data
decentdb exec --db ./my.ddb --sql "INSERT INTO orders VALUES (1, 1, 99.99, 1704067200)"
# Query with JOINs
decentdb exec --db ./my.ddb --sql "SELECT u.name, SUM(o.amount) 
 FROM users u 
 JOIN orders o ON u.id = o.user_id 
 GROUP BY u.name"
# Text search with trigram index
decentdb exec --db ./my.ddb --sql "CREATE INDEX idx_users_name ON users USING trigram(name)"
decentdb exec --db ./my.ddb --sql "SELECT * FROM users WHERE name LIKE '%ali%'"

# Import CSV data
decentdb import --table users --input data.csv --db ./my.ddb
# Export to JSON
decentdb export --table users --output users.json --db ./my.ddb --format=json
# Bulk load large datasets
decentdb bulk-load --table users --input large_dataset.csv --db ./my.ddb

There are several tools for DecentDB that provide importing/converting from other databases, read more here

# Force WAL checkpoint
decentdb checkpoint --db ./my.ddb
# View database statistics
decentdb stats --db ./my.ddb
# Rebuild an index
decentdb rebuild-index --index users_name_idx --db ./my.ddb

DecentDB provides a unified CLI tool. See decentdb --help for all commands.

Common commands:

• exec - Execute SQL statements
• repl - Interactive SQL shell
• import / export - Data transfer
• bulk-load - High-performance data loading
• checkpoint - WAL maintenance
• list-tables / describe - Schema introspection

• User Guide - SQL reference, tutorials, and examples
• Nim API - Embedded API documentation
• Architecture - Design and implementation details
• Contributing - Development guidelines

DecentDB is organized into focused modules:

• VFS - OS I/O abstraction with fault injection support
• Pager - Fixed-size pages, LRU cache, and freelist management
• WAL - Append-only log, crash recovery, and checkpointing
• B+Tree - Table storage and secondary indexes
• Record - Typed value encoding with overflow pages
• Catalog - Schema metadata management
• SQL/Planner/Exec - Query parsing, planning, and execution
• Search - Trigram inverted index for text search

# Run tests
nimble test
# Run benchmarks
nimble bench
# Lint code
nimble lint

DecentDB can generate a unit test coverage report using gcov.

# Generate coverage (requires gcov)
bash scripts/coverage_nim.sh
# Alternative: run coverage in smaller batches
bash scripts/coverage_batch.sh

Outputs:

• build/coverage/summary.txt (human-readable summary)
• build/coverage/summary.json (machine-readable summary)
• build/coverage/gcov/ (raw per-test .gcov files)

See Contributing Guide for development workflow and guidelines.

Apache-2.0. See LICENSE.