@loradb/lora-node 0.36.0 → 0.36.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +349 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +538 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- package/package.json +13 -14
package/docs/snapshot.md
ADDED
|
@@ -0,0 +1,545 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Snapshots"
|
|
3
|
+
description: "Manual point-in-time snapshots — save and restore the full in-memory LoraDB graph as a single file or byte payload, through every binding and the opt-in HTTP admin surface. Standalone for backups, or paired with WAL-backed recovery on every filesystem-backed surface."
|
|
4
|
+
online: "https://loradb.com/docs/snapshot"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Snapshots
|
|
9
|
+
|
|
10
|
+
LoraDB can dump the in-memory graph to a single file and restore it
|
|
11
|
+
later. A snapshot is the full graph frozen from the database's current
|
|
12
|
+
Arc snapshot — taken on demand, atomic on rename, readable from any
|
|
13
|
+
binding.
|
|
14
|
+
|
|
15
|
+
Snapshots are shipped as of v0.3. They close the "no persistence at
|
|
16
|
+
all" gap for workloads that only need occasional save / restore
|
|
17
|
+
operations (seeded services, notebooks, graceful-shutdown saves,
|
|
18
|
+
scheduled backups). Continuous durability is now available through the
|
|
19
|
+
[WAL](./wal.md) on every filesystem-backed surface, but snapshots are
|
|
20
|
+
still the portable file primitive those surfaces checkpoint to.
|
|
21
|
+
|
|
22
|
+
## What a snapshot is
|
|
23
|
+
|
|
24
|
+
- A **single encoded payload** containing the full graph — every node,
|
|
25
|
+
every relationship, every property — plus a short header describing
|
|
26
|
+
the format. Filesystem bindings write that payload as one file; WASM
|
|
27
|
+
returns bytes or web-native wrappers around those bytes.
|
|
28
|
+
- A **point-in-time dump.** The save loads the current Arc snapshot and
|
|
29
|
+
encodes that graph consistently; readers already using an older Arc
|
|
30
|
+
continue normally.
|
|
31
|
+
- **Atomic on rename for path-based saves.** Writes land in
|
|
32
|
+
`<path>.tmp`, are `fsync`'d, then renamed over the target; a
|
|
33
|
+
crashed save can leave a stale `.tmp` file but never a half-written
|
|
34
|
+
target.
|
|
35
|
+
- **Format-versioned.** Files declare an envelope/body format version; the
|
|
36
|
+
reader accepts supported versions and rejects unsupported ones rather than
|
|
37
|
+
partially loading unknown data.
|
|
38
|
+
|
|
39
|
+
## What snapshots are not
|
|
40
|
+
|
|
41
|
+
The bright line, stated explicitly so it cannot be missed:
|
|
42
|
+
|
|
43
|
+
- **Not continuous durability.** A crash between two saves loses every
|
|
44
|
+
mutation in the window unless you pair snapshots with the WAL on a
|
|
45
|
+
filesystem-backed surface.
|
|
46
|
+
- **Not a wall-clock checkpoint scheduler.** Manual snapshots run when
|
|
47
|
+
you call them. Explicit WAL helpers can also write managed snapshots
|
|
48
|
+
after N committed transactions, but there is no built-in timer.
|
|
49
|
+
- **Not a WAL write.** Loading a snapshot into a WAL-backed database
|
|
50
|
+
checkpoints the loaded graph into its managed snapshot directory or
|
|
51
|
+
`.loradb` file before the load returns. A WAL-backed database with
|
|
52
|
+
neither refuses the load with `LORA_CONFIG`; restore it at startup with
|
|
53
|
+
`--restore-from` instead.
|
|
54
|
+
- **Not a general persistent storage layer.** There is no alternative
|
|
55
|
+
backend; a snapshot is a dump of the in-memory graph, not a format
|
|
56
|
+
a different engine writes into.
|
|
57
|
+
- **Not free.** Saves and loads are whole-graph operations. Existing
|
|
58
|
+
readers can keep using their pinned Arc snapshot, but the encode/decode work
|
|
59
|
+
is still proportional to graph size.
|
|
60
|
+
- **Not a multi-tenant boundary.** One process holds one graph; each
|
|
61
|
+
process you run needs its own snapshot file.
|
|
62
|
+
|
|
63
|
+
## When to use snapshots
|
|
64
|
+
|
|
65
|
+
Good fits:
|
|
66
|
+
|
|
67
|
+
- **Seeded services and agents.** Build the graph offline from a
|
|
68
|
+
cheaper source, snapshot it, and ship the file alongside the
|
|
69
|
+
deployment. Every restart boots in one file-read.
|
|
70
|
+
- **Notebooks, demos, research tooling.** Save what you've curated;
|
|
71
|
+
reload it tomorrow with one call.
|
|
72
|
+
- **Graceful shutdown.** A final `save_snapshot` (or `POST
|
|
73
|
+
/admin/snapshot/save` from systemd `ExecStop`) preserves the graph
|
|
74
|
+
across planned restarts.
|
|
75
|
+
- **Scheduled backups.** A cron that calls the admin endpoint with a
|
|
76
|
+
rotating filename every N minutes is a complete backup policy for
|
|
77
|
+
graphs that fit the save window.
|
|
78
|
+
|
|
79
|
+
Bad fits:
|
|
80
|
+
|
|
81
|
+
- **Hard-durability workloads.** If losing even a minute of mutations
|
|
82
|
+
on crash is unacceptable, snapshots alone are not enough — use one
|
|
83
|
+
of the [WAL-enabled surfaces](./wal.md).
|
|
84
|
+
- **Very large graphs where save time exceeds your query window.** Save work is
|
|
85
|
+
proportional to graph size and can add meaningful CPU/I/O pressure.
|
|
86
|
+
|
|
87
|
+
## Metadata
|
|
88
|
+
|
|
89
|
+
Path-based saves, load calls, and HTTP admin calls return a small
|
|
90
|
+
metadata record. Byte-output save APIs such as WASM `saveSnapshot()` or
|
|
91
|
+
Node `saveSnapshot()` return the snapshot bytes directly instead.
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"formatVersion": 3,
|
|
96
|
+
"nodeCount": 1024,
|
|
97
|
+
"relationshipCount": 4096,
|
|
98
|
+
"walLsn": null
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
| Field | Type | Meaning |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `formatVersion` | integer | Envelope format of the snapshot file. `3` for every snapshot this release writes; `2` when loading one an older release wrote. |
|
|
105
|
+
| `nodeCount` | integer | Nodes in the saved / restored graph. |
|
|
106
|
+
| `relationshipCount` | integer | Relationships in the saved / restored graph. |
|
|
107
|
+
| `walLsn` | integer or null | The WAL fence on a WAL-backed database, for saves and checkpoints alike; `null` for a database without a WAL. |
|
|
108
|
+
|
|
109
|
+
Whenever metadata is returned, every binding uses the same four
|
|
110
|
+
fields; the spelling of the field names matches the wire shape
|
|
111
|
+
(camelCase).
|
|
112
|
+
|
|
113
|
+
## Compression and encryption
|
|
114
|
+
|
|
115
|
+
Embedded bindings can save snapshots with codec options:
|
|
116
|
+
|
|
117
|
+
| Option | Supported values |
|
|
118
|
+
|---|---|
|
|
119
|
+
| `compression` | `"none"`, `"gzip"`, `"zstd"`, `{ format: "gzip", level: 0..9 }` or `{ format: "zstd", level: 1..22 }` (zstd: native builds; wasm reads it but cannot write it) |
|
|
120
|
+
| `encryption` | Password / passphrase encryption, or a raw 32-byte key |
|
|
121
|
+
|
|
122
|
+
Password encryption is the most portable shape:
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
const encryption = {
|
|
126
|
+
type: 'password',
|
|
127
|
+
keyId: 'backup-key',
|
|
128
|
+
password: process.env.LORA_SNAPSHOT_PASSWORD!,
|
|
129
|
+
};
|
|
130
|
+
|
|
131
|
+
await db.saveSnapshot('graph.lorasnap', {
|
|
132
|
+
compression: { format: 'gzip', level: 1 },
|
|
133
|
+
encryption,
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
await db.loadSnapshot('graph.lorasnap', { credentials: encryption });
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Node, Python, WASM, and Ruby accept this JSON-style option shape; Go
|
|
140
|
+
mirrors it with `SnapshotOptions`, `SnapshotCompression`, and
|
|
141
|
+
`SnapshotEncryption` structs; Rust uses the typed `SnapshotOptions`,
|
|
142
|
+
`SnapshotPassword`, and `EncryptionKey` structs. Load calls accept the
|
|
143
|
+
credentials either under `credentials` or `encryption`, so the same
|
|
144
|
+
object used to save can usually be reused to load. HTTP admin snapshot
|
|
145
|
+
routes do not accept per-call codec options today; use an in-process
|
|
146
|
+
binding when you need custom compression or encryption.
|
|
147
|
+
|
|
148
|
+
## Binding examples
|
|
149
|
+
|
|
150
|
+
Snapshots are exposed on every binding that exposes the engine. The
|
|
151
|
+
shape is always "save produces a file or byte payload, load consumes a
|
|
152
|
+
source, and metadata is returned whenever the operation has a metadata
|
|
153
|
+
surface".
|
|
154
|
+
|
|
155
|
+
### Rust
|
|
156
|
+
|
|
157
|
+
The reference surface. Every other binding wraps these two methods.
|
|
158
|
+
|
|
159
|
+
```rust
|
|
160
|
+
use lora_database::Database;
|
|
161
|
+
|
|
162
|
+
let db = Database::in_memory();
|
|
163
|
+
db.execute("CREATE (:Person {name: 'Ada'})", None)?;
|
|
164
|
+
|
|
165
|
+
// Dump the graph to a file. Atomic on rename.
|
|
166
|
+
let meta = db.save_snapshot_to("graph.bin")?;
|
|
167
|
+
println!("saved {} nodes, {} relationships",
|
|
168
|
+
meta.node_count, meta.relationship_count);
|
|
169
|
+
|
|
170
|
+
// Boot a fresh Database directly from the snapshot.
|
|
171
|
+
let db2 = Database::in_memory_from_snapshot("graph.bin")?;
|
|
172
|
+
|
|
173
|
+
// Or overlay a snapshot onto an existing handle.
|
|
174
|
+
db.load_snapshot_from("graph.bin")?;
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
`SnapshotMeta` is re-exported from `lora_database`:
|
|
178
|
+
|
|
179
|
+
```rust
|
|
180
|
+
use lora_database::SnapshotMeta;
|
|
181
|
+
fn log_meta(m: SnapshotMeta) {
|
|
182
|
+
tracing::info!(
|
|
183
|
+
format = m.format_version,
|
|
184
|
+
nodes = m.node_count,
|
|
185
|
+
rels = m.relationship_count,
|
|
186
|
+
wal = ?m.wal_lsn,
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Python
|
|
192
|
+
|
|
193
|
+
Synchronous:
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
from lora_python import Database
|
|
197
|
+
|
|
198
|
+
db = Database.create()
|
|
199
|
+
db.execute("CREATE (:Person {name: 'Ada'})")
|
|
200
|
+
|
|
201
|
+
meta = db.save_snapshot("graph.bin")
|
|
202
|
+
print(meta["nodeCount"], meta["relationshipCount"])
|
|
203
|
+
|
|
204
|
+
db2 = Database.create()
|
|
205
|
+
db2.load_snapshot("graph.bin")
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Async — same methods as coroutines on `AsyncDatabase`:
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
import asyncio
|
|
212
|
+
from lora_python import AsyncDatabase
|
|
213
|
+
|
|
214
|
+
async def main():
|
|
215
|
+
db = await AsyncDatabase.create()
|
|
216
|
+
await db.execute("CREATE (:Person {name: 'Ada'})")
|
|
217
|
+
await db.save_snapshot("graph.bin")
|
|
218
|
+
|
|
219
|
+
db2 = await AsyncDatabase.create()
|
|
220
|
+
await db2.load_snapshot("graph.bin")
|
|
221
|
+
|
|
222
|
+
asyncio.run(main())
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Both the sync and async forms run with the GIL released (sync) / on a
|
|
226
|
+
worker thread (async) so other Python threads / coroutines make
|
|
227
|
+
progress during the call. A large save still consumes native engine work and
|
|
228
|
+
filesystem I/O proportional to graph size.
|
|
229
|
+
|
|
230
|
+
### Node.js / TypeScript
|
|
231
|
+
|
|
232
|
+
```ts
|
|
233
|
+
import { createDatabase, type SnapshotMeta } from '@loradb/lora-node';
|
|
234
|
+
|
|
235
|
+
const db = await createDatabase(); // in-memory by default
|
|
236
|
+
// const db = await createDatabase('app', { databaseDir: './data' }); // container-backed
|
|
237
|
+
await db.execute("CREATE (:Person {name: 'Ada'})");
|
|
238
|
+
|
|
239
|
+
const meta: SnapshotMeta = await db.saveSnapshot('graph.bin');
|
|
240
|
+
console.log(meta.nodeCount, meta.relationshipCount);
|
|
241
|
+
|
|
242
|
+
const db2 = await createDatabase();
|
|
243
|
+
await db2.loadSnapshot('graph.bin');
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`saveSnapshot(path)` writes atomically and resolves to `SnapshotMeta`.
|
|
247
|
+
Calling `saveSnapshot()` with no path returns a Node `Buffer`; you can
|
|
248
|
+
also request `uint8Array`, `arrayBuffer`, `base64`, or a Node stream.
|
|
249
|
+
`loadSnapshot` accepts a string / `URL` path, `Buffer`, `Uint8Array`,
|
|
250
|
+
`ArrayBuffer`, Node `Readable`, Web `ReadableStream`, or async
|
|
251
|
+
iterable. The native engine work still encodes or decodes the whole graph for
|
|
252
|
+
the duration of the save or load.
|
|
253
|
+
|
|
254
|
+
### WebAssembly
|
|
255
|
+
|
|
256
|
+
WASM has no filesystem path API. The snapshot API is byte/source based:
|
|
257
|
+
the caller chooses where to persist the bytes, and `loadSnapshot` never
|
|
258
|
+
accepts a string path.
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
import { createDatabase } from '@loradb/lora-wasm';
|
|
262
|
+
|
|
263
|
+
const db = await createDatabase();
|
|
264
|
+
await db.execute("CREATE (:Person {name: 'Ada'})");
|
|
265
|
+
|
|
266
|
+
// Serialize the graph to a Uint8Array.
|
|
267
|
+
const bytes: Uint8Array = await db.saveSnapshot();
|
|
268
|
+
|
|
269
|
+
// Persist however your app already stores state:
|
|
270
|
+
// IndexedDB, localStorage, OPFS, a POST to your backend,
|
|
271
|
+
// `fs.writeFileSync` in Node — all work.
|
|
272
|
+
|
|
273
|
+
// Later (same or a new session), restore from bytes.
|
|
274
|
+
const db2 = await createDatabase();
|
|
275
|
+
await db2.loadSnapshot(bytes);
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
`saveSnapshot` can also return `{ format: "arrayBuffer" }`,
|
|
279
|
+
`"blob"`, `"response"`, `"stream"`, or `"url"`. `loadSnapshot`
|
|
280
|
+
accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, or a
|
|
281
|
+
`ReadableStream<Uint8Array | ArrayBuffer>`.
|
|
282
|
+
|
|
283
|
+
The Worker-backed surface (`createWorkerDatabase`) exposes the same
|
|
284
|
+
`saveSnapshot` / `loadSnapshot` methods and moves the snapshot work to
|
|
285
|
+
the worker thread.
|
|
286
|
+
|
|
287
|
+
#### Persist across reloads with IndexedDB
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
const DB = 'loradb-snapshots', STORE = 'graph', KEY = 'main';
|
|
291
|
+
|
|
292
|
+
async function idb(): Promise<IDBDatabase> {
|
|
293
|
+
return await new Promise((ok, err) => {
|
|
294
|
+
const r = indexedDB.open(DB, 1);
|
|
295
|
+
r.onupgradeneeded = () => r.result.createObjectStore(STORE);
|
|
296
|
+
r.onsuccess = () => ok(r.result);
|
|
297
|
+
r.onerror = () => err(r.error);
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
async function saveToIdb(db: Database) {
|
|
302
|
+
const bytes = await db.saveSnapshot();
|
|
303
|
+
const idbDb = await idb();
|
|
304
|
+
await new Promise<void>((ok, err) => {
|
|
305
|
+
const tx = idbDb.transaction(STORE, 'readwrite');
|
|
306
|
+
tx.objectStore(STORE).put(bytes, KEY);
|
|
307
|
+
tx.oncomplete = () => ok();
|
|
308
|
+
tx.onerror = () => err(tx.error);
|
|
309
|
+
});
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
async function loadFromIdb(db: Database) {
|
|
313
|
+
const idbDb = await idb();
|
|
314
|
+
const bytes = await new Promise<Uint8Array | undefined>((ok, err) => {
|
|
315
|
+
const tx = idbDb.transaction(STORE, 'readonly');
|
|
316
|
+
const r = tx.objectStore(STORE).get(KEY);
|
|
317
|
+
r.onsuccess = () => ok(r.result);
|
|
318
|
+
r.onerror = () => err(r.error);
|
|
319
|
+
});
|
|
320
|
+
if (bytes) await db.loadSnapshot(bytes);
|
|
321
|
+
}
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
### Go
|
|
325
|
+
|
|
326
|
+
```go
|
|
327
|
+
import lora "github.com/lora-db/lora/crates/bindings/lora-go"
|
|
328
|
+
|
|
329
|
+
db, err := lora.New()
|
|
330
|
+
if err != nil { log.Fatal(err) }
|
|
331
|
+
defer db.Close()
|
|
332
|
+
|
|
333
|
+
if _, err := db.Execute("CREATE (:Person {name: 'Ada'})", nil); err != nil {
|
|
334
|
+
log.Fatal(err)
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
meta, err := db.SaveSnapshot("graph.bin")
|
|
338
|
+
if err != nil { log.Fatal(err) }
|
|
339
|
+
fmt.Printf("nodes=%d rels=%d\n", meta.NodeCount, meta.RelationshipCount)
|
|
340
|
+
|
|
341
|
+
db2, err := lora.New()
|
|
342
|
+
if err != nil { log.Fatal(err) }
|
|
343
|
+
defer db2.Close()
|
|
344
|
+
|
|
345
|
+
if _, err := db2.LoadSnapshot("graph.bin"); err != nil {
|
|
346
|
+
log.Fatal(err)
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`SnapshotMeta.WalLsn` is a `*uint64`; it is `nil` for snapshots saved
|
|
351
|
+
without a WAL and non-`nil` when you load or save a snapshot stamped by a
|
|
352
|
+
WAL-enabled surface.
|
|
353
|
+
|
|
354
|
+
### Ruby
|
|
355
|
+
|
|
356
|
+
```ruby
|
|
357
|
+
require "lora_ruby"
|
|
358
|
+
|
|
359
|
+
db = LoraRuby::Database.create
|
|
360
|
+
db.execute("CREATE (:Person {name: 'Ada'})")
|
|
361
|
+
|
|
362
|
+
meta = db.save_snapshot("graph.bin")
|
|
363
|
+
puts "#{meta['nodeCount']} nodes, #{meta['relationshipCount']} relationships"
|
|
364
|
+
|
|
365
|
+
db2 = LoraRuby::Database.create
|
|
366
|
+
db2.load_snapshot("graph.bin")
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
## HTTP admin surface
|
|
370
|
+
|
|
371
|
+
`lora-server` exposes snapshot save and load as two HTTP endpoints.
|
|
372
|
+
Both are **opt-in**: they are mounted only when the server is started
|
|
373
|
+
with `--snapshot-path`.
|
|
374
|
+
|
|
375
|
+
### Enabling the endpoints
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
lora-server \
|
|
379
|
+
--host 127.0.0.1 --port 4747 \
|
|
380
|
+
--snapshot-path /var/lib/lora/db.bin
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
Without the flag, the routes return `404`. This is deliberate — the
|
|
384
|
+
admin surface has no authentication, and an unauthenticated admin
|
|
385
|
+
endpoint on a network-reachable port is a footgun. Off by default
|
|
386
|
+
means "never exposed by accident".
|
|
387
|
+
|
|
388
|
+
The same path can also be provided via the `LORA_SERVER_SNAPSHOT_PATH`
|
|
389
|
+
environment variable.
|
|
390
|
+
|
|
391
|
+
### Saving and loading
|
|
392
|
+
|
|
393
|
+
```bash
|
|
394
|
+
curl -sX POST http://127.0.0.1:4747/admin/snapshot/save
|
|
395
|
+
# => {"formatVersion":3,"nodeCount":1024,"relationshipCount":4096,"walLsn":null,"path":"/var/lib/lora/db.bin"}
|
|
396
|
+
|
|
397
|
+
curl -sX POST http://127.0.0.1:4747/admin/snapshot/load
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Both endpoints accept an optional `{ "path": "…" }` body that
|
|
401
|
+
overrides the configured default for one request — useful for ad-hoc
|
|
402
|
+
backups to a rotated filename. Overrides are only accepted when the
|
|
403
|
+
server runs with `--admin-path-root <DIR>`, and must stay inside `DIR`:
|
|
404
|
+
|
|
405
|
+
```bash
|
|
406
|
+
curl -sX POST http://127.0.0.1:4747/admin/snapshot/save \
|
|
407
|
+
-H 'content-type: application/json' \
|
|
408
|
+
-d '{"path": "/var/backups/lora/2026-04-24.bin"}'
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
The response includes the same four metadata fields as every other
|
|
412
|
+
binding, plus the `path` that was actually used.
|
|
413
|
+
|
|
414
|
+
When WAL is enabled, every save stamps `walLsn` with the durable WAL
|
|
415
|
+
fence, so the file can be recovered over the same WAL directory without
|
|
416
|
+
replaying writes it already holds. `POST /admin/checkpoint` writes the
|
|
417
|
+
same format and also marks the WAL and drops the segments the snapshot
|
|
418
|
+
covers; a plain save leaves the WAL alone. See
|
|
419
|
+
[WAL and checkpoints](./wal.md).
|
|
420
|
+
|
|
421
|
+
### Restoring at boot
|
|
422
|
+
|
|
423
|
+
`--restore-from <PATH>` loads a snapshot once, at startup, before the
|
|
424
|
+
server begins accepting queries:
|
|
425
|
+
|
|
426
|
+
```bash
|
|
427
|
+
lora-server \
|
|
428
|
+
--restore-from /var/lib/lora/seed.bin \
|
|
429
|
+
--snapshot-path /var/lib/lora/runtime.bin
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
- A missing file at boot is fine: the server logs a message and starts
|
|
433
|
+
with an empty graph.
|
|
434
|
+
- A malformed file at boot is fatal.
|
|
435
|
+
- `--restore-from` is **independent** of `--snapshot-path`. You can
|
|
436
|
+
restore from a read-only seed and snapshot to a writable runtime
|
|
437
|
+
path, or pass the same path to both for the "boot from the last save
|
|
438
|
+
every time" pattern:
|
|
439
|
+
|
|
440
|
+
```bash
|
|
441
|
+
lora-server \
|
|
442
|
+
--host 127.0.0.1 --port 4747 \
|
|
443
|
+
--snapshot-path /var/lib/lora/db.bin \
|
|
444
|
+
--restore-from /var/lib/lora/db.bin
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### Security warning
|
|
448
|
+
|
|
449
|
+
> **Caution**
|
|
450
|
+
>
|
|
451
|
+
>
|
|
452
|
+
> The admin endpoints have **no authentication**, and the optional
|
|
453
|
+
> `path` body field is passed straight to the OS. Any client that can
|
|
454
|
+
> reach the admin port can:
|
|
455
|
+
>
|
|
456
|
+
> - write files anywhere the server UID can write, or
|
|
457
|
+
> - swap the live graph by pointing `load` at an attacker-staged file.
|
|
458
|
+
>
|
|
459
|
+
> Do not expose the admin surface on a network-reachable host without
|
|
460
|
+
> authenticated ingress in front of it. A reverse proxy with auth, a
|
|
461
|
+
> Unix socket, or simply not binding the port at all are all acceptable
|
|
462
|
+
> answers. Future releases may add authentication; until then, the
|
|
463
|
+
> correct deployment is "admin surface disabled by default, enabled only
|
|
464
|
+
> behind an auth boundary".
|
|
465
|
+
>
|
|
466
|
+
> See [Limitations → HTTP server](./limitations.md#http-server) and
|
|
467
|
+
> [HTTP API → Admin endpoints (opt-in)](https://loradb.com/docs/api/http#admin-endpoints-opt-in)
|
|
468
|
+
> for the detailed security profile.
|
|
469
|
+
>
|
|
470
|
+
|
|
471
|
+
## File format (reference)
|
|
472
|
+
|
|
473
|
+
Snapshots are written in envelope format 3: framed records, each frame
|
|
474
|
+
compressed on its own so snapshots are built and read on every core. Files
|
|
475
|
+
declare their envelope format version and are rejected when the reader does not
|
|
476
|
+
support it. Format 2 (one column-oriented body) still loads; the `LORASNAP`
|
|
477
|
+
legacy format has been retired.
|
|
478
|
+
|
|
479
|
+
```
|
|
480
|
+
[0..8) magic "LORACOL1"
|
|
481
|
+
[8..12) format u32 — envelope format, currently 3
|
|
482
|
+
[12..16) manifest_len u32
|
|
483
|
+
[16..24) body_len u64
|
|
484
|
+
[24..56) checksum BLAKE3(manifest || body)
|
|
485
|
+
[56..) manifest explicit binary manifest
|
|
486
|
+
[...end) body framed records and catalogs (format 3), or a column-oriented payload (format 2)
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
The manifest carries `walLsn`, node and relationship counts,
|
|
490
|
+
compression, encryption metadata, and the body length. A format 3 body holds
|
|
491
|
+
the id counters and the graph's dictionaries, then nodes and relationships in
|
|
492
|
+
frames of 4,096 ids, then one catalog frame with the index, constraint and
|
|
493
|
+
vector index definitions, so `SHOW INDEXES` and `SHOW CONSTRAINTS` state
|
|
494
|
+
survives snapshot save/load. Each frame is compressed on its own (zstd by
|
|
495
|
+
default, gzip or none); encryption seals the whole body. A format 2 body stores
|
|
496
|
+
the same graph in separate columns (body versions 2 to 5); older catalog-free
|
|
497
|
+
bodies still load with empty index and constraint lists.
|
|
498
|
+
|
|
499
|
+
Readers validate the magic bytes, the format version, every length and
|
|
500
|
+
the BLAKE3 checksum, and build the loaded graph beside the current one.
|
|
501
|
+
A file that fails any check is rejected, and the graph in memory is not
|
|
502
|
+
touched until the load succeeds. Snapshots may come from uploads, so a
|
|
503
|
+
reader never allocates from a length the file states: a frame claiming
|
|
504
|
+
more than 1 GiB, inflating to a different size than it declares, or
|
|
505
|
+
holding bytes after its compressed data is refused.
|
|
506
|
+
|
|
507
|
+
## Limitations
|
|
508
|
+
|
|
509
|
+
Worth restating, because the failure modes are where snapshots bite:
|
|
510
|
+
|
|
511
|
+
- **Manual save and restore only.** Manual snapshots run when you call
|
|
512
|
+
them. Explicit WAL helpers can also write managed snapshots after N
|
|
513
|
+
committed transactions, but there is no wall-clock scheduler.
|
|
514
|
+
- **Snapshots alone are not continuous durability.** A crash between
|
|
515
|
+
saves loses every mutation in the window unless you pair snapshots
|
|
516
|
+
with the [WAL](./wal.md).
|
|
517
|
+
- **Whole-graph work.** Save and load encode/decode the entire graph. Existing
|
|
518
|
+
readers can continue on already-loaded Arc snapshots, but new queries see the
|
|
519
|
+
restored graph only after load publishes it.
|
|
520
|
+
- **One process, one graph.** Each process you run needs its own
|
|
521
|
+
snapshot file.
|
|
522
|
+
- **No partial or incremental snapshots.** Every save serializes the
|
|
523
|
+
whole graph.
|
|
524
|
+
- **Admin surface is unauthenticated.** Opt-in is the only safety
|
|
525
|
+
control today; put an authenticated ingress in front of it on any
|
|
526
|
+
host that isn't exclusively localhost.
|
|
527
|
+
|
|
528
|
+
For the underlying engine internals (wire format, mutation-event
|
|
529
|
+
surface, forward-compatibility rules, atomicity guarantees on the
|
|
530
|
+
parent-dir fsync), see the internal
|
|
531
|
+
[Snapshots operator doc](https://github.com/lora-db/lora/blob/main/docs/operations/snapshots.md).
|
|
532
|
+
|
|
533
|
+
## See also
|
|
534
|
+
|
|
535
|
+
- [**Rust guide → Persisting your graph**](https://loradb.com/docs/getting-started/rust#persisting-your-graph)
|
|
536
|
+
- [**Python guide → Persisting your graph**](https://loradb.com/docs/getting-started/python#persisting-your-graph)
|
|
537
|
+
- [**Node guide → Persisting your graph**](./getting-started/node.md#persisting-your-graph)
|
|
538
|
+
- [**WASM guide → Persisting your graph**](https://loradb.com/docs/getting-started/wasm#persisting-your-graph)
|
|
539
|
+
- [**Go guide → Persisting your graph**](https://loradb.com/docs/getting-started/go#persisting-your-graph)
|
|
540
|
+
- [**HTTP server → Snapshots, WAL, and restore**](https://loradb.com/docs/getting-started/server#snapshots-wal-and-restore)
|
|
541
|
+
- [**HTTP API → Admin endpoints (opt-in)**](https://loradb.com/docs/api/http#admin-endpoints-opt-in)
|
|
542
|
+
- [**WAL and checkpoints**](./wal.md)
|
|
543
|
+
- [**Cookbook → Backup and restore**](./cookbook.md#backup-and-restore)
|
|
544
|
+
- [**Limitations → Storage**](./limitations.md#storage)
|
|
545
|
+
- [**Troubleshooting → Snapshots**](./troubleshooting.md#snapshots)
|