MariaDB Backup to S3

• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Backup
  • Restore
  • Retention
  • Registry
  • Scheduler
• Storage Types
  • S3 Storage
  • FTP Storage
  • Filesystem Storage
• Encryption
• Examples
• Contributing
• License
• Contact
• Acknowledgments

MariaDB Backup to S3 is a CLI tool that backs up MariaDB databases, compresses them, optionally encrypts them with AES-256-GCM, and uploads to S3-compatible, FTP, or local filesystem storage.

Two backup methods are supported:

Key features:

• Compress backups with pigz (parallel gzip)
• Optional AES-256-GCM client-side encryption
• Multiple storage backends: S3-compatible, FTP, filesystem
• Automatic backup rotation with configurable retention policies
• Backup registry for tracking and managing backups
• Built-in scheduler daemon for automated scheduled backups without external cron
• Docker container support

(back to top)

• Go
• mariadb-backup / mariadb-dump
• AWS SDK for Go v2
• pigz (parallel gzip)

(back to top)

• Go 1.25+ (for building from source)
• MariaDB server with mariadb-backup (for physical) or mariadb-dump (for logical) available in PATH, and mariadb client binary for listing databases (logical backup only)
• pigz in PATH
• tar in PATH
• At least 2x the database size in free temp space
• Storage backend credentials (depending on chosen storage type)

Binary (recommended):

1. Visit the Releases page
2. Download the appropriate binary for your OS
3. Make executable and move to PATH:

   chmod +x mariadb-backup-s3
   sudo mv mariadb-backup-s3 /usr/local/bin/

Go install:

go install github.com/capcom6/mariadb-backup-s3@latest

Docker:

docker pull ghcr.io/capcom6/mariadb-backup-s3:latest

Note The Docker image uses MariaDB's lts version. For specific versions, clone the repo, modify Dockerfile.goreleaser base image, and build a custom image.

From source:

git clone https://github.com/capcom6/mariadb-backup-s3.git
cd mariadb-backup-s3
go build -o mariadb-backup-s3

(back to top)

mariadb-backup-s3 [global options] command [command options] [arguments...]

Configuration is loaded from (highest priority first): CLI flags > environment variables > .env file in the current directory.

mariadb-backup-s3 backup [options]

Options:

Physical backup example:

mariadb-backup-s3 backup \
  --db-host=mariadb.example.com \
  --db-user=backup \
  --storage-url="s3://my-bucket/backups?endpoint=https://s3.eu-west-1.amazonaws.com" \
  --retention-count=14 \
  --keep-daily=7

Logical backup example:

mariadb-backup-s3 backup \
  --backup-method=mariadb-dump \
  --db-host=mariadb.example.com \
  --db-user=backup \
  --storage-url="s3://my-bucket/backups"

By default mariadb-dump locks tables per database using READ LOCAL locks, so concurrent inserts into non-transactional tables (e.g. MyISAM/Aria) may still occur while a table is dumped, and cross-database consistency is not guaranteed. Each database is dumped in a separate invocation, so the generated .sql files are not point-in-time consistent with each other; as a result, logical (mariadb-dump) backups do not provide a global snapshot of all databases. The virtual schemas information_schema and performance_schema are skipped. For non-blocking dumps (InnoDB only), use --db-backup-options="--single-transaction", accepting that non-transactional tables are then not guaranteed consistent.

Environment-only (minimal):

export MARIADB__HOST=localhost
export MARIADB__USER=root
export MARIADB__PASSWORD=secret
export MARIADB__BACKUP_METHOD=mariadb-backup
export STORAGE__URL=s3://my-bucket/backups
export AWS_REGION=eu-west-1
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=yyy
mariadb-backup-s3

(back to top)

mariadb-backup-s3 restore [options] [backup_name.tar.gz | --latest | --backup-id=<id>]

Exactly one backup selector must be specified: a filename argument, --latest, or --backup-id.

Options:

Restore latest backup:

mariadb-backup-s3 restore \
  --storage-url="s3://bucket/path" \
  --target-dir=/var/lib/mysql \
  --latest

Restore by filename or ID:

mariadb-backup-s3 restore --storage-url="s3://bucket/path" \
  --target-dir=/tmp/restore \
  2026-07-03-12-00-00.tar.gz

mariadb-backup-s3 restore --storage-url="s3://bucket/path" \
  --target-dir=/tmp/restore \
  2026-07-03-12-00-00.tar.gz.enc  # .enc suffix for encrypted backups

mariadb-backup-s3 restore --storage-url="s3://bucket/path" \
  --target-dir=/tmp/restore \
  --backup-id="2026-07-03-12-00-00-a1b2c3d4"

Note Logical backups (mariadb-dump) restore by extracting .sql files from the archive. Import them manually:

