KvSQL.com

KvSQL Launches With an Embedded Engine and a Database Server on One Set of Records

Thu, 22 Oct 2026 00:00:00 +0000

KvSQL 0.1.0 is out. It’s a key-value store and an SQL database that keep one copy of the data between them. Read a row by its key and it comes straight from the storage tree, with nothing parsed or planned. Ask SQL about the same rows and it reads the same bytes. One transaction covers both, and an index stays right whichever way a row was written.

The release has two products. KvSQL Engine is a Rust library you put in your own program: one file on disk, no server, and no dependencies beyond the Rust standard library. KvSQL DB is built on it: kvsqld serves a database file over HTTP with JSON, and kvsql is a shell that talks to the server or opens a file directly.

Why Key Lookups and SQL Belong on the Same Records

Thu, 22 Oct 2026 00:00:00 +0000

Think of a cloakroom. At one window you hand over a ticket and get your coat back. Nobody searches, nobody asks what colour it was. At another window you can ask the attendant for every blue coat left after nine o’clock, and somebody has to go through the racks to answer. Both are useful. A database that only has the first window is a key-value store. One that only has the second is an SQL database.

How KvSQL Was Tested With Power Cuts, Killed Processes and 30000 Statements Checked Against SQLite

Thu, 22 Oct 2026 00:00:00 +0000

A database makes one promise above the rest. When it says a commit is done, the data is there, even if the power goes a moment later. And if the power goes during a commit, the file holds the whole transaction or none of it, never part. Most of KvSQL’s tests are aimed at that promise, from several sides.

All the figures below come from one recorded run of the project’s test script, scripts/record-results.sh, on a Linux container with two virtual CPUs, on October 22, 2026. The full output is in the repository under test/results/latest. CI runs the same script on Linux and macOS on every change.

Case Study: A Checkout That Is Never Half Done, Tested With 1200 Power Cuts

Thu, 22 Oct 2026 00:00:00 +0000

A checkout touches several things that must change together. The cart goes away, an order appears with its lines, and the stock goes down. If the power fails halfway, the worst outcomes are an order with the stock never taken, or a paid order with the cart still sitting there. With a key-value store for carts and an SQL database for orders, those are two systems and two commits, and somebody has to write the cleanup for the gap between them.

Case Study: An Edge Gateway Collecting Sensor Readings Over HTTP With kvsqld

Thu, 22 Oct 2026 00:00:00 +0000

An edge gateway sits between a set of devices and the rest of the world. Sensors post readings to it, a dashboard on the same network shows the latest value per device, and someone asks about history: averages, peaks, the hour a fridge ran warm. The gateway is often a small box with no room for a database team, so it should be one program and one file.

This case study runs that set-up with kvsqld. Twenty simulated devices post readings over HTTP on their own connections, while a dashboard reads the latest value by key and asks SQL for history. It’s part of case_studies.rs in the repository. The figures are from its recorded run of October 22, 2026, on a real file on a Linux container with two virtual CPUs. The output is in case-studies.md.

Case Study: Sessions and Reporting in One Store Instead of Two

Thu, 22 Oct 2026 00:00:00 +0000

A web application checks its session table on every request. A token comes in, and the app needs the user behind it, fast. Once in a while somebody wants a different view of the same data: how many sessions are live per country, or every session of one user, revoked at once when a password changes. Teams often split this in two, with sessions in Redis for speed and a copy in SQL for the reports and the bulk revokes.

KvSQL Against SQLite on the Same Machine: Key Reads, SQL Reads and Synced Commits

Thu, 22 Oct 2026 00:00:00 +0000

KvSQL’s claim is a fast path by key that skips the SQL machinery, on the same records SQL reads. A claim like that needs a measurement, and the obvious yardstick is SQLite. It’s the most used embedded database there is, and it’s very good. So the project’s test script runs a benchmark against SQLite every time it records results, and saves it next to the test output.

The figures here are from the recorded run of October 22, 2026, on a Linux container with two virtual CPUs. The full table, with every condition, is bench.md in the repository. A container like this is noisy: between runs on the same day, single figures moved by 20 to 30 percent. Treat the gaps below as rough sizes.

Use Example: A Cache With Expiry Using Key Reads and an SQL Sweep

Thu, 22 Oct 2026 00:00:00 +0000

A response cache has two jobs that pull in different directions. On a hit, it has to find one entry by its key as fast as possible. Now and then it has to throw away everything that has expired, which is a question over all the entries. In KvSQL both jobs run on one table.

