mariadb-backup-s3 - Automate MariaDB Backups to S3

Powerful Features for Modern Infrastructure

🔄

Flexible Scheduling

Run on-demand, integrate with cron or systemd timers, or use the built-in scheduler daemon for fully automated backup schedules.

☁️

Multi-Storage Support

Supports S3-compatible providers, including AWS S3, MinIO, and DigitalOcean Spaces, plus FTP and local filesystem storage.

🐳

Docker Ready

Deploy as a Docker container or sidecar.

🗂️

Smart Retention

Intelligent backup rotation with configurable retention policies to optimize storage costs.

⚙️

Simple Configuration

Environment variable-based configuration. No complex config files or learning curves.

📁

Physical Backups

Uses mariabackup for high-performance, hot backups with direct filesystem access to MariaDB data directory for maximum reliability and speed.

🗄️

Logical Backups

Uses mariadb-dump to export each database as a separate .sql file. No filesystem access required - ideal for containerized and managed deployments.

⏰

Built-in Scheduler

Cron-compatible scheduler daemon with YAML configuration, persistent state, and CloudEvents webhook notifications - no external cron or systemd timers needed.

🔒

End-to-End Encryption

Secure your backups with AES-256-GCM encryption. Protect sensitive data with industry-standard encryption that ensures confidentiality even if storage is compromised.

📝

Comprehensive Logging

Detailed, structured logging with both human-readable and JSON formats. Configure log levels and integrate with your existing monitoring systems for complete visibility into backup operations.

Physical vs Logical Backups

Two backup methods for different deployment scenarios

⚖️

Two Backup Methods

mariadb-backup-s3 supports two methods: physical (mariadb-backup, the default) which copies database files at the storage engine level, and logical (mariadb-dump) which exports each database as a separate .sql file. Select the method with MARIADB__BACKUP_METHOD.

📁

Physical: Filesystem Access

mariabackup performs hot backups - it can backup your database while it's running without significant performance impact. This requires direct, read-only access to the MariaDB data files located in /var/lib/mysql.

🗄️

Logical: No Filesystem Access

mariadb-dump exports SQL dumps over the network using the mariadb client to list databases. No filesystem access is required, making it ideal for containerized and managed deployments - at the cost of per-database consistency and slower restores.

🔒

Security Considerations

Physical backups need read access to database files, but never write access. Logical backups only need database credentials. Both allow secure, least-privilege configurations where backup users have minimal permissions.

Get Started in Minutes

Choose your preferred deployment method and start backing up your MariaDB databases immediately.

docker-compose.yml

version: '3.8'
services:
  db:
    image: mariadb:lts
    environment:
      - MARIADB_ROOT_PASSWORD=your-db-password
      - MARIADB_AUTO_UPGRADE
    healthcheck:
      test:
        [
          "CMD",
          "healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized"
        ]
      timeout: 5s
      retries: 10
    volumes:
      - mariadb-data:/var/lib/mysql

  db-backup:
    image: ghcr.io/capcom6/mariadb-backup-s3:latest
    environment:
      - MARIADB__HOST=db
      - MARIADB__USER=root
      - MARIADB__PASSWORD=your-db-password
      - MARIADB__BACKUP_OPTIONS=--skip-ssl --parallel=4
      - STORAGE__URL=s3://your-bucket/backups
      - AWS_ACCESS_KEY_ID=your-access-key
      - AWS_SECRET_ACCESS_KEY=your-secret-key
      - AWS_REGION=us-east-1
      - RETENTION__COUNT=30
    volumes:
      - mariadb-data:/var/lib/mysql
    deploy:
      replicas: 0
      labels:
        - "swarm.cronjob.enable=true"
        - "swarm.cronjob.schedule=@daily"
        - "swarm.cronjob.skip-running=true"
      restart_policy:
        condition: none

  cronjob:
    image: ghcr.io/crazy-max/swarm-cronjob:latest
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    environment:
      - "TZ=UTC"
      - "LOG_LEVEL=info"
      - "LOG_JSON=true"
    deploy:
      replicas: 1

volumes:
  mariadb-data:

Deploy with docker stack deploy -c docker-compose.yml mariadb for automated daily backups!

Installation & Setup

# Download and install the binary
wget https://github.com/capcom6/mariadb-backup-s3/releases/latest/download/mariadb-backup-s3_Linux_x86_64.tar.gz
tar -xzf mariadb-backup-s3_Linux_x86_64.tar.gz
sudo install -m 0755 mariadb-backup-s3 /usr/local/bin/

# Create backup user
sudo useradd -r -s /usr/sbin/nologin backup-user
sudo mkdir -p /var/backups/mariadb
sudo chown backup-user:backup-user /var/backups/mariadb

