QDB - Quantum Database Backup

A universal CLI tool for creating post-quantum encrypted database backups that are automatically emailed to recipients. Supports Supabase, MongoDB, MySQL, and PostgreSQL.

Features

• 🔐 Post-Quantum Encryption: Uses @profullstack/post-quantum-helper for quantum-resistant encryption
• 🗄️ Multi-Database Support: Works with Supabase, MongoDB, MySQL, and PostgreSQL
• 💾 Automated Backups: Seamlessly integrates with native database CLIs
• 🔄 Full Restore: Decrypt and restore backups to any supported database
• 📧 Email Delivery: Automatically sends encrypted backups via email
• 🔒 Secure Key Management: You control your encryption keys - they're never stored or shared
• 📦 Compressed Archives: Creates ZIP archives before encryption for efficient storage
• 🧹 Clean Workflow: Automatically cleans up intermediate files

Supported Databases

| Database | CLI Tool | Backup Command | Restore Command | |----------|----------|----------------|-----------------| | Supabase | pnpx supabase | db dump | db reset | | MongoDB | mongodump | mongodump --archive | mongorestore --archive | | MySQL | mysqldump | mysqldump | mysql | | PostgreSQL | pg_dump | pg_dump --format=custom | pg_restore |

Prerequisites

• Node.js 20 or newer
• SMTP credentials for email delivery
• At least one database CLI installed:
  • Supabase: pnpm add -g supabase
  • MongoDB: MongoDB Database Tools
  • MySQL: MySQL Client
  • PostgreSQL: PostgreSQL Client

Installation

Option 1: Install Globally (Recommended)

# Install globally from npm (when published)
pnpm add -g @profullstack/quantum-database-backups

# Or install from local directory
cd quantum-database-backups
pnpm install
pnpm link --global

# Now you can use 'qdb' from anywhere
qdb --help

Option 2: Local Development

# Clone the repository
git clone <repository-url>
cd quantum-database-backups

# Install dependencies
pnpm install

# Run locally with node
node src/cli.js --help

Quick Start

Interactive Setup (Recommended)

Run the interactive setup wizard to configure QDB:

qdb init

This will prompt you for:

• Path to encryption keys file
• Default recipient email
• Default database name
• Working directory for backups
• SMTP server settings (host, port, credentials)

Configuration is saved to ~/.config/quantum-database-backups/config.json with secure permissions (0600).

Manual Configuration

Alternatively, you can configure via environment variables:

export SMTP_USER="[email protected]"
export SMTP_PASS="your-app-password"
export SMTP_HOST="smtp.gmail.com"  # Optional
export SMTP_PORT="587"              # Optional

Generate Encryption Keys

You need to generate your post-quantum encryption keys. Create a keys.json file:

{
  "publicKey": "your-public-key-here",
  "privateKey": "your-private-key-here"
}

⚠️ IMPORTANT: Keep your keys.json file secure and backed up separately. Without it, you cannot decrypt your backups!

For Gmail SMTP, use an App Password.

Usage

Create an Encrypted Backup

Supabase (Default)

# Using saved configuration
qdb backup

# With explicit options
qdb backup \
  --email [email protected] \
  --keys ./keys.json \
  --db-name mydb

MongoDB

qdb backup \
  --provider mongodb \
  --email [email protected] \
  --keys ./keys.json \
  --db-name mydb \
  --uri mongodb://localhost:27017

MySQL

qdb backup \
  --provider mysql \
  --email [email protected] \
  --keys ./keys.json \
  --db-name mydb \
  --host localhost \
  --port 3306 \
  --user root \
  --password mypassword

PostgreSQL

qdb backup \
  --provider postgres \
  --email [email protected] \
  --keys ./keys.json \
  --db-name mydb \
  --host localhost \
  --port 5432 \
  --user postgres \
  --password mypassword

Backup Options

• -e, --email <email> - Recipient email address
• -k, --keys <path> - Path to keys.json file
• -d, --db-name <name> - Database name for filename
• -p, --provider <name> - Database provider (supabase, mongodb, mysql, postgres)
• -w, --work-dir <path> - Working directory for backups (default: ./backups)
• --keep-files - Keep intermediate files (default: false)
• --no-email - Skip sending email

Provider-Specific Options:

• --host <host> - Database host (MySQL, PostgreSQL)
• --port <port> - Database port (MySQL, PostgreSQL)
• --user <user> - Database user (MySQL, PostgreSQL)
• --password <password> - Database password (MySQL, PostgreSQL)
• --uri <uri> - Connection URI (MongoDB)

Restore from Encrypted Backup

Supabase

qdb restore \
  --input ./backups/backup.encrypted \
  --keys ./keys.json \
  --provider supabase

MongoDB

