🔁 Automated MariaDB database backups with S3-compatible storage integration

• 🗄️ MariaDB Backup to S3
  • Table of Contents
  • 🚀 Quick Start
  • ✨ Features
  • 🛠️ How It Works
    • Temporary Working Directory
  • 📋 Prerequisites
  • 📦 Installation
    • Binary Installation (Recommended)
    • Using Go Install
    • Docker
    • From Source (Advanced)
  • ⚙️ Configuration
    • Logging Configuration
  • 🚀 Usage
    • Backup
    • Restore
  • 📂 Storage Types
    • S3 Storage
    • FTP Storage
    • Filesystem Storage
  • 🔐 Encryption
    • Security Considerations
      • Key Management
      • Key Generation
  • 📝 Examples
  • 🤝 Contributing
  • 📄 License

# Using pre-built binary (check Releases page for latest version)
curl -LO 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
chmod +x mariadb-backup-s3
./mariadb-backup-s3 --help

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

# Configure & run
cp .env.example .env
nano .env  # Edit with your credentials
./mariadb-backup-s3

• 🛡️ Full database backups using mariabackup
• 🗜️ Compression to .tar.gz format
• 🔑 Optional encryption using AES-256-GCM
• ☁️ Multiple storage backends (S3-compatible, FTP, filesystem)
• 🔌 Pluggable storage interface for extensibility
• 🔄 Automatic backup rotation
• 🐳 Docker container support

The backup process follows these steps:

1. 📂 Create temporary working directory
2. 💾 Perform MariaDB backup using mariabackup --backup
3. 🔧 Prepare backup for consistency using mariabackup --prepare
4. 🗜️ Compress backup to .tar.gz archive
5. 🔑 Encrypt archive using AES-256-GCM
6. 🚀 Upload archive to configured storage backend
7. 🧹 Clean up old backups based on retention policy

The restore process follows these steps:

1. 📥 Download the backup file from the specified storage backend
2. 🔑 Decrypt the backup using AES-256-GCM
3. 🗜️ Decompress the .tar.gz archive
4. 🔄 Restore the database files to specified directory

The tool uses a temporary working directory to store intermediate files. By default, it uses the system's default temporary directory (e.g., /tmp). If for some reason you need to use a different directory, you can specify it via the TMPDIR environment variable.

export TMPDIR=/mnt/data/backup
./mariadb-backup-s3 backup

• Go 1.23+ (for building from source)
• MariaDB server
• At least 2x the actual database size in free space (for successful backup)
• Storage backend credentials (depending on chosen storage type)

1. Visit the Releases page
2. Download the appropriate binary for your OS
3. Make executable: chmod +x mariadb-backup-s3
4. Move to PATH: sudo mv mariadb-backup-s3 /usr/local/bin/

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

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

Note The Docker image uses MariaDB's lts version. For specific versions:

1. Clone the repository
2. Modify Dockerfile base image
3. Build custom image: docker build -t custom-backup-image .

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

The tool supports loading configuration from multiple sources:

1. .env file in the current directory
2. Environment variables
3. Command-line flags

The priority order is: .env > Environment variables > Command-line flags

The logging system can be configured via environment variables:

• LOG_LEVEL: Set log level (debug, info, warn, error, fatal). Default: info
• LOG_FORMAT: Set format (human, json). Default: human
• LOG_OUTPUT: Set output destination:
  • stdout (default): Standard output
  • stderr: Standard error
  • Any file path: Write logs to the specified file
• NO_COLOR: When set (any non-empty value), disables colored output for human format

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

The tool offers the following commands:

mariadb-backup-s3 backup [options]

Options:

Example:

./mariadb-backup-s3 backup \
  --db-host=mariadb.example.com \
  --db-user=backup \
  --storage-url="file:///var/backups/mariadb"

mariadb-backup-s3 restore [options] filename

Options:

Arguments:

Example:

./mariadb-backup-s3 restore \
  --storage-url="file:///var/backups/mariadb" \
  --target-dir=/var/lib/mariadb \
  backup_name.tar.gz

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

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

Required for S3:

• AWS_ACCESS_KEY: Your access key
• AWS_SECRET_KEY: Your secret key
• AWS_REGION: AWS region (or any region for non-AWS S3)

Query Parameters:

• endpoint: S3 endpoint URL
• s3-force-path-style: Set to "true" to use path-style URLs

For FTP servers:

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

Required for FTP:

• username: FTP username (defaults to "anonymous" if not provided)
• password: FTP password (optional for anonymous)
• host: FTP server hostname
• port: FTP port (defaults to 21)

For local or mounted filesystem storage:

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

The backup system supports client-side encryption using AES-256 in Galois/Counter Mode (GCM) to ensure your database backups remain confidential and secure. This method provides both confidentiality and integrity verification.

Features:

• 256-bit key strength
• Authenticated encryption with additional data (AEAD)
• Automatic nonce generation for each backup

Configuration:

# base64-encoded encryption key
ENCRYPTION__KEY=Av2cfWJ3enCHTyzPdzowfAXshvJtbEsvwgPjV46wnjc=

• 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

Generate secure encryption keys using cryptographically secure methods:

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

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

• systemd Service Example: examples/systemd-service
• Docker Swarm CRON Example: examples/docker-cron-backup
• Simple CRON Example: examples/simple-cron-backup
• Advanced CRON Example: examples/advanced-cron-backup
• Encryption Example: examples/encryption-example

We welcome contributions! Please follow these steps:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch: git checkout -b feat/amazing-feature
3. 💾 Commit changes: git commit -m 'Add amazing feature'
4. 🚀 Push to branch: git push origin feat/amazing-feature
5. 🔀 Create a Pull Request

Apache 2.0 - See LICENSE for details.

💡 Need Help? Open an issue for support.