# Create configuration file
sudo tee /etc/default/mariadb-backup-s3 > /dev/null << EOF
MARIADB__HOST=localhost
MARIADB__USER=backup_user
MARIADB__PASSWORD=secure_password
MARIADB__BACKUP_OPTIONS=--skip-ssl --parallel=4
STORAGE__URL=s3://your-bucket/backups
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1
RETENTION__COUNT=30
EOF
sudo chmod 600 /etc/default/mariadb-backup-s3

# Create systemd service
sudo tee /etc/systemd/system/mariadb-backup-s3.service > /dev/null << EOF
[Unit]
Description=MariaDB Backup to S3
After=network.target

[Service]
Type=oneshot
EnvironmentFile=/etc/default/mariadb-backup-s3
ExecStart=/usr/local/bin/mariadb-backup-s3
User=backup-user
Group=backup-user
SupplementaryGroups=mysql
UMask=0077
TimeoutStartSec=2h

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
PrivateTmp=yes
PrivateDevices=yes
ProtectHome=tmpfs
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
MemoryDenyWriteExecute=yes
LockPersonality=yes
ReadWritePaths=/var/backups/mariadb
EOF

# Create systemd timer
sudo tee /etc/systemd/system/mariadb-backup-s3.timer > /dev/null << EOF
[Unit]
Description=Run mariadb-backup-s3 daily at 2:30 AM

[Timer]
Unit=mariadb-backup-s3.service
OnCalendar=*-*-* 02:30:00
Persistent=true
AccuracySec=5m
RandomizedDelaySec=30m

[Install]
WantedBy=timers.target
EOF

# Enable and start the timer
sudo systemctl daemon-reload
sudo systemctl enable --now mariadb-backup-s3.timer

Your automated daily backups are now scheduled! Check status with systemctl list-timers mariadb-backup-s3.timer

⚠️ Important: The backup user needs filesystem access to the MariaDB data directory (/var/lib/mysql) for mariabackup to function properly. Ensure the backup user has appropriate read permissions to the MariaDB data files.

Flexible Configuration Options

Customize backup behavior with simple environment variables

Database Settings

MARIADB__HOST MariaDB server hostname

MARIADB__PORT Database port (default: 3306)

MARIADB__USER Database username with backup privileges

MARIADB__PASSWORD Database password

MARIADB__BACKUP_METHOD Backup method: mariadb-backup (physical) or mariadb-dump (logical)

MARIADB__CLIENT_BINARY mariadb client binary (lists databases for logical backups)

MARIADB__BACKUP_OPTIONS Additional mariabackup options (e.g., --parallel=4)

Storage Configuration

STORAGE__URL Storage URL (e.g., s3://my-bucket/backups, file:///tmp/backups)

AWS_ACCESS_KEY_ID S3 access key ID

AWS_SECRET_ACCESS_KEY S3 secret access key

AWS_REGION S3 region (default: us-east-1)

Backup & Retention Settings

ENCRYPTION__KEY Base64-encoded encryption key for AES-256-GCM

RETENTION__COUNT Maximum number of backups to retain (0 = unlimited)

RETENTION__MAX_AGE Maximum age of backups (e.g., 24h, 168h)

RETENTION__KEEP_DAILY Number of daily backups to keep (0 = disabled)

RETENTION__KEEP_WEEKLY Number of weekly backups to keep (0 = disabled)

RETENTION__KEEP_MONTHLY Number of monthly backups to keep (0 = disabled)

RETENTION__DRY_RUN Preview retention policy without deleting (retention command)

RETENTION__FORCE Continue retention despite errors (retention command)

BACKUP__SKIP_RETENTION Skip retention policy after backup

Restore

RESTORE__TARGET_DIR Target directory to restore to

Scheduler

SCHEDULER__CONFIG Path to scheduler YAML config file

SCHEDULER__STATE_FILE Path to persistent scheduler state file

Logging

LOG_LEVEL Log level (e.g., debug, info, warn, error)

LOG_OUTPUT Log output (e.g., stdout, stderr, file path)

LOG_FORMAT Log format (e.g., json, human)

NO_COLOR Disable color output (default: unset)

Feature	mariadb-backup-s3	mysqldump	Percona XtraBackup	Custom Scripts
S3 Integration	✓ Native	✗ Manual	✗ Manual	✗ Custom
Docker Support	✓ Official image	✗ Manual setup	✓ Official image	✗ Custom
Retention Management	✓ Automatic	✗ Manual	✗ Manual	✗ Custom
Configuration	✓ Environment vars	~ Command line	~ Command line	✗ Complex
Encryption Support	✓ Native	✗ Manual	✓ Native	✗ Custom
Logical Backup Support	✓ Native	✓ Native	✗ Not supported	✗ Custom
Built-in Scheduler	✓ Native	✗ Not included	✗ Not included	✗ Custom

Automate MariaDB Backups to S3 in Minutes

Stop Worrying About Database Backups

Before

After