DecentDB¶

Durable embedded SQL for local-first applications.

DecentDB is a Rust-native embedded relational database engine focused on durable ACID writes, fast reads, predictable correctness, and application integration. It is built around a single-process concurrency model with one writer and many concurrent readers under snapshot isolation.

DecentDB is not trying to be "SQLite with more features." Its strongest lane is embedded SQL for modern applications that need local durability, rich relational queries, syncable offline data, and language bindings that feel native.

What Stands Out¶

Core Features¶

• ACID transactions with WAL durability and crash recovery.
• One writer, many readers for predictable embedded concurrency.
• B+Tree tables and secondary indexes with page caching.
• Foreign keys with referential integrity and supported actions such as CASCADE, SET NULL, and RESTRICT.
• Generated columns in STORED and VIRTUAL modes.
• Temporary tables and views scoped to the current session.
• JSON support including scalar functions and table-valued functions such as json_each and json_tree.
• SQL compatibility helpers including safe SQLite-style PRAGMAs, sqlite_schema, minimal information_schema, generate_series, main./temp. qualifiers, and query-time BINARY, NOCASE, and RTRIM collations.
• Local data security with TDE, durable row policies, projection masks, audit context functions, and queryable security audit events.
• Sandboxed Lua extensions with manifest validation, package hashing, Ed25519 signature checks, explicit install/enable/trust lifecycle, scalar functions, table-valued functions, aggregates, query-time collations, Rust APIs, CLI commands, C ABI JSON bridges, and sys.* inspection views.
• Triggers for application-side logic, including supported AFTER and INSTEAD OF trigger paths.
• Bulk-load, CSV, and JSON import/export workflows.
• Queryable operational metrics through stable sys.* inspection views for WAL, write queue, storage, reactive subscription, and sync status snapshots.
• Production sync relay and changeset APIs with checkpointed changeset export/apply/inspect/invert, HTTP/WebSocket shape delivery, durable client acknowledgements, and relay diagnostics.
• Reactive subscriptions and change streams with table, primary-key range, query, and change-stream watches for committed in-process invalidation.
• Branch, diff, restore, and time-travel workflows with named snapshots, branch-local writes, primary-key row diffs, guarded restore, and constrained merge.
• Built-in HTTP API and Web Console through decentdb serve for local inspection, schema browsing, SQL/EXPLAIN execution, CSV export, and scripting.
• Browser WASM/OPFS binding through @decentdb/web, with a Dedicated Worker runtime, OPFS-backed persistence, binary result transport, checkpoint, import/export, and persistence helpers.
• In-memory databases using :memory: plus save-as support for snapshots.
• Cross-platform release builds for Linux x86_64/arm64, macOS, and Windows.

Quick Start¶

Install the CLI from the latest release:

1. Download the archive for your platform from GitHub Releases.
2. Extract the archive.
3. Put decentdb or decentdb.exe on your PATH.

Release archives are published for Linux x86_64/arm64, macOS, and Windows. Verify the CLI is available:

decentdb --help

If you are developing DecentDB itself, you can also install the CLI from a local checkout:

cargo install --path crates/decentdb-cli

Create a database, insert a row, and query it:

decentdb exec --db ./app.ddb --sql "CREATE TABLE users (id INT PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)"
decentdb exec --db ./app.ddb --sql "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com') RETURNING id"
decentdb exec --db ./app.ddb --sql "SELECT * FROM users"

Open an interactive SQL shell:

decentdb repl --db ./app.ddb

Enable local-first sync on a database:

decentdb sync init --db ./app.ddb --replica-id node-a
decentdb sync status --db ./app.ddb --format table
decentdb sync pending --db ./app.ddb --since 0 --limit 10 --format table

Where To Start¶

