Pages on KvSQL.com

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.