This section is about what is underneath the SQL. You do not need any of it to use the database, and you will want some of it the first time something is slower than you expected or a file will not open.
The one idea
WitDatabase is six interfaces stacked on each other. Each has implementations registered under a key, and each can be replaced on its own without disturbing the rest.
Read the list downward and you have the path a row takes on its way to the disk.
| Layer | Interface | What it decides |
|---|---|---|
| Storage engine | IKeyValueStore |
How keys and values are laid out and found again |
| Secondary indexes | ISecondaryIndexFactory |
What can be looked up without a scan |
| Transaction journal | ITransactionJournal |
What survives the power going out |
| Page cache | IPageCache |
Which pages stay in memory |
| Encryption | ICryptoProvider |
How pages are protected at rest |
| Storage backend | IStorage |
Where the pages physically go |
Architecture covers how the registry works and what it takes to write an implementation of your own. It is the article to read first if the arrangement above is the reason you are here.
The SQL layer above all this is fixed. The parser, the planner, the executor and the transaction semantics are what make an application written for a full database server keep working when the server is swapped out, and a pluggable version of that would be a pluggable promise.
Reference
File format is what a .witdb contains and how format versions relate,
which matters when the file is a document your users keep.
Benchmarks is where the numbers live, with the conditions they were measured under. No other page on this site quotes a figure.
Limitations is what the engine does not do. The list is kept as failing tests in the repository, so an entry leaves it when the behaviour arrives.
Troubleshooting maps the errors you are most likely to meet onto the pages that explain them.
If you are here for a reason
Something is slow. Benchmarks will tell you whether the shape of your workload is one this engine is good at. Then indexing, since a missing index outweighs everything else on this list, and caching if the working set is larger than memory.
A file will not open. File format for version compatibility, encryption if it is protected.
Something surprised you. Troubleshooting if you are holding an error message, limitations if you are not.
You need the database somewhere it does not go. Architecture, then the article for the layer you mean to replace.