Welcome
Kova stores documents, answers SQL, and searches text. One process, one port, the MongoDB wire.
You talk to Kova with a MongoDB driver. The listener speaks the MongoDB wire protocol on port 27018. Insert a document, find it, run a SQL string over the same rows, or search the text. The files on disk are the database. Restart the process and the documents are still there.
What you can do today
| You want to | You use |
|---|---|
| Store and read documents | A MongoDB driver. Documents. |
| Filter, group, and join collections | find and aggregate. Find and aggregate. |
| Ask a SQL question | db.runCommand({ sql }). SQL. |
| Search words, including a typo | $text, or WHERE TEXT. Text search. |
| Speed up a field lookup | createIndex. Indexes. |
| Name a saved pipeline | A view. Views. |
| Number a field on insert | autoincrement. Autoincrement. |
| Commit several writes together | beginTransaction. Transactions. |
| Require a user and a password | [security]. Security. |
| Copy the database to a file | kovadump. Backup and restore. |
| Open the data from a SQL client | The ODBC driver. ODBC. |
| Keep a copy if a machine dies | A replica set. Replica sets. |
| Split one collection across machines | Shards and a router. Sharding. |
How a write lands
A client sends a command. Kova appends that change to a log on disk, then updates the page that holds the document. The reply means the log has the change. A checkpoint later folds those pages into the data directory and shortens the log. If the process stops in between, startup replays the log and the document comes back.
RAM holds a cache of pages, called the buffer pool. A find that misses the cache reads the page from disk. The collection does not have to fit in memory.
One process, until you ask for more
The default kova.toml is one writable process. It stores every document you insert. Security is off, so a client connects and sends commands. Turn security on when you want a user and a password. Add a replica set when you want copies of the same data. Add shards when one machine cannot hold the collection or the writes.
A feed of committed writes, published to Apache Iggy, is planned. It is off. The shape of the record is on the Feed page. Today a program reads with find, or tails local.oplog.rs on a replica set.
Where the files are
| Path | What it is |
|---|---|
kova.toml | Port, data directory, security, replication, sharding. |
data/ | Pages, the write-ahead log, and replica logs for this process. |
~/.local/bin/kova | The server, after the install. |
~/.local/bin/kovadump | Backup and restore. It talks to a server that is already running. |
~/.local/lib/libkova.so | The ODBC driver on Linux. |
The engineering notes stay in docs/ inside the repository. This site is the guide for people running the server.