mariadb-backup-s3 restore --storage-url="s3://bucket/path" --target-dir=/tmp/restore --latest
mariadb -u root -p < /tmp/restore/mydb.sql

(back to top)

Apply retention policies to prune old backups.

mariadb-backup-s3 retention [options]

Options:

Examples:

# Keep only the 7 most recent backups
mariadb-backup-s3 retention \
  --storage-url="s3://my-bucket/backups" \
  --retention-count=7

# Keep backups from the last 7 days
mariadb-backup-s3 retention \
  --storage-url="s3://my-bucket/backups" \
  --max-age=168h

# Keep 1 daily for 7 days, 1 weekly for 4 weeks, 1 monthly for 12 months
mariadb-backup-s3 retention \
  --storage-url="s3://my-bucket/backups" \
  --keep-daily=7 \
  --keep-weekly=4 \
  --keep-monthly=12

# Preview what would be deleted
mariadb-backup-s3 retention \
  --storage-url="s3://my-bucket/backups" \
  --retention-count=3 \
  --dry-run

Note At least one retention policy must be enabled. The retention command will fail if no policies are specified.

(back to top)

View and manage the backup registry.

mariadb-backup-s3 registry list [options]

mariadb-backup-s3 registry list \
  --storage-url="s3://my-bucket/backups"

Registry entry fields:

Note Entries rebuilt with --rebuild use timestamp-only IDs, set sha256 to "unknown", and have an empty tool.method.

(back to top)

Built-in cron daemon that executes backup and retention jobs on a schedule without external cron or systemd timers.

mariadb-backup-s3 scheduler <command> [options]

Subcommands:

Options:

Example scheduler config:

# scheduler.yaml
state_file: /var/lib/mariadb-backup-s3/state.json
jobs:
  - name: nightly-full-backup
    schedule: "0 2 * * *"
    command: backup
    timeout: 4h
    storage:
      url: s3://my-bucket/backups?endpoint=https://s3.custom.com
    mariadb:
      host: localhost
      port: 3306
      user: root
      password: ${MARIADB__PASSWORD}
      backup_method: mariadb-backup
    retention:
      max_count: 7

# Validate the config
mariadb-backup-s3 scheduler check --config scheduler.yaml

# Run the scheduler daemon
mariadb-backup-s3 scheduler run --config scheduler.yaml

# Run all enabled jobs once and exit
mariadb-backup-s3 scheduler run --config scheduler.yaml --once

# Check job status
mariadb-backup-s3 scheduler status --config scheduler.yaml --state-file /var/lib/mariadb-backup-s3/state.json

Note See examples/scheduler for a complete setup guide.

(back to top)

For S3-compatible storage (AWS S3, MinIO, DigitalOcean Spaces, etc.):

STORAGE__URL=s3://bucket-name/path?endpoint=https://s3.example.com

Required environment variables:

Query parameters:

STORAGE__URL=ftp://username:password@host:port/path

Username defaults to anonymous.

STORAGE__URL=file:///absolute/path/to/backup/directory

Examples:

• Linux/macOS: file:///var/backups/mariadb
• Windows: file:///C:/backups/mariadb
• Docker volume: file:///data/backups

(back to top)

Client-side encryption using AES-256-GCM for confidentiality and integrity verification.

Features:

• 256-bit key strength
• Authenticated encryption with associated data (AEAD)
• Automatic nonce generation per backup
• HKDF-SHA256 key derivation

Configuration:

# base64-encoded encryption key
# Replace with a unique value generated by: openssl rand -base64 32
ENCRYPTION__KEY=REPLACE_WITH_A_UNIQUE_BASE64_KEY

Key generation:

# Generate a 32-byte (256-bit) key
openssl rand -base64 32

# Alternative
head -c 32 /dev/urandom | base64

Security considerations:

• Never commit encryption keys to version control
• Store keys in secure environment variables or dedicated secret management systems
• Implement proper access controls for key storage

(back to top)

• systemd Service -- Run as a systemd service
• Docker Swarm CRON -- Scheduled backups in Docker Swarm
• Simple CRON -- Basic cron-based scheduling
• Advanced CRON -- Advanced cron with logging and notifications
• Encryption -- Encrypted backup setup
• Scheduler -- Built-in scheduler daemon

(back to top)

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/amazing-feature)
3. Commit your Changes (git commit -m 'Add amazing feature')
4. Push to the Branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTORS.md for a list of contributors.

(back to top)

Distributed under the Apache 2.0 License. See LICENSE for details.

(back to top)

• Report a bug
• Request a feature
• View all issues

Project Link: https://github.com/capcom6/mariadb-backup-s3

(back to top)

• Choose an Open Source License
• Img Shields
• Best-README-Template

(back to top)