Skip to main content
← 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: true in the datastore block of .swamp.yaml, or the SWAMP_DATASTORE_DURABLE env var (1/true/yes/on or 0/false/no/off) when the block does not set it. The block wins; any other env value is ignored. Off by default. A non-boolean durable is refused when the config is read, and datastore setup keeps 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/exclude keep 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 custom path, no namespace) orders writes with F_BARRIERFSYNC instead 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 custom path, a namespace, extension and v3 datastores, and data delete/rename/prune/gc keep the full flush; set a custom path where the newest versions must survive a power cut.
  • Errors: a failed sync fails the write with Could not sync <path> to disk: <reason>. Treat EIO/ENOSPC as a disk problem. A filesystem that cannot sync at all gets a hint to set durable: 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○TRIAGED○IN PROGRESS○SHIPPED

Open

10/30/2026, 10:22:53 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.