Skip to content

7. Important Considerations

Please Read

These considerations are provided to help you evaluate the suitability of docker-mariadb-snapshot for your specific environment and requirements, not to scare you away from using it.

This tool has succesfully been used in production with mid-scale (1M+ rows) deployments, but every environment is different.

docker-mariadb-snapshot may not be suitable for all environments. It is designed to be reliable, simple and easy to use. It may not meet all requirements or constraints in every scenario.

Please ensure that you audit this package and understand its limitations before deploying it in your specific environment. Some of the considerations you may want to review before deploying this package in production include:

7.1 Testing Snapshot Restorations

Always test restoration procedures immediately after scheduling and performing the first snapshots.

  • Test in a non-production environment.
  • Verify the snapshot integrity and compatibility with your target server version by performing the restoration as if you were in a data-loss situation.

If possible, automate periodic restoration tests to ensure ongoing snapshot integrity.

7.2 Sensitive Data

Database snapshots may contain sensitive, personal, or confidential data. Snapshots are plain-text and, unless encrypted separately, insecure by default. Ensure that snapshot files are stored securely and access is restricted.

7.3 Non-Default rsnapshot Configuration

docker-mariadb-snapshot sets the sync_first 1 rsnapshot configuration item and uses rsnapshot's standard rotation hierarchy. Only the lowest retained level snapshots the live data; higher levels promote the oldest snapshot of the level below and never connect to the database. Any level that is retained but not scheduled must have its retention set to 0, or nothing is ever promoted. See the Understanding the RSnapshot Configuration document for more details.

7.4 Container Restart Policies

The image ENTRYPOINT returns a non-zero exit code if any part of the snapshot process fails, even if only one database in many fails, so the orchestration system sees the failure.

When the snapshot script fails, rsnapshot rolls the run back: .sync is restored from the newest snapshot of the lowest level, discarding every file from that run, including the databases that did dump successfully. The image then exits without rotating, so a failed run leaves the existing snapshots exactly as they were. (Before 2026-10-30 the image ignored this failure, exited zero and rotated anyway, which copied the previous snapshot into a new generation and pushed the oldest distinct one out.)

A consequence: a failure that repeats every run freezes your snapshots at the last good one, while every run reports failure. Watch the exit status of every run. A container restart policy like always or on-failure only repeats the failure and adds load to the server.

Although all examples within this documentation set docker-mariadb-snapshot restart policy to prevent automatic restarts on failure, it is important to ensure that your orchestration system or container runtime is configured similarly to handle these scenarios appropriately.

7.4.1 Suggested Configurations

7.4.1.1 docker-compose

Setting the restart policy to "no" will prevent automatic restarts:

service:
    [...]
    restart: "no"

7.4.1.2 Kubernetes Cron

Setting the restartPolicy to Never and backoffLimit to 0 in a Job spec will prevent automatic restarts:

    restartPolicy: Never
    backoffLimit: 0

7.5 Snapshot Options

The mariadb-dump utility has many options, however only the following are used to create snapshots:

    --single-transaction
    --quick
    --skip-lock-tables
    --routines
    --events
    --triggers
    --hex-blob
    --default-character-set=${DB_DEFAULT_CHARSET}

7.6 MariaDB Sandbox Mode

Recent versions of mariadb-dump introduced sandbox mode as a security feature and now prepend a special directive at the top of every dump file:

/*!999999- enable the sandbox mode */

The change was introduced as a mitigation for CVE-2024-21096. Sandbox mode blocks those dangerous client commands, but it also has a side effect: older MariaDB clients and all MySQL clients do not understand the \- sandbox command and fail with errors like ERROR at line 1: Unknown command '\-' when they encounter this directive. For more details, see MariaDB’s announcement “MariaDB Dump File Compatibility Change.

docker-mariadb-snapshot strips this line by default from all dump files after they are created to maintain compatibility with older MariaDB clients and MySQL clients. If you want to retain this line in your dumps, set the environment variable STRIP_SANDBOX_MODE_COMMENT to false.

7.7 Snapshot Consistency and Atomic State

7.7.1 Overview

The combination of --single-transaction and --skip-lock-tables provides point-in-time consistency for InnoDB tables only. Generally, this is likely 'good enough' for many applications using InnoDB as the primary storage engine. Non-transactional storage engines (MyISAM, MEMORY, etc.) are not locked and may be captured in an inconsistent state if modified during snapshot.

For more detailed information about consistency, storage engine implications, cross-engine consistency issues, and how to audit your database, see the Snapshot Consistency and Atomic State guide.

7.8 High Confidence Snapshot Consistency

For high-reliability snapshots, a MariaDB/MySQL server should be placed into a read-only state before the snapshot is taken.

How to do so is outside the scope of this documentation, and depends on your specific environment and setup.

Good starting points: