Data durability and backup
Memgraph uses two mechanisms to ensure the durability of stored data and make disaster recovery possible:
- write-ahead logging (WAL)
- periodic snapshot creation
These mechanisms generate durability files and save them in the respective
wal
and snapshots
folders in the data directory. Data directory stores
permanent data on-disk.
The default data directory path is /var/lib/memgraph
but the path can be
changed by modifying the data-dir
configuration
flag.
If you are using a multi-tenant architecture, the data_directory
also houses
databases within /data_directory/databases/*db_name*
.
Durability files are deleted when certain events are triggered, for example,
exceeding the maximum number of snapshots, defined by the
--storage-snapshot-retention-count=3
flag.
To prevent the deletion of durability files, you need to lock the data directory
, and enable it again by unlocking the directory.
To manage this behavior, use the following queries:
LOCK DATA DIRECTORY;
UNLOCK DATA DIRECTORY;
To show the status of the data directory, run:
DATA DIRECTORY LOCK STATUS;
To encrypt the data directory, use LUKS (opens in a new tab) as it works with Memgraph out of the box and is undetectable from the applications perspective so it shouldn't break any existing applications.
Durability mechanisms
To configure the durability mechanisms check their respective configuration flags in the configuration settings.
Write-ahead logging
Write-ahead logging (WAL) is a technique applied in providing atomicity and durability to database systems.
In the default IN_MEMORY_TRANSACTIONAL storage
mode, Memgraph creates a
Delta
object each time data is changed. By using Deltas, Memgraph creates
write-ahead logs. Each database modification is therefore recorded in a log file
before being written to the DB, and in the end the log file contains all steps
needed to reconstruct the DB’s most recent state.
Memgraph has WAL enabled by default. To switch it on and off, use the boolean
--storage-wal-enabled
flag. For other WAL-related flags check the configuration
reference guide.
WAL files are usually located at /var/lib/memgraph/wal
.
Snapshots
Snapshots provide a faster way to restore the states of your database. Snapshots
are created periodically based on the value defined with the
--storage-snapshot-interval-sec
configuration flag, as well as upon exit based
on the value of the --storage-snapshot-on-exit
configuration flag. When a
snapshot creation is triggered, the entire data storage is written to the drive.
Nodes and relationships are divided into groups called batches.
On startup, the database state is recovered from the most recent snapshot file. Memgraph can read the data and build the indexes on multiple threads, using batches as a parallelization unit: each thread will recover one batch at a time until there are no unhandled batches.
This means the same batch size might not be suitable for every dataset. A smaller dataset might require a smaller batch size to utilize a multi-threaded processor, while bigger datasets might use bigger batches to minimize the synchronization between the worker threads. Therefore the size of batches and the number of used threads are configurable similarly to other durability related settings.
The timestamp of the snapshot is compared with the latest update recorded in the WAL file and, if the snapshot is less recent, the state of the DB will be recovered using the WAL file.
Memgraph has snapshot creation enabled by default. You can configure the exact snapshot creation behavior by defining the relevant flags. Alternatively, you can make one directly by running the following query:
CREATE SNAPSHOT;
Snapshot files are saved inside the snapshots
directory located in the data directory
(var/lib/memgraph
).
Snapshots and WAL files are presently not compatible between Memgraph versions.
Create backup
Follow these steps to create database backup:
Create a snapshot
If necessary, create a snapshot of the current database state by running the
following query in mgconsole
or Memgraph Lab:
CREATE SNAPSHOT;
The snapshot is saved in the snapshots
directory of the data directory
(/var/lib/memgraph
).
Lock the data directory
Durability files are deleted when an event is triggered, for example, exceeding the maximum number of snapshots.
To disable this behavior, run the following query in mgconsole
or Memgraph
Lab:
LOCK DATA DIRECTORY;
Copy files
Copy snapshot files (from the snapshots
directory) and any additional WAL
files (from the wal
directory) to a backup location.
If you've just created a snapshot file there is no need to backup WAL files.
To copy the snapshot files from the Docker container first check the container
ID by running docker ps
then run the following command:
docker cp <CONTAINER ID>:/var/lib/memgraph/<snapshot_file> <snapshot_file>
Unlock the data directory
Run the following query in mgconsole
or Memgraph Lab to unlock the
directory:
UNLOCK DATA DIRECTORY;
Memgraph will delete the files which should have been deleted before locking and allow any future deletion of the durability files.
Restore data
Follow these steps to restore data from a backup:
Empty the `wal` directory
If you want to restore data only from the snapshot file, ensure that the
wal
directory is empty:
- Find the container ID using a
docker ps
command, then enter the container using:
docker exec -it CONTAINER_ID bash
- Position yourself in the
/var/lib/memgraph/wal
directory andrm *
Stop the instance
Run the following command
docker stop CONTAINER_ID
Start the instance
You can start the instance with the backed up files in two ways.
Option 1
You can start the instance by adding a -v ~/snapshots:/var/lib/memgraph/snapshots
flag to the docker run
command,
where the ~/snapshots
represents a path to the location of the directory
with the back-up snapshot, for example:
docker run -p 7687:7687 -p 7444:7444 -v ~/snapshots:/var/lib/memgraph/snapshots memgraph/memgraph
If you want to copy both WAL and snapshot files start the instance by adding
a -v ~/snapshots:/var/lib/memgraph/snapshots -v ~/wal:/var/lib/memgraph/wal
flags to the docker run
command, where the ~/snapshots
represents a path
to the location of the backed-up snapshot directory, and ~/wal
represents a
path to the location of the backed-up wal directory for example:
docker run -p 7687:7687 -p 7444:7444 -v ~/snapshots:/var/lib/memgraph/snapshots -v ~/wal:/var/lib/memgraph/wal memgraph/memgraph
Option 2
The other option is to copy the backed-up snapshot file into the snapshots
directory after creating the container and start the database. So the commands
should look like this:
docker create -p 7687:7687 -p 7444:7444 -v `snapshots`:/var/lib/memgraph/snapshots --name memgraphDB memgraph/memgraph
tar -cf - sample_snapshot_file | docker cp -a - memgraphDB:/var/lib/memgraph/snapshots
The sample_snapshot_file
is the snapshot file you want to use to restore the
data. Due to the nature of Docker file ownership, you need to use tar
to
copy the file as STDIN into the non-running container. It will allow you to
change the ownership of the file to the memgraph
user inside the container.
After that, start the database with:
docker start -a memgraphDB
The -a
flag is used to attach to the container's output so you can see the logs.
Once memgraph is started, change the snapshot directory ownership to the memgraph
user by running the following command:
docker exec -it -u 0 memgraphDB bash -c "chown memgraph:memgraph /var/lib/memgraph/snasphots"
Otherwise, Memgraph will not be able to write the future snapshot files and will fail.
Database dump
The database dump contains a record of the database state in the form of Cypher queries. It’s equivalent to the SQL dump in relational DBs.
You can run the queries constituting the dump to recreate the state of the DB as it was at the time of the dump.
To dump the Memgraph DB, run the following query:
DUMP DATABASE;
If you are using Memgraph Lab, you can dump the database, that is, the queries
to recreate it, to a CYPHERL file in the Import & Export
section of the Lab.
Storage modes
Memgraph has the option to work in IN_MEMORY_ANALYTICAL
,
IN_MEMORY_TRANSACTIONAL
or ON_DISK_TRANSACTIONAL
storage
modes.
Memgraph always starts in the IN_MEMORY_TRANSACTIONAL
mode in which it creates
periodic snapshots and write-ahead logging as durability mechanisms, and also
enables creating manual snapshots.
In the IN_MEMORY_ANALYTICAL
mode, Memgraph offers no periodic snapshots and
write-ahead logging. Users can create a snapshot with the CREATE SNAPSHOT;
Cypher query. During the process of snapshot creation, other transactions will
be prevented from starting until the snapshot creation is completed.
In the ON_DISK_TRANSACTIONAL
mode, durability is supported by RocksDB since it
keeps its own
WAL (opens in a new tab) files.
Memgraph persists the metadata used in the implementation of the on-disk
storage.