db.execute("CREATE TABLE cache (key TEXT PRIMARY KEY, body BLOB, expires INTEGER NOT NULL);
            CREATE INDEX cache_expires ON cache(expires)", &[])?;

Store a response with put_row, which replaces an older entry under the same key:

Use Example: Settings Read by Key and Audited With SQL

Thu, 22 Oct 2026 00:00:00 +0000

Feature flags and settings are read all the time and listed rarely. The code asks “is the new checkout on?” on every request. Once in a while a person asks “what are all the search settings right now?” A plain keyspace in KvSQL answers both, with no schema at all.

Write settings as keys and values:

let mut tx = db.begin_write()?;
tx.put("settings", b"checkout.new_flow", b"on")?;
tx.put("settings", b"search.fuzzy", b"off")?;
tx.put("settings", b"search.limit", b"50")?;
tx.put("settings", b"upload.max_mb", b"20")?;
tx.commit()?;

Read one by key, straight from storage:

Use Example: Working With a Database File in the kvsql Shell

Thu, 22 Oct 2026 00:00:00 +0000

Sometimes you just want to look inside a database. Maybe a test left a file behind, or you’re checking what a service wrote, or you want to try a query before putting it in code. The kvsql shell opens a file directly, with no server running, and takes SQL and key-value commands side by side.

kvsql --file jobs.kvsql

Here is a short session, as the project’s use example program ran it through the shell’s own command code, one command at a time the way -c takes them. The output is exactly what came back:

Why the Project Is Called KvSQL

Thu, 22 Oct 2026 00:00:00 +0000

The name is the design, spelled out. KV for key-value, SQL for SQL, written together because in this database they aren’t two systems glued side by side. They’re two ways into one store.

The lower-case v is on purpose. Kv reads as one small syllable in front of the three letters everybody knows, and it keeps the name from turning into a row of capitals. Say it “K-V-S-Q-L”, or “kv sequel” if you prefer; both are fine.

About

Mon, 01 Jan 0001 00:00:00 +0000

KvSQL is a hybrid of key-value and SQL in Rust. It comes as two products built on one set of records. KvSQL Engine is a library you embed in your program: one file on disk, no server. KvSQL DB is a database server, kvsqld, and a shell, kvsql, built on the same engine.

Why It Exists

Many programs need two things from their data. They need fast lookups by key, thousands of times a second, and they need real questions answered: totals, filters, joins. The usual answer is two stores, a key-value store such as RocksDB or Redis for the lookups and SQLite for the questions. The data then lives twice. Code has to keep the two copies in step, and a change can’t be atomic across both.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Developers weighing KvSQL for an application, a service or an edge gateway, with questions the reference doesn’t answer.
Anyone who found a bug. A short program or a list of kvsql commands that shows it is the best report. The issue tracker on GitHub works too.
Teams with a workload worth testing, such as a key-value store and SQLite running side by side today.

Write to info@kvsql.com.

Download KvSQL

Mon, 01 Jan 0001 00:00:00 +0000

Each archive holds the two KvSQL DB programs, kvsqld (the server) and kvsql (the shell), with the license files and the README. The links always point to the latest release.

System	Download
Linux, x86-64	kvsql-linux-x86_64.tar.gz
Linux, ARM64	kvsql-linux-arm64.tar.gz
macOS, Apple silicon	kvsql-macos-arm64.tar.gz
macOS, Intel	kvsql-macos-x86_64.tar.gz
Windows, x86-64	kvsql-windows-x86_64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Each of these builds ran the engine’s test suite and a smoke test on its own platform before the release went out: a file opened with the shell, then the server started, written to with curl and read back through the shell.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

There are two ways in. Embed KvSQL Engine in a Rust program, or run the KvSQL DB server and use it from any language over HTTP.

The Engine in a Rust Program

Add the engine as a Git dependency. It has no dependencies of its own.

[dependencies]
kvsql-engine = { git = "https://github.com/softdevstudio/kvsql", tag = "v0.1.0" }

Open a file, write some keys and read them back:

use kvsql_engine::Db;

fn main() -> kvsql_engine::Result<()> {
    let db = Db::open("app.kvsql")?;

    // Several changes, committed together.
    let mut tx = db.begin_write()?;
    tx.put("users", b"42", b"Ada")?;
    tx.put("users", b"43", b"Grace")?;
    tx.commit()?;

    let name = db.get("users", b"42")?;                     // Some(b"Ada")
    let some = db.scan("users", b"40", Some(b"50"), 100)?;  // keys 40 up to 50
    println!("{:?} {}", name, some.len());
    Ok(())
}

Now SQL on the same records. A table is a keyspace with a schema, and each row sits under its primary key:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

This page is the short version. The full reference lives with the code: SQL, server and shell and file format, plus the README, which is the manual.

Engine API

Call	What it does
`Db::open(path)`	Open or create a database file. A second process gets `Error::Locked`
`db.get(ks, key)`, `db.scan(ks, from, to, limit)`	Read by key, or a key range in order, on a snapshot
`db.put(ks, key, value)`, `db.delete(ks, key)`	One change, committed on its own
`db.begin_write()`	A write transaction: `get`, `scan`, `put`, `delete`, `drop_keyspace`, `execute`, `put_row`, `delete_row`, then `commit`
`db.begin_read()`	A snapshot that sees nothing committed after it began: `get`, `scan`, `query`, `get_row`
`db.execute(sql, params)`	SQL in its own transaction. Reads run on a snapshot; writes commit only if every statement succeeds
`db.get_row(table, pk)`	A table row by primary key, straight from storage, no SQL
`db.verify()`	Check every page, every row against its table and every index entry

When commit returns, the transaction is on disk. A crash or power cut during a commit leaves the whole commit or none of it. If a commit fails part way, the handle refuses further use; reopen the file to continue from the last good commit.