Skip to content

storage.md

Latest commit

 

History

History
35 lines (26 loc) · 1.55 KB

storage.md

File metadata and controls

35 lines (26 loc) · 1.55 KB

Storage Contract

Backend and File Layout

  • Storage backend: redb 3.x.
  • Database file: DB_PATH/data.redb.
  • Writer coordination lock file: DB_PATH/db.owner.lock.
  • Embedded GUI endpoint discovery file (GUI runtime only): DB_PATH/.api-addr.
  • pastes_meta is a derived projection used for list/search/filter work, including derived retrieval metadata (kind, compact handle, top terms).
  • pastes_meta_state stores the projection schema version; startup rebuilds pastes_meta from authoritative paste rows only when that marker is missing or stale.

Compatibility Policy

  • Until stable release, backward compatibility is not required.
  • This project does not provide a sled-to-redb migration path.
  • Existing sled-era artifacts are considered incompatible with current runtime.
  • If data.redb is missing and legacy sled artifacts are present, startup fails with an explicit incompatible-storage error.

Caution

Sled-era data is not auto-migrated. Use a fresh DB_PATH for current builds unless you explicitly convert data yourself.

Durability and Atomicity

  • redb write transactions are commit-durable.
  • LocalPaste relies on commit() durability; there is no required explicit flush step.
  • Multi-table write operations are executed inside single redb write transactions where invariant coupling matters.

Operational Expectations

  • One writer process per DB_PATH at a time.
  • Do not run localpaste-gui and standalone localpaste concurrently on the same DB_PATH.
  • For isolated local testing, use distinct DB_PATH directories.