← Back to list
01Issue
FeatureOpenSwamp ClubPublic
AssigneesNone
Relationships
#4208 Docs: document the datastore durable setting and its macOS ordering in the manual
Opened by stack72 · 10/30/2026
Description
The datastore durable setting shipped in swamp-club#4017 and is not documented in the manual. content/manual/reference/datastore-configuration.md does not mention it, so users cannot discover that data writes are unsynced by default, how to turn syncing on, or what it costs. swamp-club#4032 (PR 3515) changed its behaviour on macOS, which also needs saying. Today only the design docs (design/enablers/datastores.md, design/primitives/data.md) and the swamp skill's repo reference describe it.
What to document (reference/datastore-configuration.md)
- The setting:
durable: truein thedatastoreblock of.swamp.yaml, or theSWAMP_DATASTORE_DURABLEenv var (1/true/yes/onor0/false/no/off) when the block does not set it. The block wins; any other env value is ignored. Off by default. A non-booleandurableis refused when the config is read, anddatastore setupkeeps it across a re-run. - What it guarantees: off, a write is atomic (survives a process crash) but not synced, so a power cut can lose it or publish an empty version (ext4 delayed allocation). On, a version's content and directory entries reach the disk before the latest marker and catalog publish it.
- Where it applies: the filesystem backend and a v2 extension datastore's local cache. On v3, committed versions are already durable; versions the checkout's
directories/excludekeep local are synced as on v2. - Cost: several fsyncs per write. Roughly double write time on a local NVMe disk, more on network and spinning disks.
- macOS (swamp-club#4032): the default datastore (
.swamp/data, no custompath, nonamespace) orders writes withF_BARRIERFSYNCinstead of a full drive-cache flush. A run writing 804 versions took 21 s instead of 36 s (18 s unsynced). The newest versions may not survive a power cut, but a version is never published without its content. A custompath, a namespace, extension and v3 datastores, anddata delete/rename/prune/gckeep the full flush; set a custompathwhere the newest versions must survive a power cut. - Errors: a failed sync fails the write with
Could not sync <path> to disk: <reason>. TreatEIO/ENOSPCas a disk problem. A filesystem that cannot sync at all gets a hint to setdurable: false.
Acceptance
- The datastore configuration reference documents the setting, the env var and precedence, the guarantee, the cost, the macOS behaviour, and the sync error.
- A short note in the data explanation or how-to on when to turn it on (data that must survive a power cut).
02Bog Flow
Open
No activity in this phase yet.
03Sludge Pulse
Sign in to post a ripple.