• New users: Installation and Quick Start
• SQL users: SQL Reference, SQL Feature Matrix, and Data Types
• Local-first applications: Local-first sync
• Security-sensitive apps: Local Data Security
• Browser applications: WASM / Browser
• Flutter mobile applications: Dart/Flutter
• Extensibility: Lua Extensions
• Operational workflows: Doctor, Performance Tuning, and Benchmarks
• Comparing engines: Comparison Overview, DecentDB vs SQLite, and DecentDB vs DuckDB
• Language integrations: C/C++ ABI, .NET, Go, Python, Node.js, Dart/Flutter, JDBC, and WASM / Browser
• CLI users: Interactive SQL Shell, Built-In Web Console, and CLI Reference

Built-In Web Console At A Glance¶

decentdb serve --db ./app.ddb starts a local HTTP API and lightweight browser console at http://localhost:7373. It is designed for quick inspection, simple ad hoc SQL, schema browsing, and scripting support without installing a full IDE.

• embedded HTML, CSS, and vanilla JavaScript served from the CLI binary
• no CDN, external fonts, telemetry, frontend build pipeline, or internet dependency
• transparent ephemeral auth for default localhost sessions
• read-only mode for safe inspection
• table detail, schema, query, explain, CSV export, and local query history

Start with the Built-In Web Console guide.

Browser WASM At A Glance¶

@decentdb/web loads the Rust engine compiled to WASM inside a Dedicated Worker and stores database bytes in OPFS through synchronous access handles. The main-thread API stays async while the engine preserves the same one-writer, WAL-first design.

• OPFS-backed browser persistence
• async TypeScript API for open, exec, query, prepare, checkpoint, import/export, and persistence requests
• binary worker result transport with JSON retained for compatibility/debugging
• automated Chromium OPFS smoke and scheduled transport benchmark coverage

Start with the WASM / Browser guide.

Local-First Sync At A Glance¶

DecentDB sync is built into the engine and exposed through CLI commands, SQL inspection surfaces, HTTP/WebSocket relay routes, and native/web APIs. The current sync surface includes:

• durable row-level change capture in a sidecar sync journal
• public checkpoint changeset create, inspect, apply, and invert APIs
• production relay routes for shape snapshots, incremental changes, durable acknowledgements, diagnostics, and WebSocket subscriptions
• replica IDs, peer catalogs, and peer-to-scope bindings
• manual JSON batch export/import
• localhost/dev HTTP sync run and sync serve workflows
• scoped replication with validated row filters
• conflict recording, inspection, resolution, reopen, and policy commands
• canonical sys.* operational inspection views with sys_sync_* compatibility names
• retention reports, safe prune dry-runs, peer lag, and sync doctor guidance

Start with the sync overview or jump directly to the sync quickstart.

Language Bindings¶

All bindings sit above the native C ABI. The Rust engine remains the authoritative implementation.

Current Constraints¶

• DecentDB is an embedded, single-process database engine.
• The concurrency model is one writer with many concurrent readers.
• The built-in HTTP surfaces are local-first. decentdb serve can bind to a non-localhost host only with explicit bearer-token configuration, but it is still a lightweight inspection/API server rather than a hardened public database service.
• Browser v1 support is worker-owned OPFS storage. It does not provide cross-tab writes, service worker ownership, or cross-worker WAL coordination.
• DecentDB exposes a sandboxed Lua extension model. It does not support arbitrary native extension loading, SQLite-style .load, direct database handles inside extension code, or Lua execution in browser/WASM artifacts.
• Some roadmap items, including vector search and full-text ranking, are planned work rather than shipped features.

Releases And Packages¶

GitHub Releases publish native archives for Linux x86_64/arm64, macOS, and Windows. Release bundles include the CLI and native C API library. JDBC and DBeaver assets are published alongside the native bundles.

.NET packages include DecentDB.AdoNet, DecentDB.MicroOrm, DecentDB.EntityFrameworkCore, DecentDB.EntityFrameworkCore.Design, and DecentDB.EntityFrameworkCore.NodaTime.

See Release process and GitHub Releases.

Project Links¶

• GitHub repository
• Issue tracker
• License