qdb restore \
  --input ./backups/backup.encrypted \
  --keys ./keys.json \
  --provider mongodb \
  --uri mongodb://localhost:27017 \
  --database mydb \
  --drop

MySQL

qdb restore \
  --input ./backups/backup.encrypted \
  --keys ./keys.json \
  --provider mysql \
  --host localhost \
  --port 3306 \
  --user root \
  --password mypassword \
  --database mydb

PostgreSQL

qdb restore \
  --input ./backups/backup.encrypted \
  --keys ./keys.json \
  --provider postgres \
  --host localhost \
  --port 5432 \
  --user postgres \
  --password mypassword \
  --database mydb \
  --clean

Restore Options

• -i, --input <path> - Path to encrypted backup file (required)
• -k, --keys <path> - Path to keys.json file (required)
• -p, --provider <name> - Database provider (supabase, mongodb, mysql, postgres) (default: supabase)
• --host <host> - Database host (MySQL, PostgreSQL)
• --port <port> - Database port (MySQL, PostgreSQL)
• --user <user> - Database user (MySQL, PostgreSQL)
• --password <password> - Database password (MySQL, PostgreSQL)
• --database <name> - Database name
• --uri <uri> - Connection URI (MongoDB)
• --drop - Drop existing data before restore (MongoDB/PostgreSQL)
• --clean - Clean database before restore (PostgreSQL)

Decrypt a Backup

qdb decrypt \
  --input ./backups/supabase-backup-20241006-123456-mydb.zip.encrypted \
  --output ./restored-backup.zip \
  --keys ./keys.json

Options

• -i, --input <path> - Path to encrypted file (required)
• -o, --output <path> - Path for decrypted output file (required)
• -k, --keys <path> - Path to keys.json file (required)

View Configuration

qdb info

This displays your current configuration and available commands.

Configuration Priority

QDB uses the following priority order for configuration:

1. Command-line arguments (highest priority)
2. Saved configuration (~/.config/quantum-database-backups/config.json)
3. Environment variables
4. Default values (lowest priority)

This allows you to:

• Set defaults with qdb init
• Override per-backup with CLI flags
• Use environment variables for sensitive data

Workflow

The backup process follows these steps:

1. Load Configuration: Merges CLI args, saved config, and env vars
2. Load Keys: Reads your encryption keys from configured path
3. Database Dump: Executes pnpx supabase db dump to create SQL backup
4. Create Archive: Compresses the SQL file into a ZIP archive
5. Encrypt: Encrypts the ZIP file using post-quantum cryptography
6. Email: Sends the encrypted file to the specified recipient
7. Cleanup: Removes intermediate files (unless --keep-files is used)

File Naming Convention

Backup files follow this naming pattern:

supabase-backup-{YYYYMMDD-HHMMSS}-{dbname}.{extension}

Example: supabase-backup-20241006-143022-production.zip.encrypted

Security Best Practices

1. Never commit keys.json: Add it to .gitignore
2. Store keys separately: Keep backups of your keys in a secure location separate from your encrypted backups
3. Use strong SMTP passwords: Use app-specific passwords when available
4. Rotate keys periodically: Generate new keys and re-encrypt old backups
5. Test decryption: Regularly verify you can decrypt your backups

Development

Running Tests

# Run all tests
pnpm test

# Run with coverage
pnpm test -- --coverage

Linting and Formatting

# Check code style
pnpm run lint

# Format code
pnpm run format

# Check formatting without changes
pnpm run format:check

Project Structure

quantum-database-backups/
├── src/
│   ├── cli.js          # CLI entry point
│   ├── backup.js       # Database backup logic
│   ├── encrypt.js      # Post-quantum encryption
│   ├── email.js        # Email functionality
│   └── utils.js        # Helper functions
├── tests/
│   └── utils.test.js   # Test files
├── .eslintrc.json      # ESLint configuration
├── .prettierrc.json    # Prettier configuration
├── package.json        # Project dependencies
└── README.md           # This file

Troubleshooting

"SMTP not configured" Error

Make sure you've set the SMTP_USER and SMTP_PASS environment variables:

export SMTP_USER="[email protected]"
export SMTP_PASS="your-password"

"Database dump failed" Error

Ensure:

1. Supabase CLI is installed: pnpm add -g supabase
2. You're in a directory with a Supabase project
3. Your Supabase project is properly configured

"Missing required keys" Error

Your keys.json file must contain both publicKey and privateKey fields:

{
  "publicKey": "...",
  "privateKey": "..."
}

License

MIT

Contributing

Contributions are welcome! Please follow these guidelines:

1. Follow the existing code style (ESLint + Prettier)
2. Write tests for new features
3. Update documentation as needed
4. Keep commits focused and descriptive

Support

For issues and questions, please open an issue on the GitHub repository.

Copyright

© Profullstack, Inc. https://profullstck.com