{"id":31956332,"url":"https://github.com/profullstack/quantum-database-backups","last_synced_at":"2025-10-14T14:49:58.229Z","repository":{"id":318325125,"uuid":"1070740130","full_name":"profullstack/quantum-database-backups","owner":"profullstack","description":"A CLI tool for creating post-quantum encrypted database backups that are automatically emailed to recipients.","archived":false,"fork":false,"pushed_at":"2025-10-06T13:32:18.000Z","size":60,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-06T15:24:44.965Z","etag":null,"topics":["automation","backups","database","hacktoberfest","post-quantum"],"latest_commit_sha":null,"homepage":"https://profullstack.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/profullstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-06T11:26:41.000Z","updated_at":"2025-10-06T13:32:22.000Z","dependencies_parsed_at":"2025-10-06T15:24:46.537Z","dependency_job_id":"fafcbb6b-7a04-47fa-a65f-2965f36def2b","html_url":"https://github.com/profullstack/quantum-database-backups","commit_stats":null,"previous_names":["profullstack/quantum-database-backups"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/profullstack/quantum-database-backups","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fquantum-database-backups","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fquantum-database-backups/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fquantum-database-backups/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fquantum-database-backups/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/profullstack","download_url":"https://codeload.github.com/profullstack/quantum-database-backups/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fquantum-database-backups/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019143,"owners_count":26086685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","backups","database","hacktoberfest","post-quantum"],"created_at":"2025-10-14T14:48:32.253Z","updated_at":"2025-10-14T14:49:58.224Z","avatar_url":"https://github.com/profullstack.png","language":"JavaScript","readme":"# QDB - Quantum Database Backup\n\nA universal CLI tool for creating post-quantum encrypted database backups that are automatically emailed to recipients. Supports Supabase, MongoDB, MySQL, and PostgreSQL.\n\n## Features\n\n- 🔐 **Post-Quantum Encryption**: Uses `@profullstack/post-quantum-helper` for quantum-resistant encryption\n- 🗄️ **Multi-Database Support**: Works with Supabase, MongoDB, MySQL, and PostgreSQL\n- 💾 **Automated Backups**: Seamlessly integrates with native database CLIs\n- 🔄 **Full Restore**: Decrypt and restore backups to any supported database\n- 📧 **Email Delivery**: Automatically sends encrypted backups via email\n- 🔒 **Secure Key Management**: You control your encryption keys - they're never stored or shared\n- 📦 **Compressed Archives**: Creates ZIP archives before encryption for efficient storage\n- 🧹 **Clean Workflow**: Automatically cleans up intermediate files\n\n## Supported Databases\n\n| Database | CLI Tool | Backup Command | Restore Command |\n|----------|----------|----------------|-----------------|\n| Supabase | `pnpx supabase` | `db dump` | `db reset` |\n| MongoDB | `mongodump` | `mongodump --archive` | `mongorestore --archive` |\n| MySQL | `mysqldump` | `mysqldump` | `mysql` |\n| PostgreSQL | `pg_dump` | `pg_dump --format=custom` | `pg_restore` |\n\n## Prerequisites\n\n- Node.js 20 or newer\n- SMTP credentials for email delivery\n- At least one database CLI installed:\n  - **Supabase**: `pnpm add -g supabase`\n  - **MongoDB**: [MongoDB Database Tools](https://www.mongodb.com/try/download/database-tools)\n  - **MySQL**: [MySQL Client](https://dev.mysql.com/downloads/mysql/)\n  - **PostgreSQL**: [PostgreSQL Client](https://www.postgresql.org/download/)\n\n## Installation\n\n### Option 1: Install Globally (Recommended)\n\n```bash\n# Install globally from npm (when published)\npnpm add -g @profullstack/quantum-database-backups\n\n# Or install from local directory\ncd quantum-database-backups\npnpm install\npnpm link --global\n\n# Now you can use 'qdb' from anywhere\nqdb --help\n```\n\n### Option 2: Local Development\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd quantum-database-backups\n\n# Install dependencies\npnpm install\n\n# Run locally with node\nnode src/cli.js --help\n```\n\n## Quick Start\n\n### Interactive Setup (Recommended)\n\nRun the interactive setup wizard to configure QDB:\n\n```bash\nqdb init\n```\n\nThis will prompt you for:\n- Path to encryption keys file\n- Default recipient email\n- Default database name\n- Working directory for backups\n- SMTP server settings (host, port, credentials)\n\nConfiguration is saved to `~/.config/quantum-database-backups/config.json` with secure permissions (0600).\n\n### Manual Configuration\n\nAlternatively, you can configure via environment variables:\n\n```bash\nexport SMTP_USER=\"your-email@example.com\"\nexport SMTP_PASS=\"your-app-password\"\nexport SMTP_HOST=\"smtp.gmail.com\"  # Optional\nexport SMTP_PORT=\"587\"              # Optional\n```\n\n### Generate Encryption Keys\n\nYou need to generate your post-quantum encryption keys. Create a `keys.json` file:\n\n```json\n{\n  \"publicKey\": \"your-public-key-here\",\n  \"privateKey\": \"your-private-key-here\"\n}\n```\n\n**⚠️ IMPORTANT**: Keep your `keys.json` file secure and backed up separately. Without it, you cannot decrypt your backups!\n\nFor Gmail SMTP, use an [App Password](https://support.google.com/accounts/answer/185833).\n\n## Usage\n\n### Create an Encrypted Backup\n\n#### Supabase (Default)\n\n```bash\n# Using saved configuration\nqdb backup\n\n# With explicit options\nqdb backup \\\n  --email recipient@example.com \\\n  --keys ./keys.json \\\n  --db-name mydb\n```\n\n#### MongoDB\n\n```bash\nqdb backup \\\n  --provider mongodb \\\n  --email admin@example.com \\\n  --keys ./keys.json \\\n  --db-name mydb \\\n  --uri mongodb://localhost:27017\n```\n\n#### MySQL\n\n```bash\nqdb backup \\\n  --provider mysql \\\n  --email admin@example.com \\\n  --keys ./keys.json \\\n  --db-name mydb \\\n  --host localhost \\\n  --port 3306 \\\n  --user root \\\n  --password mypassword\n```\n\n#### PostgreSQL\n\n```bash\nqdb backup \\\n  --provider postgres \\\n  --email admin@example.com \\\n  --keys ./keys.json \\\n  --db-name mydb \\\n  --host localhost \\\n  --port 5432 \\\n  --user postgres \\\n  --password mypassword\n```\n\n#### Backup Options\n\n- `-e, --email \u003cemail\u003e` - Recipient email address\n- `-k, --keys \u003cpath\u003e` - Path to keys.json file\n- `-d, --db-name \u003cname\u003e` - Database name for filename\n- `-p, --provider \u003cname\u003e` - Database provider (supabase, mongodb, mysql, postgres)\n- `-w, --work-dir \u003cpath\u003e` - Working directory for backups (default: `./backups`)\n- `--keep-files` - Keep intermediate files (default: false)\n- `--no-email` - Skip sending email\n\n**Provider-Specific Options**:\n- `--host \u003chost\u003e` - Database host (MySQL, PostgreSQL)\n- `--port \u003cport\u003e` - Database port (MySQL, PostgreSQL)\n- `--user \u003cuser\u003e` - Database user (MySQL, PostgreSQL)\n- `--password \u003cpassword\u003e` - Database password (MySQL, PostgreSQL)\n- `--uri \u003curi\u003e` - Connection URI (MongoDB)\n### Restore from Encrypted Backup\n\n#### Supabase\n\n```bash\nqdb restore \\\n  --input ./backups/backup.encrypted \\\n  --keys ./keys.json \\\n  --provider supabase\n```\n\n#### MongoDB\n\n```bash\nqdb restore \\\n  --input ./backups/backup.encrypted \\\n  --keys ./keys.json \\\n  --provider mongodb \\\n  --uri mongodb://localhost:27017 \\\n  --database mydb \\\n  --drop\n```\n\n#### MySQL\n\n```bash\nqdb restore \\\n  --input ./backups/backup.encrypted \\\n  --keys ./keys.json \\\n  --provider mysql \\\n  --host localhost \\\n  --port 3306 \\\n  --user root \\\n  --password mypassword \\\n  --database mydb\n```\n\n#### PostgreSQL\n\n```bash\nqdb restore \\\n  --input ./backups/backup.encrypted \\\n  --keys ./keys.json \\\n  --provider postgres \\\n  --host localhost \\\n  --port 5432 \\\n  --user postgres \\\n  --password mypassword \\\n  --database mydb \\\n  --clean\n```\n\n#### Restore Options\n\n- `-i, --input \u003cpath\u003e` - Path to encrypted backup file (required)\n- `-k, --keys \u003cpath\u003e` - Path to keys.json file (required)\n- `-p, --provider \u003cname\u003e` - Database provider (supabase, mongodb, mysql, postgres) (default: supabase)\n- `--host \u003chost\u003e` - Database host (MySQL, PostgreSQL)\n- `--port \u003cport\u003e` - Database port (MySQL, PostgreSQL)\n- `--user \u003cuser\u003e` - Database user (MySQL, PostgreSQL)\n- `--password \u003cpassword\u003e` - Database password (MySQL, PostgreSQL)\n- `--database \u003cname\u003e` - Database name\n- `--uri \u003curi\u003e` - Connection URI (MongoDB)\n- `--drop` - Drop existing data before restore (MongoDB/PostgreSQL)\n- `--clean` - Clean database before restore (PostgreSQL)\n\n\n### Decrypt a Backup\n\n```bash\nqdb decrypt \\\n  --input ./backups/supabase-backup-20241006-123456-mydb.zip.encrypted \\\n  --output ./restored-backup.zip \\\n  --keys ./keys.json\n```\n\n#### Options\n\n- `-i, --input \u003cpath\u003e` - Path to encrypted file (required)\n- `-o, --output \u003cpath\u003e` - Path for decrypted output file (required)\n- `-k, --keys \u003cpath\u003e` - Path to keys.json file (required)\n\n### View Configuration\n\n```bash\nqdb info\n```\n\nThis displays your current configuration and available commands.\n\n## Configuration Priority\n\nQDB uses the following priority order for configuration:\n\n1. **Command-line arguments** (highest priority)\n2. **Saved configuration** (`~/.config/quantum-database-backups/config.json`)\n3. **Environment variables**\n4. **Default values** (lowest priority)\n\nThis allows you to:\n- Set defaults with `qdb init`\n- Override per-backup with CLI flags\n- Use environment variables for sensitive data\n\n## Workflow\n\nThe backup process follows these steps:\n\n1. **Load Configuration**: Merges CLI args, saved config, and env vars\n2. **Load Keys**: Reads your encryption keys from configured path\n3. **Database Dump**: Executes `pnpx supabase db dump` to create SQL backup\n4. **Create Archive**: Compresses the SQL file into a ZIP archive\n5. **Encrypt**: Encrypts the ZIP file using post-quantum cryptography\n6. **Email**: Sends the encrypted file to the specified recipient\n7. **Cleanup**: Removes intermediate files (unless `--keep-files` is used)\n\n## File Naming Convention\n\nBackup files follow this naming pattern:\n\n```\nsupabase-backup-{YYYYMMDD-HHMMSS}-{dbname}.{extension}\n```\n\nExample: `supabase-backup-20241006-143022-production.zip.encrypted`\n\n## Security Best Practices\n\n1. **Never commit keys.json**: Add it to `.gitignore`\n2. **Store keys separately**: Keep backups of your keys in a secure location separate from your encrypted backups\n3. **Use strong SMTP passwords**: Use app-specific passwords when available\n4. **Rotate keys periodically**: Generate new keys and re-encrypt old backups\n5. **Test decryption**: Regularly verify you can decrypt your backups\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test -- --coverage\n```\n\n### Linting and Formatting\n\n```bash\n# Check code style\npnpm run lint\n\n# Format code\npnpm run format\n\n# Check formatting without changes\npnpm run format:check\n```\n\n### Project Structure\n\n```\nquantum-database-backups/\n├── src/\n│   ├── cli.js          # CLI entry point\n│   ├── backup.js       # Database backup logic\n│   ├── encrypt.js      # Post-quantum encryption\n│   ├── email.js        # Email functionality\n│   └── utils.js        # Helper functions\n├── tests/\n│   └── utils.test.js   # Test files\n├── .eslintrc.json      # ESLint configuration\n├── .prettierrc.json    # Prettier configuration\n├── package.json        # Project dependencies\n└── README.md           # This file\n```\n\n## Troubleshooting\n\n### \"SMTP not configured\" Error\n\nMake sure you've set the `SMTP_USER` and `SMTP_PASS` environment variables:\n\n```bash\nexport SMTP_USER=\"your-email@example.com\"\nexport SMTP_PASS=\"your-password\"\n```\n\n### \"Database dump failed\" Error\n\nEnsure:\n1. Supabase CLI is installed: `pnpm add -g supabase`\n2. You're in a directory with a Supabase project\n3. Your Supabase project is properly configured\n\n### \"Missing required keys\" Error\n\nYour `keys.json` file must contain both `publicKey` and `privateKey` fields:\n\n```json\n{\n  \"publicKey\": \"...\",\n  \"privateKey\": \"...\"\n}\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Follow the existing code style (ESLint + Prettier)\n2. Write tests for new features\n3. Update documentation as needed\n4. Keep commits focused and descriptive\n\n## Support\n\nFor issues and questions, please open an issue on the GitHub repository.\n\n## Copyright\n\n© Profullstack, Inc. https://profullstck.com","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fquantum-database-backups","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofullstack%2Fquantum-database-backups","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fquantum-database-backups/lists"}