maria
Back up MariaDB with full and incremental snapshots stored in restic on local disk or an rclone remote (such as S3), and list, restore, or mount them on demand
- Command:
/go/maria - Category: Databases
- Required option: None. The first argument is an action (
start,stop,list,refresh,restore,connect). With no argument, it takes a backup. - Output: Plain text progress messages
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/maria backs up every MariaDB database on the server at once, using mariadb-backup and restic. It:
- takes one full backup, then incremental backups against it, so later runs are fast and small
- compresses the backup and uses half of the server's CPU threads (at least one)
- stores each run as a restic snapshot, either in an rclone remote (S3, MinIO, and others) or in
/backup/mariaon this server - lists snapshots, and restores any of them over the live data directory
- mounts a snapshot as a second, read-write MariaDB instance on port
3307, so you can inspect or copy data without touching the live server
This command backs up the database server only. For hosting accounts (files, mail, settings), use backup or snapshot.
Quick start
# 1. Turn on scheduled backups (creates /var/go/etc/maria.conf)
/go/maria start
# 2. Take a backup now
/go/maria
# 3. See your snapshots
/go/maria list
Syntax
/go/maria [action] [snapshot] [--force]
| Form | Behavior |
|---|---|
/go/maria |
Take a full backup if none exists, otherwise an incremental backup. |
/go/maria start |
Create /var/go/etc/maria.conf with the default schedule, if it doesn't exist. |
/go/maria stop |
Disable scheduled backups by renaming maria.conf to maria.bak. |
/go/maria list |
List the snapshots in the backup destination. |
/go/maria refresh |
Delete the local full and incremental backups, then take a new full backup. |
/go/maria restore [snapshot] [--force] |
Restore a snapshot into /var/lib/mysql and restart MariaDB. |
/go/maria connect [snapshot] |
Restore a snapshot into a separate data directory and start a second MariaDB instance on port 3307. |
[snapshot] is either a tag or a restic snapshot ID. See Snapshot tags.
The command needs the server hostname to contain at least two dots (for example server.example.com). Otherwise it stops immediately.
Options
Actions and flags
| Argument | Used with | Default | Notes |
|---|---|---|---|
start |
— | — | Does nothing if maria.conf already exists. |
stop |
— | — | Replaces any earlier maria.bak. |
list |
— | — | Same as restic snapshots on the destination. |
refresh |
— | — | Forces a new full backup. The local backup chain is deleted first. |
restore |
— | — | Fails if /var/lib/mysql already contains data, unless you pass --force. |
connect |
— | — | Erases the data directory of the earlier connect instance and ends anything listening on port 3307. |
<snapshot> |
restore, connect |
Backup files already in Dir |
A tag or snapshot ID. If omitted, the backup files already on disk are used. |
--force |
restore |
Off | Stops MariaDB and deletes everything in /var/lib/mysql before restoring. |
Settings file: /var/go/etc/maria.conf
All backup actions need this file. start creates it.
| Setting | Default | Notes |
|---|---|---|
Cron |
"0 12,16,20 * * *" |
Written by start. Backups run at 12:00, 16:00, and 20:00 daily. The script itself does not read this value. |
Dir |
/maria |
Local working folder for the backup files. If you set it, the folder must already exist. |
RemoteDir |
maria |
Folder in the remote destination. A leading / is removed. |
Example:
Cron="0 12,16,20 * * *"
Dir="/maria"
RemoteDir="maria"
Backup destination
The destination is chosen automatically from /root/.config/rclone/rclone.conf:
| rclone remote found | Destination |
|---|---|
[maria] |
maria:<RemoteDir>/<hostname> |
[backup] (and no [maria]) |
backup:<RemoteDir>/<hostname> |
| Neither | /backup/maria on this server (no hostname subfolder) |
Output
The command prints short progress lines. There is no JSON output.
| Message | Meaning |
|---|---|
Taking Full Backup... |
No full backup exists locally, so one is being taken. |
Restic Full Backup: <destination>... |
The full backup is being sent to the destination. |
Taking Incremental Backup... |
A full backup already exists, so only changes since it are being taken. |
Restic Incremental Backup: <destination>... |
The incremental backup is being sent to the destination. |
Restoring Restic TAG <tag>... |
The snapshot argument matched a tag. |
Restoring Restic ID <id>... |
The snapshot argument matched a snapshot ID. |
Restoring MariaDB Backup... |
The backup files are being prepared and copied back. |
mariadb --port=3307 |
Printed by connect. Run it to open the second instance. |
Instance (maria) already running. |
Another run started less than an hour ago. |
Invalid Server Hostname <hostname>, ... |
The hostname has fewer than two dots. |
File /var/go/etc/maria.conf not Exists. |
Scheduled backups were never started (or were stopped). |
Folder <Dir> not Exists. |
Dir in maria.conf points to a missing folder. |
Directory /var/lib/mysql is not empty. |
restore refused to overwrite existing data. |
Archive <snapshot> does not exist |
No tag or ID matched. The snapshot list is printed after it. |
[!NOTE] Most actions end with exit status
1, even when they work (start,stop,list,restore,connect, and full backups). Only an incremental backup ends with0. In scripts, read the output instead of relying on the exit status.
Security
[!WARNING] Restic encrypts snapshots with a fixed password built into the script. That password is the same on every server, so the encryption does not protect your data from anyone who can read the repository and knows the default. Restrict access to the remote bucket or to
/backup/maria. The MariaDB root password is also passed tomariadb-backupon its command line, so it is briefly visible in the process list while a backup runs.
Examples
# Take a backup (full the first time, incremental afterwards)
/go/maria
# Start over with a fresh full backup, for example after switching destination
/go/maria refresh
# List the available snapshots
/go/maria list
# Restore the latest snapshot taken at 20:00 over the live databases
/go/maria restore 20 --force
# Restore a specific snapshot by its ID
/go/maria restore a1b2c3d4 --force
# Inspect the 12:00 snapshot without touching live data
/go/maria connect 12
mariadb --port=3307
# Stop scheduled backups
/go/maria stop
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Instance (maria) already running. |
A backup started less than an hour ago and hasn't finished. | Wait. If nothing is running, delete /usr/local/goadmio/lock/maria.lock. A lock older than an hour is ignored automatically. |
Invalid Server Hostname |
The hostname has fewer than two dots. | Set a full hostname with hostname. |
File /var/go/etc/maria.conf not Exists. |
Backups were never enabled, or stop was run. |
Run /go/maria start. |
Folder <Dir> not Exists. |
Dir in maria.conf points to a missing folder. |
Create the folder, or fix Dir. |
| Backups land on local disk, not the remote | No [maria] or [backup] remote in rclone.conf. |
Add a remote with one of those names, then run /go/maria refresh. |
| Incremental runs fail after changing the remote | The restic repository is only created during a full backup, and the new destination has none. | Run /go/maria refresh. |
Directory /var/lib/mysql is not empty. |
restore won't overwrite live data by default. |
Add --force if you are sure. This deletes the current databases. |
Archive <snapshot> does not exist |
The argument is not a known tag or snapshot ID. | Run /go/maria list and copy a tag or ID. |
| Restoring a tag gave older data than expected | A tag is the hour of the day, and restic uses the newest snapshot with that tag. | Use the snapshot ID from list for an exact point in time. |
| Disk fills up | Local backup files stay on disk, and with local storage the restic repository is on disk too. | Use a remote, or free space with clean. |
| Script reports failure though the output looks fine | Most actions exit with status 1. |
Check the output messages, not the exit status. |
Details
What a backup run does
flowchart TD
A["maria"] --> B{"Lock younger than 1 hour?"}
B -- "Yes" --> X1["Instance already running, exit"]
B -- "No" --> C{"Hostname has 2+ dots<br/>and maria.conf exists?"}
C -- "No" --> X2["Error, exit"]
C -- "Yes" --> D{"Full backup exists locally?"}
D -- "No" --> E["mariadb-backup full + compress"]
E --> F["restic init, forget, prune"]
F --> G["restic backup, tagged with the hour"]
D -- "Yes" --> H["mariadb-backup incremental<br/>against the full backup"]
H --> G
G --> I["Release lock"]
- Writes the command and its arguments to
/var/log/go/maria.log. - Takes a lock in
/usr/local/goadmio/lock/maria.lock. The lock is released when the command ends, even if you press Ctrl+C. - Checks the hostname, reads
maria.conf, and picks the destination. - Raises the open-files limit and enables
io_uring, whichmariadb-backupuses. - Takes the backup (see below) and sends the whole
Dirfolder to restic, tagged with the current hour.
Full backup
Taken when <Dir>/<hostname>/full/mysql doesn't exist locally, such as on the first run or after refresh. After the backup, it:
- creates the restic repository (
restic init; an "already exists" message is harmless) - removes old snapshots and prunes the repository, then sends the new snapshot
Incremental backup
Taken on every later run. The previous incremental backup is deleted, and the new one is taken against the full backup, not against the previous incremental. So each incremental grows until the next full backup, but a restore needs only the full backup plus the latest incremental.
Retention
| Rule | Keeps |
|---|---|
--keep-within 24h |
Every snapshot from the last 24 hours |
--keep-daily 7 |
One snapshot per day for 7 days |
--keep-weekly 4 |
One snapshot per week for 4 weeks |
--keep-monthly 12 |
One snapshot per month for 12 months |
[!NOTE] Old snapshots are removed only when a full backup is taken (the first run, or after
refresh). Incremental runs never prune. If you rarely runrefresh, snapshots keep accumulating. Running/go/maria refreshnow and then (for example monthly) keeps the repository tidy and resets the growing incremental.
Snapshot tags
Each snapshot is tagged with the hour (00 to 23) at which it was taken. With the default schedule, the tags in use are 12, 16, and 20.
When you pass a snapshot to restore or connect, the command first looks for a matching tag and restores the latest snapshot that has it. If there is no tag match, it tries the argument as a snapshot ID.
How restore works
- If
--forcewas passed, stops MariaDB and deletes/var/lib/mysql/*. - If
/var/lib/mysqlstill holds data, printsDirectory /var/lib/mysql is not empty.and stops. - If a snapshot was given, deletes the local
Dirfolder and restores the snapshot into it. Without a snapshot, the backup files already inDirare used. - Stops MariaDB, then decompresses and prepares the full backup. If an incremental backup exists, it is decompressed and applied on top.
- Copies the result into
/var/lib/mysql, fixes ownership, and restarts MariaDB.
How connect works
connect follows the same steps as restore, with these differences:
- It uses
/var/go/var/lib/mysqlas the data directory, and the live databases are not touched. - Before restoring, it runs
/go/mysql system, ends any process listening on port3307, and deletes the old contents of that data directory. - After restoring, it starts a second MariaDB with
/var/go/etc/my.cnf, waits 10 seconds, and sets its root password to the same value as the live server's. - It prints
mariadb --port=3307.
The second instance keeps running until you stop it. To discard it, end the process on port 3307.
See also
| Command | Description |
|---|---|
backup |
Back up one or all GoAdmio accounts to local disk or remote storage, manually or on a schedule |
snapshot |
Back up, list, check, restore, and delete restic snapshots of hosting accounts, locally or on remote storage |
restore |
Restore accounts, databases, SSL certificates, or folders from local or remote GoAdmio backups |
mysqlbackup |
Back up MariaDB/MySQL to a remote server via rsync |
cron |
Rebuild GoAdmio's cron jobs, server-wide or for one domain, and restart or stop the cron service |
s3 |
Mount an S3 bucket on a GoAdmio server |
installmariadb |
Install or upgrade MariaDB from the official repositories (default version 12.3, or a version you choose) and apply basic hardening |
my |
Regenerate the MariaDB configuration file with settings tuned to the server's RAM, CPU, and database usage, then restart MariaDB |