dbdump initial commit

2026-04-28 21:24:57 +02:00
parent e17c339b8e
commit b5c1ac95b7
4 changed files with 702 additions and 0 deletions
@@ -0,0 +1,219 @@
+# MongoDB Dump Utility
+
+This directory contains a standalone tool for backing up MongoDB databases from remote servers.
+It manages multiple environment configurations for easy switching between prod, uat, and other environments.
+
+## Quick Start
+
+### First Run
+
+```bash
+./db-dump.sh dump
+```
+
+The script will detect no environments and guide you through creating one. Answer the prompts with:
+- **Environment name** (required): e.g., `prod`, `uat`, `staging`
+- **MongoDB username** (required): The admin user
+- **MongoDB password** (required): The admin password
+- **MongoDB host** (required): e.g., `cluster0.mongodb.net`
+- **MongoDB port** (required): Usually `27017` or `10255`
+- **Application name** (required): Used in connection string and dump folder name
+
+### Subsequent Runs
+
+```bash
+./db-dump.sh dump
+```
+
+The script will show you a list of configured environments and let you choose which one to backup,
+or create a new environment.
+
+## Commands
+
+```bash
+# Perform a backup of a selected environment
+./db-dump.sh dump
+
+# List all configured environments
+./db-dump.sh list
+
+# Add a new environment
+./db-dump.sh add
+
+# Delete an environment
+./db-dump.sh delete
+
+# Show help
+./db-dump.sh help
+```
+
+## How It Works
+
+1. **Environment Selection**: On each run, you select from existing environments or create new ones
+2. **Credential Storage**: Each environment's credentials are stored in `.env.<name>` files
+3. **MongoDB Connection**: Connects using your credentials with MongoDB Atlas parameters (ssl, replicaSet, etc.)
+4. **Dump Creation**: Uses `mongodump` to create a backup
+5. **Timestamped Output**: Dumps are organized as `./dumps/<appName>/<yyyymmdd_hhmm>/`
+
+## Configuration Files
+
+Each environment is stored in a separate file:
+
+```
+.env.prod       # Production environment
+.env.uat        # UAT environment
+.env.staging    # Staging environment (if created)
+```
+
+Each file contains:
+```
+MONGO_USERNAME=<username>
+MONGO_PASSWORD=<password>
+MONGO_HOST=<host>
+MONGO_PORT=<port>
+APP_NAME=<appName>
+```
+
+## Directory Structure
+
+```
+dbdump/
+├── db-dump.sh              # Main script
+├── .env.prod              # Production config (created by user)
+├── .env.uat               # UAT config (created by user)
+├── .env.example           # Example configuration
+├── .gitignore             # Git ignore rules
+├── README.md              # This file
+└── dumps/                 # Created automatically
+    ├── prod/
+    │   ├── 20260414_1632/
+    │   │   ├── admin/
+    │   │   └── myapp/
+    │   └── 20260414_1645/
+    └── uat/
+        └── 20260414_1632/
+```
+
+## Dump Output
+
+Dumps are stored with the following structure:
+
+```
+dumps/<appName>/<yyyymmdd_hhmi>/
+  admin/           # System databases
+  config/
+  myapp/           # Application databases
+  system.profile/
+```
+
+Each backup preserves the complete database structure and is ready to be restored using `mongorestore`.
+
+## Accessing Dumps
+
+To view or restore a dump:
+
+```bash
+# List recent dumps
+ls -lh dumps/prod/
+
+# Restore a dump to local MongoDB
+mongorestore --uri "mongodb://localhost:27017" dumps/prod/20260414_1632/
+
+# Copy dump to another location
+cp -r dumps/prod/20260414_1632/ /backup/prod-backup-20260414/
+```
+
+## Security
+
+- Configuration files have restricted permissions (600)
+- Credentials are stored locally in `.env.*` files
+- These files are git-ignored for security
+- Never commit `.env.*` files to version control
+
+## Requirements
+
+- **MongoDB Database Tools**: Download from https://www.mongodb.com/try/download/database-tools
+  - Specifically requires `mongodump` command
+- Bash shell
+- Network access to MongoDB server
+
+## Installation of MongoDB Database Tools
+
+### macOS
+```bash
+brew tap mongodb/brew
+brew install mongodb-database-tools
+```
+
+### Linux (Ubuntu/Debian)
+```bash
+wget https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2004-x86_64-100.8.0.tgz
+tar -xzf mongodb-database-tools-ubuntu2004-x86_64-100.8.0.tgz
+sudo cp mongodb-database-tools-ubuntu2004-x86_64-100.8.0/bin/* /usr/local/bin/
+```
+
+### Windows
+Download the MSI installer from https://www.mongodb.com/try/download/database-tools and run it.
+
+## Troubleshooting
+
+### mongodump not found
+```bash
+# Check if MongoDB Database Tools is installed
+mongodump --version
+
+# If not installed, see "Installation" section above
+```
+
+### Connection refused
+- Verify host and port are correct
+- Check network connectivity to MongoDB server
+- Ensure firewall allows access
+
+### Authentication failed
+- Verify username and password
+- Check the user has admin permissions
+- Confirm the `authSource=admin` parameter
+
+### Port already displaying in error
+The connection string is checked for errors. If you see connection errors, the script displays the exact MongoDB error message.
+
+## Advanced Usage
+
+### Manual mongodump command (for reference)
+
+The script constructs and runs this command automatically:
+
+```bash
+mongodump --uri "mongodb://<username>:<password>@<host>:<port>/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<appName>@" -o ./dumps/<appName>/<yyyymmdd_hhmm>
+```
+
+### Scheduling automated backups
+
+You can schedule regular backups using cron (Linux/macOS):
+
+```bash
+# Add to crontab
+crontab -e
+
+# Daily dump at 3 AM for production environment
+0 3 * * * cd /path/to/dbdump && ./db-dump.sh dump << EOF
+1
+EOF
+```
+
+## Support
+
+For MongoDB connection issues, refer to:
+- MongoDB Documentation: https://docs.mongodb.com/
+- Connection String Reference: https://docs.mongodb.com/manual/reference/connection-string/
+
+## About
+
+**Author:** Julien Gautier ([jgautier.webdev@gmail.com](mailto:jgautier.webdev@gmail.com))
+
+**Organization:** AdAstra
+
+**Project:** adastra_scripts
+
+This utility was created to enable efficient backup and versioning of MongoDB databases from remote servers for AdAstra projects.