Backup and Restore#
MuduDB provides two backup mechanisms:
Base backup + WAL archiving — physical snapshots of every worker at a committed point, plus continuously archived WAL chunks for point-in-time recovery (PITR).
Logical dump — a portable full-database export (schema plus per-table CSV) packaged as a ZIP archive.
Base backups and logical dumps run on the live server through the HTTP management endpoint. restore and pitr are offline commands that build a new data directory locally without contacting the server.
Configuration#
Backup is configured through the optional [backup] section of mudud.cfg. When the section is absent the server runs backup-free: WAL prefix GC reclaims chunks without archiving them.
[backup]
backup_dir = "./backup" # base backups are written here
archive_dir = "./wal-archive" # sealed WAL chunks are archived here
archive_mode = "on" # "off", "on" (default), or "always"
Field |
Type |
Default |
Description |
|---|---|---|---|
|
string |
unset |
Directory base backups are written to; required by the |
|
string |
unset |
Directory sealed WAL chunks are continuously archived to. |
|
string |
|
|
When archiving is active, WAL prefix GC only reclaims a chunk after it has been durably archived. Archiving runs independently of replication, so single-node deployments archive too.
Taking a base backup#
mcli --http-addr 127.0.0.1:8300 backup create --label daily-1
The server force-flushes each worker’s WAL, snapshots every worker at its committed point, and copies the snapshots under <backup_dir>/<label>/. The BACKUP_LABEL file is written last: a backup counts as valid only once its label decodes and every referenced snapshot is complete.
List, verify, and delete backups:
mcli --http-addr 127.0.0.1:8300 backup list
mcli --http-addr 127.0.0.1:8300 backup verify --label daily-1
mcli --http-addr 127.0.0.1:8300 backup delete --label daily-1
backup list returns the labels of every valid backup under backup_dir. backup verify decodes the label and checks every referenced snapshot file against its manifest (length and CRC64); a missing or corrupt backup fails with an error. backup delete removes <backup_dir>/<label>/.
All four commands require [backup] backup_dir; without it the server answers backup is not configured: [backup] backup_dir is missing.
Restoring a base backup (offline)#
mcli restore --label daily-1 --backup-dir ./backup --archive-dir ./wal-archive --target-dir ./restored
restore rebuilds a complete data directory under --target-dir: it installs the base backup’s relation files and key/value state, then replays the archived WAL forward to the end of the archive. --backup-dir and --archive-dir are the directories [backup] backup_dir and archive_dir were configured with. A server can then be started with db_path pointing at the target directory.
Point-in-time recovery (offline)#
mcli pitr --label daily-1 --backup-dir ./backup --archive-dir ./wal-archive --target-dir ./recovered --time 1700000000000
pitr works like restore but stops at a target point. Exactly one of the following is required:
--lsn <N>— stop before the given LSN.--time <ms>— stop after the last commit whose timestamp is at or before the given milliseconds since the epoch.--xid <N>— stop after the commit of the given transaction id.
If no commit in the archive satisfies a --time or --xid target, the command fails with no commit in the archive satisfies the recovery target.
Logical dump and restore#
mcli --http-addr 127.0.0.1:8300 dump --label daily-1 --dir /dumps
Writes a self-contained ZIP archive <dir>/<label>.zip on the server (--dir is a server-side path). The archive contains the catalog metadata (manifest.mp, schema.mp), a human-readable schema.sql, and one CSV per table under data/ (CSV encoding is identical to the SQL COPY surface). Partitioned tables contribute metadata only; their data is not dumped.
mcli --http-addr 127.0.0.1:8300 restore-logical --label daily-1 --dir /dumps
mcli --http-addr 127.0.0.1:8300 restore-logical --label daily-1 --dir /dumps --drop
Restores the schema and reloads the data on the live server. Tables that already exist are skipped by default; pass --drop to drop and recreate same-named tables.
HTTP endpoints#
The mcli commands map to these HTTP management endpoints:
Command |
Endpoint |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Limitations#
Base backup and logical dump require a kernel server mode (
TokioorIOUring). On aLegacyserver the endpoints report errors such asbase backup is not supported.A base backup covers one server.
restoreandpitrrun locally against itsbackup_dirandarchive_dirand do not need a running server.
See the Configuration Reference for all [backup] fields and mcli Management Interface (HTTP) for the full command reference.
WAL archiving from [backup] is wired into the Tokio backend’s worker configuration. The current IOUring startup path does not pass that configuration to workers: its base-backup and logical-dump management endpoints do not imply continuous WAL archiving. Use Tokio for the documented archive/PITR workflow. archive_mode = "always" currently does not gate commit acknowledgements on archive durability.
Filesystem content is stored outside WAL. The current worker snapshot copies relation .dat files and KV state, not the fs/ generation files; logical dumps contain schema and table CSV rather than object-content files. These mechanisms alone therefore do not provide complete replication or recovery of filesystem object content. Preserve and validate that content separately when using FS columns.