Skip to content
wabe Disk

Server configuration

Global options precede the subcommand. Command-line values override their corresponding environment variables. wabe-disk --help shows the installed binary’s options.

Storage and caching

Section titled “Storage and caching”
Flag Environment variable Default
--data WABE_DISK_DATA .data; local authoritative storage when no bucket is selected.
--bucket WABE_DISK_BUCKET Unset; enables S3 when supplied.
--prefix WABE_DISK_PREFIX wabe-disk.
--cache WABE_DISK_CACHE Unset; optional disposable file cache directory.
--cache-bytes WABE_DISK_CACHE_BYTES 67,108,864 bytes per disk’s local file cache.
--ram-cache-bytes WABE_DISK_RAM_CACHE_BYTES Unset; optional ceiling on the shared RAM cache, including zero to disable.
--ram-cache-percent WABE_DISK_RAM_CACHE_PERCENT 80.

The RAM cache is shared across all disks and grows as blocks are read. Its default budget is 80% of currently available machine or container memory, including reclaimable blocks already in this cache. There is no fixed byte ceiling and no memory reservation per disk. The server checks available memory once a second and adjusts the budget when it changes by at least 5%. LRU eviction removes blocks that have not been used recently. An explicit --ram-cache-bytes adds a ceiling; --ram-cache-percent 0 or --ram-cache-bytes 0 disables the cache.

The cache budget counts decoded block payloads. Active operations, MemTables and allocator overhead also consume memory; this is not a strict process RSS limit. Temporary staging lookups are released after each operation. Keep the disposable file cache separate from authoritative local data, with neither directory containing the other.

Writes and command buffers

Section titled “Writes and command buffers”
Flag Environment variable Default
--durability WABE_DISK_DURABILITY buffered; accepts buffered or remote.
--flush-ms WABE_DISK_FLUSH_MS 10,000 milliseconds.
--memtable-bytes WABE_DISK_MEMTABLE_BYTES 31,457,280 bytes per disk.
--max-unflushed-bytes WABE_DISK_MAX_UNFLUSHED_BYTES 62,914,560 bytes per disk; storage backpressure.
--merge-edits WABE_DISK_MERGE_EDITS 256 edits per private autosave block or tree node; positive integer, at most 4,294,967,295.
--chunk-bytes WABE_DISK_CHUNK_BYTES 65,536 bytes for newly created disks.
--io-bytes WABE_DISK_IO_BYTES 65,536 bytes.
--sort-memory-bytes WABE_DISK_SORT_MEMORY_BYTES 8,388,608 bytes before sort run spilling.

Change an existing disk’s future file chunk size through config. The sort threshold is a spill trigger; it does not bound total process RSS. Scratch files use the operating system’s temporary directory, configurable with TMPDIR.

Authentication and execution

Section titled “Authentication and execution”
Variable / option Behavior
WABE_DISK_API_KEY Optional full-access HTTP key. Must be nonempty visible ASCII without whitespace. Unset means unauthenticated.
WABE_DISK_QJS_WORKER Worker executable; defaults to a sibling wabe-quickjs-worker.
WABE_DISK_JS_CGROUP Optional delegated Linux cgroup v2 subtree for JS workers; requires memory and pids controllers. WABE_QUICKJS_CGROUP is a fallback alias.
serve --port Loopback listening port; default 8090.
WABE_DISK_SQL_MAX_CONCURRENT Maximum active SQL requests per router, shared by HTTP SQL and shell/JavaScript wabesql; default 16. Waiting requests queue asynchronously.
WABE_DISK_SQL_TIMEOUT_MS SQL execution deadline including concurrency admission and response backpressure; default 30000 milliseconds. Initial disk/session context acquisition and HTTP JSON extraction precede this deadline. Accepted storage I/O drains after HTTP timeout.

Without a configured cgroup, the worker uses an address-space limit. Runtime limits lists execution and input defaults. The standalone CLI does not expose every embedded Rust configuration field, including compaction-mode selection.

Optional SQL engine

Section titled “Optional SQL engine”

SQLite is enabled in the default build. The experimental Turso HTTP API requires the Cargo build feature experimental-turso. It has no runtime engine-selection flag or environment variable. An enabled build serves both endpoint families; SQLite remains the engine for wabesql.

Upgrade an existing deployment

Section titled “Upgrade an existing deployment”

The server and CLI use the wabe-disk command and WABE_DISK_* environment variables. Rename the environment keys in your service configuration before restarting. Keep each existing value, including the object-store prefix, bucket and local data path. The new default object-store prefix is wabe-disk; set WABE_DISK_PREFIX explicitly to your existing prefix to keep opening the same disks. Persisted storage format identifiers and content hashes remain unchanged.