Skip to content

Oxiland 0.4 storage API proposal

Milestone: 0.4
Status: accepted for implementation
Engine: Oxigraph 0.5.9 + Fjall 2.x (format v1)
Decision: ADR-006

Goals

  • Graduate Model::open from experimental to a supported durable contract.
  • Provide Redland-shaped transactions, sync, clear, bulk load, and capabilities.
  • Keep memory and Fjall behind one facade.
  • Preserve archival continuity via standards RDF (N-Quads / TriG).

On-disk format v1

Fjall partition oxiland_quads stores:

Key Value
__oxiland/meta UTF-8 JSON {"format_version":1,"oxiland":"0.4.0"}
N-Quads line ({quad} .) empty

Model::open / open_with require format v1 (or write it for a brand-new empty store). Pre-0.4 experimental stores (quad keys, no meta) must use Model::migrate_legacy_store.

Public types

  • StorageBackend::{Memory, Fjall}
  • OpenOptions — path, read_only, create (default true)
  • StorageCapabilities — durability, transactions, sync, clear, read_only, bulk
  • ModelTransaction — mutator used inside Model::transaction

Transaction semantics

model.transaction(|tx| {
    tx.add(statement)?;
    Ok(())
})?;
  • Uses Oxigraph Store::start_transaction for the working set.
  • Fjall: write lock for the whole transaction; durable replace_all_from_store only after Oxigraph commit; sync failure reloads memory from disk.
  • Nested Update / auto-commit add while a transaction is open → Unsupported.
  • Drop / Err aborts the Oxigraph transaction (no durable write).

Atomic import

Parser::load_transactional parses fully, then inserts inside Model::transaction so mid-parse failure leaves durable state unchanged.

Legacy Redland backends

See 0.4-legacy-storage.md. Names never silently map to Fjall.