Single-File Format
The .kitedb file layout
KiteDB stores everything in a single .kitedb file. This makes databases portable, simplifies deployment, and enables atomic operations.
File Layout
Database metadata, pointers, checksums
CSR data, compressed with zstd
The Header
The header is 4 KB and contains all metadata needed to open the database:
Header Contents
offset 0, always 4 KBAtomic Updates
The header enables atomic state transitions. A checkpoint works like this:
Checkpoint Process
If crash occurs:
No intermediate state is possible.
WAL Area
The WAL area is a circular buffer divided into two regions:
Default WAL size is 1MB. Auto-checkpoint is enabled by default and triggers when WAL usage exceeds 80% of the active region. Increase WAL size for high-throughput ingest. WAL size is fixed at creation; change it via `resizeWal` (offline) or rebuild into a new file.
WAL Area
64 MB exampleWhy two regions?
- •Checkpoint reads primary to build new snapshot
- •Concurrent transactions write to secondary
- →No blocking between reads and writes
Snapshot Area
The snapshot area holds the CSR-formatted graph data:
Snapshot Sections
File Growth
The file grows in predictable ways:
File Size Examples
Example below assumes a 64MB WAL. Default WAL size is 1MB and configurable.
Single-File vs Multi-File
KiteDB previously supported a directory-based format. Single-file is now the default:
| Aspect | Single-File | Directory (legacy) |
|---|---|---|
| Portability | Copy one file | Copy entire directory |
| Atomic ops | Header flip | Manifest + renames |
| Disk usage | ~40% smaller | More overhead |
| Complexity | Simpler | More moving parts |
Opening a Database
Opening a Database
If WAL replay finds incomplete transaction:Discard it (never committed). Recovery is automatic and fast.
Next Steps
- WAL & Durability – How the write-ahead log provides crash safety
- Snapshot + Delta – How reads merge these two sources