kinedb

kinedb is a database engine. The same engine runs as one server, as a cluster of servers, or inside your application. In all three cases, your application sends SQL.

kinedb stores tables, document collections (JSON documents with an _id) and key-value collections. Every commit makes a new version of the data, and the old versions stay readable. So a branch of a whole database costs one pointer, not a copy.

The three ways it runs

One server

The kinedb binary starts a server on port 4820. Clients connect over HTTP (POST /sql, JSON) or over a WebSocket (/ws, a binary protocol). The same port serves a web console at /ui/ and these docs at /ui/docs/.

Status: works today. See Run kinedb.

A cluster of servers

A cluster is any number of kinedb servers that act as one database. You start every node with --calvin, and every node after the first with --join <address> of a running node. The nodes find each other with a gossip protocol.

The cluster splits each table into shards by key range, and it splits a shard again when the shard grows. Each shard has replicas on several nodes. The replicas agree on one order of the writes with Raft, and every replica applies the writes in that order. A write is durable when the cluster acknowledges it: each replica writes the entry to disk before it counts toward the quorum.

Status: works today. See Architecture.

Embedded in your application

The engine is also a library. In Rust, the kinedb crate opens a database with Db::open(path) or Db::open_in_memory(), and runs SQL with db.execute(sql). No server runs. Db::open_with_memory(path, bytes) and Db::open_in_memory_with_memory(bytes) set a memory budget. Db::open_with_options(path, options) sets how much commit history the database keeps (History retention). The kinedb binary gives you the same engine from a shell:

kinedb --data-dir ./data -e "SHOW TABLES"

In JavaScript, the npm package @kinedb/embedded is the same engine as WebAssembly. It runs in a browser tab, in bun and in Node, and it can sync a table from a server and keep serving reads when the server is gone. See the embedded database.

Status: the library works on disk and in memory, and it compiles to WebAssembly. Every node serves five browser demonstrations of it at /ui/demos/.

For AI agents

These docs are written for coding agents first. Every page is also plain Markdown:

• The index of all pages: https://docs.kinedb.com/llms.txt
• All pages in one file: https://docs.kinedb.com/llms-full.txt
• One page: add .md to its URL, for example https://docs.kinedb.com/sql.md for https://docs.kinedb.com/sql.

Every kinedb node also serves the docs of its own build. Use these when you work against a specific server, because they match that server exactly: http://<host>:4820/ui/docs/llms-full.txt.

To give an agent the docs, put this in the CLAUDE.md (or AGENTS.md) of your project:

## KineDB

This project uses KineDB. Before you write KineDB SQL or client code, read
https://docs.kinedb.com/llms-full.txt. The server of this project also serves the docs
of its own version at http://<host>:4820/ui/docs/llms-full.txt; when the two differ,
the server's copy is correct.

Where to go next

• Quickstart: the first ten minutes. Start one server, create a table, change it and read it.
• Run kinedb: Docker or the binary, every argument and every environment variable.
• Backup, restore and import: kd-tool, a logical backup and restore, and the import of a MongoDB mongodump directory.
• SQL reference: every statement that kinedb runs today.
• Architecture: how it works today, and where it is going.
• JavaScript client and Python client: connect from an application.