-success){kind=icon}
Lightweight, Fast, Zero-Trust Database Backup Engine
LunarDump is a modern, developer-friendly Command-Line Interface (CLI) tool designed to streamline and secure your database backup workflows. Built with Python, it automates the entire lifecycle of database disaster recovery—from streaming dumps without memory overhead, applying military-grade AES-256-GCM encryption, to syncing backups directly across cloud providers.
- 🗄️ Multi-Engine Support: Seamlessly handles PostgreSQL, MySQL, MariaDB, and MongoDB out-of-the-box.
- 🔐 Zero-Trust Encryption: End-to-end authenticated AES-256-GCM encryption applied locally before any data leaves your server.
- ⚡ Memory-Efficient Streaming: Streams database dumps directly through encryption into cloud storage, preventing RAM spikes even on multi-gigabyte databases.
- ☁️ Multi-Cloud Syncing: Direct integration with AWS S3, Google Cloud Storage (GCS), Cloudflare R2, and MinIO.
- 🧹 Automated Retention Cleaner: Automatically purges outdated backup archives according to your custom retention window.
- 🔔 Instant Telemetry: Rich terminal UI with progress bars, health-check tables, and webhook alerts to Telegram & Slack.
# Standard installation
pip install lunardump
# With Google Cloud Storage support
pip install "lunardump[gcs]"# Global CLI Tool Installation (Recommended for servers & workstations)
uv tool install lunardump
# One-Off Instant Execution without installing (like npx)
uvx lunardump run --config config.yaml# Run LunarDump using official Docker image
docker run --rm \
-v $(pwd)/config.yaml:/app/config.yaml:ro \
-v $(pwd)/.env:/app/.env:ro \
indhifarhandika/lunardump:latest run --config /app/config.yamlLunarDump leverages native client dump tools for streaming efficiency. Ensure the CLI client for your database engine is installed on your system:
# For MySQL / MariaDB
brew install mysql-client
export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"
# For PostgreSQL
brew install libpq
# For MongoDB
brew install mongodb-database-tools# For MySQL
sudo apt update && sudo apt install -y mysql-client
# For PostgreSQL
sudo apt install -y postgresql-client
# For MongoDB
sudo apt install -y mongodb-org-tools
# For MySQL
sudo apt update && sudo apt install -y mariadb-client-compat
# For PostgreSQL
sudo apt install -y postgresql-client
# For MongoDB
sudo apt-get install gnupg curl
curl -fsSL https://pgp.mongodb.com/server-8.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt-get update
sudo apt-get install -y mongodb-orgGenerate production-ready configuration and .env template files instantly without manual typing:
# Generate default templates (PostgreSQL + S3)
lunardump config generate
# Or specify database engine (postgres | mysql | mongo) and storage target (s3 | gcs | local)
lunardump config generate --db-type postgres --storage s3This single command automatically generates 3 files:
config.yaml: Pre-configured backup job profile.migration.yaml: Live database-to-database migration profile..env: Environment file containing an auto-generated cryptographically secure 256-bit AES key!
Open .env to set your real database passwords and cloud credentials:
# Database Passwords
DB_PASSWORD="your_database_password_here"
SOURCE_DB_PASS="password_server_a"
TARGET_DB_PASS="password_server_b"
# Cryptographic AES-256 Secret Key (Auto-Generated Hex)
LUNARDUMP_ENCRYPTION_KEY="f48a9b2c..."
# Cloud Storage Credentials (AWS S3)
AWS_ACCESS_KEY_ID="your_aws_access_key_id"
AWS_SECRET_ACCESS_KEY="your_aws_secret_access_key"
# Or for Google Cloud Storage (GCS)
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# Notifications
TELEGRAM_BOT_TOKEN="your_telegram_bot_token"Before running your backup job, test connectivity to your database, CLI tools, encryption keys, and cloud storage:
lunardump config check --config config.yamlOutput preview:
LunarDump System Health Check
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component ┃ Details ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Config File │ config.yaml │ VALID (Pydantic v2) │
│ DB Engine (mysql) │ Tool binary check │ INSTALLED │
│ DB Connection │ 127.0.0.1:3306/db_user │ CONNECTED │
│ Encryption (AES-256-GCM) │ Env: LUNARDUMP_ENCRYPTION_KEY │ KEY READY │
│ Storage Target │ s3://company-db-backups │ REACHABLE │
└──────────────────────────┴───────────────────────────────┴────────────────────────────────────┘
Run the automated backup pipeline:
# Dry-run mode: validates configuration without creating files
lunardump run --config config.yaml --dry-run
# Run full backup (Dump -> Encrypt -> Upload -> Retention Cleanup -> Webhook Alert)
lunardump run --config config.yamlDecrypt an AES-256-GCM encrypted backup file back to plain database SQL/dump format:
# Decrypt using key file
lunardump restore --file backup_20260729.enc --key secret.key --output backup_decrypted.sql
# Decrypt using raw key string
lunardump restore --file backup_20260729.enc --key f77693f31ebef68d774913969a3f6a57ee... --output backup_decrypted.sqlVerify that a backup archive is authentic, uncorrupted, and decryptable without restoring it to database or disk:
# Verify local encrypted backup file
lunardump restore --file backup_20260730.enc --key secret.key --verify
# Download and verify directly from cloud storage (AWS S3 / GCS)
lunardump restore --config config.yaml --remote-key daily/mysql/backup_20260730.enc --verifyPerform an instant database dump directly to a local file or stdout without requiring a configuration file:
# Dump MySQL directly to file
lunardump db dump --type mysql --host localhost --user root --name db_name --output dump.sql
# Dump PostgreSQL directly to stdout
lunardump db dump --type postgres --host localhost --user postgres --name main_db > dump.sqlLunarDump features a built-in continuous background daemon runner. You can automate recurring backup schedules directly using human-friendly schedule expressions or standard cron syntax:
Run LunarDump continuously as a background daemon process:
# Run daily at 02:00 AM (Human-friendly string)
lunardump run --config config.yaml --cron "day-2"
# Run weekly on Monday at 14:30
lunardump run --config config.yaml --cron "week-mon-14.5"
# Run monthly on the 1st of every month at 02:00 AM
lunardump run --config config.yaml --cron "month-1-2"
# Run every 15 minutes
lunardump run --config config.yaml --cron "every-15m"
# Standard 5-field cron syntax
lunardump run --config config.yaml --cron "0 2 * * *"💡 Tip: You can also define
cron: "day-2"inside yourconfig.yamlfile so runninglunardump run --config config.yamlautomatically launches daemon mode.
Alternatively, schedule one-off backup runs via Linux system crontab:
# Open crontab editor
crontab -e
# Add daily backup entry at 02:00 AM
0 2 * * * cd /opt/lunardump && source .env && lunardump run --config config.yaml >> /var/log/lunardump.log 2>&1Contributions, issues, and feature requests are welcome! Whether it's reporting a bug, adding support for new database engines or storage providers, or improving documentation, your help is greatly appreciated.
For full development setup, testing standards, and pull request guidelines, please read our CONTRIBUTING.md.
For security policies, vulnerability reporting, and cryptographic safety guidelines, please read our SECURITY.md.
- HackTrack: Pre-installed natively. You can run
lunardumpdirectly from the terminal or launch it from the system menu under Extra Tools.
If you find LunarDump useful for your projects or infrastructure, please consider supporting its development:
Distributed under the MIT License. See LICENSE for more information.