mariadb-backup-s3 - Automate MariaDB Backups to S3

Powerful Features for Modern Infrastructure

🔄

Flexible Scheduling

Run on-demand or integrate with cron or systemd timers for automated backup schedules.

☁️

S3-Compatible Storage

Works with AWS S3, MinIO, DigitalOcean Spaces, and any S3-compatible storage provider.

🐳

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.

📁

Filesystem-Level Backups

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

Why Filesystem Access is Required

Understanding the technical requirements for reliable MariaDB backups

📁

mariabackup Technology

mariadb-backup-s3 uses mariabackup, high-performance backup tool for MariaDB. Unlike mysqldump which exports data through SQL queries, mariabackup works at the filesystem level by copying database files directly.

🔄

Hot Backups Without Locking

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

⚡

Performance & Reliability

Direct filesystem access enables faster backups and restores compared to SQL-based methods. This approach ensures data consistency and provides better performance for larger databases.

🔒

Security Considerations

The backup process requires read access to database files, but never needs write access. This allows for 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
      - 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
      - BACKUP__LIMITS__MAX_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
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
BACKUP__LIMITS__MAX_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
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_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 Settings

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

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	~ Config files	✗ Complex

Automate MariaDB Backups to S3 in Minutes

Stop Worrying About Database Backups

Before

After