Checkpointing and compaction

On this page

Checkpoint policies

Checkpoint policies

Run this standalone, auto-commit statement in Explorer or a Bolt driver:

CALL gdb.checkpoint();

The selected storage mode determines the maintenance work. See maintenance calls for more details.

An idle checkpoint does not rotate an empty log or rewrite an unchanged resident snapshot. Checkpoint also purges unused in-memory string interner data.

Hybrid: seal and compact

A routine hybrid checkpoint does not walk the graph or rewrite every property. It syncs and renames the active file to its immutable numbered name, then creates a small fresh wal.log. Segment publication is O(1) in graph size.

Stale-property compaction

Sealing alone would retain every overwritten payload forever. At each checkpoint the engine may therefore compact at most one worthwhile sealed segment:

all topology/schema/removal mutations and every transaction LSN are retained;
only obsolete property-update records are omitted;
live property records are copied and the key directory is relocated;
a synced .compact file is published through an old/new rename handoff. Crash recovery deterministically completes or rolls back an interrupted handoff;
policy thresholds avoid rewriting a segment for a small saving, which is kinder to SSDs.

This caps each maintenance pass at one segment rewrite and reclaims the large historical value payloads incrementally. Selecting a candidate still scans the segment metadata, so checkpoint CPU is linear in the number of segments even though bytes rewritten in one pass are bounded. The small structural mutation history and frame metadata remain append-only; recovery still replays them to rebuild the RAM graph and derived indexes. A dump/restore is the explicit full logical rebase when one is required.

Resident: snapshot and reset

A resident checkpoint serialises the complete committed graph to a temporary snapshot, syncs it, atomically publishes it, then crash-safely resets the now redundant log. Its authenticated watermark makes either side of a crash reopenable without double-applying or skipping commits. This is O(graph) CPU and I/O by design. It is suitable for the small system database and databases explicitly switched to resident mode; large user graphs should use hybrid mode so routine maintenance cannot become a growing full-snapshot pause.

Both durable engines auto-checkpoint when the active segment reaches 64 MiB by default. The server checks only after a successful updating statement and at a safe statement boundary. GDB_CHECKPOINT_THRESHOLD=0 disables the automatic trigger.

Server configuration · Commit durability and recovery · Backup, restore and transfer