# Checkpointing and compaction

[Wiki](../README.md) / [Operations](README.md)

**On this page**

- [Checkpoint policies](#checkpoint-policies)
  - [Hybrid: seal and compact](#hybrid-seal-and-compact)
  - [Stale-property compaction](#stale-property-compaction)
  - [Resident: snapshot and reset](#resident-snapshot-and-reset)
- [Compacting a database](#compacting-a-database)

## Checkpoint policies

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

```cypher
CALL gdb.checkpoint();
```

The selected storage mode determines the maintenance work. See
[maintenance calls](backups.md) 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.

| Engine | Does |
|---|---|
| Paged | Purges 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 |
| Resident | Checkpoints: a fresh snapshot and an empty log |
| Hybrid | Checkpoints 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.

## Related articles

[Server configuration](configuration.md) · [Commit durability and recovery](durability.md) · [Backup, restore and transfer](backups.md)
