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

$3

``bash


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
`

$3

`bash


Clone the repository

git clone
cd quantum-database-backups

Install dependencies

pnpm install

Run locally with node

node src/cli.js --help
`

Quick Start

$3

Run the interactive setup wizard to configure QDB:

`bash
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).

$3

Alternatively, you can configure via environment variables:

`bash
export SMTP_USER="your-email@example.com"
export SMTP_PASS="your-app-password"
export SMTP_HOST="smtp.gmail.com" # Optional
export SMTP_PORT="587" # Optional
`

$3

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

`json
{
"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

$3

#### Supabase (Default)

`bash


Using saved configuration

qdb backup

With explicit options

qdb backup \
--email recipient@example.com \
--keys ./keys.json \
--db-name mydb
`

#### MongoDB

`bash
qdb backup \
--provider mongodb \
--email admin@example.com \
--keys ./keys.json \
--db-name mydb \
--uri mongodb://localhost:27017
`

#### MySQL

`bash
qdb backup \
--provider mysql \
--email admin@example.com \
--keys ./keys.json \
--db-name mydb \
--host localhost \
--port 3306 \
--user root \
--password mypassword
`

#### PostgreSQL

`bash
qdb backup \
--provider postgres \
--email admin@example.com \
--keys ./keys.json \
--db-name mydb \
--host localhost \
--port 5432 \
--user postgres \
--password mypassword
`

#### Backup Options

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

Provider-Specific Options:
- --host - Database host (MySQL, PostgreSQL)
- --port - Database port (MySQL, PostgreSQL)
- --user - Database user (MySQL, PostgreSQL)
- --password - Database password (MySQL, PostgreSQL)
- --uri - Connection URI (MongoDB)


$3

#### Supabase

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

#### MongoDB

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

#### MySQL

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

#### PostgreSQL

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




$3

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

#### Options

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

$3

`bash
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

$3

`bash


Run all tests

pnpm test

Run with coverage

pnpm test -- --coverage
`

$3

`bash


Check code style

pnpm run lint

Format code

pnpm run format

Check formatting without changes

pnpm run format:check
`

$3

`
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

$3

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

`bash
export SMTP_USER="your-email@example.com"
export SMTP_PASS="your-password"
`

$3

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

$3

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

`json
{
"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