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. The kinedb binary gives you the same engine from a shell:

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

Status: the library works on disk and in memory, and it compiles to WebAssembly.

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: replace .html with .md in its URL, for example https://docs.kinedb.com/sql.md.

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

• Run kinedb: Docker or the binary, every argument and every environment variable.
• 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.