Resident and hybrid storage
Volatile, resident and hybrid databases
Persistence and memory usage are separate choices.
| Mode | Kept in memory | Persistent storage | Typical use |
|---|---|---|---|
| Volatile | The whole graph and indexes | None | Disposable tests |
| Durable resident | The whole graph and indexes | Commit log and full checkpoints | Small, latency-sensitive catalogues |
| Durable hybrid | Topology, indexes and a bounded property cache | Commit log with properties read on demand | Large property-rich graphs |
The database image writes to /data/gdb by default. Mount a volume at /data
to retain that data when the container is recreated. The system database
starts in resident mode; user databases start in hybrid mode.
Both durable modes provide the same Cypher behaviour. They differ in property placement and checkpoint cost. A database remembers a successful mode change.
Changing a live database's engine
Run one administration statement at a time in Explorer or a driver's auto-commit session:
ALTER DATABASE analytics SET ENGINE HYBRID;
ALTER DATABASE analytics SET ENGINE RESIDENT;
SHOW DATABASES;
A switch waits for existing work on that database and blocks new work there until it finishes. Other databases can continue running. The statement cannot run inside an explicit transaction.
Switching to resident mode loads all properties into memory, so allow enough RAM for the complete property set. Conversion work grows with the number of properties. Volatile databases always remain resident.
RAM and disk behaviour
Hybrid storage keeps graph topology, adjacency, property locations and indexes in memory. Only base property values move behind a bounded cache; it is not a fully disk-paged database.
Size memory for the graph structure, indexes, query results and GDS projections as well as the property cache. Indexed values may remain in memory even when their base property value is not cached.
Hybrid checkpoints seal the active log and incrementally reclaim stale property values. Resident checkpoints write a full snapshot. See checkpointing when planning maintenance on a large graph.
Configuration
Set these values in your Compose service's environment:
environment:
GDB_DATA: /data/gdb
GDB_DURABILITY: group
GDB_PROPERTY_CACHE_BYTES: 33554432
GDB_CHECKPOINT_THRESHOLD: 67108864
This selects group commit, a 32 MiB property cache per hybrid database and a 64 MiB active-log checkpoint trigger. The cache budget counts encoded record bytes; actual decoded memory use can be higher.
GDB_PROPERTY_CACHE_BYTES=0 disables the property cache.
GDB_CHECKPOINT_THRESHOLD=0 disables automatic checkpointing.
Configure the remaining service settings using the Docker example.