Checkpointing and compaction

Wiki / Operations

On this page

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.

Compacting a database

CALL gdb.compact() gives back the space dead data holds, as a standalone auto-commit statement with administrative rights. From version 2.1.0.

EngineDoes
PagedPurges dropped tables no snapshot reads, checkpoints, then rewrites every pack that holds a dead page. The replaced packs go at once, and only the live manifest is kept
ResidentCheckpoints: a fresh snapshot and an empty log
HybridCheckpoints until the log stops shrinking; superseded property values go

It yields bytesBefore, bytesAfter and bytesReclaimed, the database directory's size on disk. From version 2.1.4, running it again on a database that has not changed writes nothing, so bytesBefore and bytesAfter match. Paged also keeps itself compact as it runs: a page that a flush leaves under a quarter full is joined with its neighbour, and each flush collects the sparsest packs.

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

Planning a deployment? Review compatibility and licence setup for your instance.