The Store

For an application that keeps its graph, the Store does everything of the previous pages for you: one directory holds the graph's snapshots and its write-ahead log, every commit is durable before it returns, and opening the directory brings the graph back exactly as the last commit left it, also after a crash. One directory = one graph, one writer: "SQLite for graphs".

The directory is usually a path on disk. It can also be one single file (graph.gstore, for embedded use) or live in memory (every target, the browser included).

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, Store, StoreOptions};

let store = Store::create("data", StoreOptions::new())?;      // or Store::open("data", ..)
store.graph().write().traversal_mut().add_v("person").property("name", "ann").to_list()?;
store.mark("after-ann")?;                                      // a point-in-time target
store.checkpoint(Some("nightly"))?;                            // a snapshot of the current state
store.close()?;                                                // a clean close (Drop does it too)

let past = Store::open_read_only("data", RecoveryTarget::Mark("after-ann".into()))?;
assert_eq!(past.graph.vertex_count(), 1);
Ok::<(), Box<dyn std::error::Error>>(())
}

graphersal store create data/ --from modern     # the same from the command line
graphersal --graph data/ -e 'g.add_v("person").property("name", "ann").to_list()'
graphersal store info data/

The files

data/
├── GRAPH, GRAPH.copy        identity, lineage, state (two copies of the same small file)
├── LOCK                     held by the one writer (an operating-system lock)
├── BACKUP                   the backup pin: held shared while a backup copies, prune waits for it
├── INTENT                   only while a multi-file operation runs (rollback, prune, ...)
├── marks                    the marks, rebuilt from the WAL when lost
├── snapshots/
│   └── 00000000000000000003/      one snapshot, named by its commit (20 digits)
│       ├── manifest               identity, position, counts, the segment list, every chunk's checksum
│       ├── schema.json            the stored schema
│       ├── v-000000.seg           vertices, sorted by id, in compressed chunks
│       └── e-000000.seg           edges
├── wal/
│   └── 00000000000000000004.wal   write-ahead log segments, named by their first commit (16 MiB each)
└── attic/
    └── 20261008T070510Z-00000000000000000002/   history a rollback moved aside

Every name is relative to the store's root, and no file records a path: move or copy the whole directory and open it there. The exact byte layouts are the Storage Format Specification.

The pages of the Store

What works while the store is open elsewhere (a dev server, a REPL, another program):