dbrestore initial commit

2026-04-28 21:26:23 +02:00
parent e17c339b8e
commit dfd8f7b22b
4 changed files with 613 additions and 0 deletions
@@ -0,0 +1,277 @@
+# MongoDB Restore Utility (Standalone)
+
+This directory contains a standalone tool for restoring MongoDB database backups created with `db-dump.sh`.
+It provides interactive navigation through backup directories and restores them to a configured MongoDB instance.
+
+## Quick Start
+
+### 1. Configure Connection Details
+
+Copy the example configuration:
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your MongoDB connection details:
+```
+MONGO_USERNAME=admin
+MONGO_PASSWORD=password
+MONGO_HOST=localhost
+MONGO_PORT=27017
+MONGO_DATABASE=adastradb
+MONGO_AUTHSOURCE=admin
+```
+
+### 2. Restore a Backup
+
+```bash
+./db-restore.sh
+```
+
+The script will:
+1. Verify MongoDB tools are installed
+2. Load your configuration
+3. Ask for the path to your backups directory
+4. Guide you through the directory structure
+5. Show a summary of what will be restored
+6. Ask for confirmation
+7. Restore the backup
+
+## How It Works
+
+### Configuration
+
+The script requires a `.env` file with these variables:
+- `MONGO_USERNAME` - MongoDB admin username
+- `MONGO_PASSWORD` - MongoDB admin password
+- `MONGO_HOST` - MongoDB server hostname/IP
+- `MONGO_PORT` - MongoDB server port
+- `MONGO_DATABASE` - Target database name
+- `MONGO_AUTHSOURCE` - Authentication source (usually `admin`)
+
+### Interactive Navigation
+
+The script intelligently navigates through your backup directory structure:
+
+```
+dumps/
+├── prod/                          ← Choose this
+│   ├── 20260414_1632/             ← Then this
+│   │   └── (database folders)     ← Then this
+│   └── 20260414_1645/
+└── uat/
+    └── 20260414_1700/
+```
+
+At each level, the script:
+1. Shows available subdirectories
+2. Asks you to choose one
+3. Continues until it finds `.bson` files (backup data)
+
+### Backup Detection
+
+The script automatically stops navigation when it finds a directory containing `.bson` files, which are the actual backup data files.
+
+Example backup structure:
+```
+~/Works/dbdump/dumps/
+└── bo-uat-cosmodb/
+    └── 20260414_1732/
+        └── admin/                 ← BSON files here
+            ├── system.profile.bson
+            └── system.version.bson
+```
+
+## Example Use Case
+
+Given this backup structure:
+```
+~/Works/dbdump/dumps/
+├── bo-prod-cosmodb/
+│   └── 20260414_1600/
+│       └── AdAstra/
+│           ├── collection1.bson
+│           └── collection1.metadata.json
+└── bo-uat-cosmodb/
+    └── 20260414_1732/
+        └── AdAstra/
+            ├── orders.bson
+            └── orders.metadata.json
+```
+
+Restore process:
+```bash
+./db-restore.sh
+
+# Script asks: Dumps path: ~/Works/dbdump/dumps
+# Shows: 1) bo-prod-cosmodb  2) bo-uat-cosmodb
+# You choose: 2
+# Shows: 1) 20260414_1732
+# You choose: 1
+# Shows: 1) AdAstra
+# You choose: 1
+# Script finds BSON files and shows summary
+```
+
+## Restore Summary
+
+Before executing the restore, the script displays:
+
+```
+MongoDB Connection:
+  Host:       localhost
+  Port:       27017
+  Username:   admin
+  Database:   adastradb
+  AuthSource: admin
+
+Backup Source:
+  Location: /home/user/Works/dbdump/dumps/bo-uat-cosmodb/20260414_1732
+  Backup files: 42
+  Total size: 250M
+```
+
+You must confirm with "yes" to proceed.
+
+## Connection String
+
+The script constructs the MongoDB connection string as:
+
+```
+mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<authSource>
+```
+
+Example:
+```
+mongodb://admin:password@localhost:27017/adastradb?authSource=admin
+```
+
+## Directory Structure
+
+```
+dbrestore/
+├── db-restore.sh        # Main script
+├── .env                 # Configuration (created by you, git-ignored)
+├── .env.example        # Example configuration
+├── .gitignore          # Git ignore rules
+└── README.md           # This file
+```
+
+## Security
+
+- Configuration file (`.env`) has restricted permissions
+- Contains sensitive credentials (username, password)
+- Never commit actual `.env` file to version control
+- Use `.env.example` as template
+
+## Requirements
+
+- **MongoDB Database Tools**: Download from https://www.mongodb.com/try/download/database-tools
+  - Specifically requires `mongorestore` command
+- Bash shell
+- Network access to MongoDB server
+- Backup files created by `db-dump.sh` or `mongodump`
+
+## 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
+
+### mongorestore not found
+```bash
+# Check if MongoDB Database Tools is installed
+mongorestore --version
+
+# If not installed, see "Installation" section above
+```
+
+### .env file not found
+```bash
+# Copy the example configuration
+cp .env.example .env
+
+# Edit with your values
+nano .env  # or your favorite editor
+```
+
+### Connection refused
+- Verify host and port are correct
+- Check network connectivity to MongoDB server
+- Ensure firewall allows access
+- Verify MongoDB service is running (if local)
+
+### Authentication failed
+- Verify username and password in `.env`
+- Check user has sufficient permissions
+- Confirm `authSource` is correct (usually `admin`)
+
+### No BSON files found
+- Make sure you're pointing to the root of dumps directory
+- Navigate through subdirectories until you reach the folder with actual backup files
+- BSON files are typically deep in the directory structure
+
+## Manual Restore Command
+
+For reference, here's the command the script executes:
+
+```bash
+mongorestore --uri "mongodb://user:pass@host:port/db?authSource=admin" /path/to/dumps
+```
+
+## Related Tools
+
+- **`dbutils/db-start.sh`** - Start MongoDB in Docker for restoring locally
+- **`dbdump/db-dump.sh`** - Create backups from remote MongoDB servers
+- **`dbrestore/db-restore.sh`** - Restore backups to a MongoDB instance (this tool)
+
+## Workflow Example
+
+Complete workflow to backup and restore:
+
+```bash
+# 1. Backup from production MongoDB (in dbdump folder)
+cd ~/Works/dbdump
+./db-dump.sh dump
+# Select prod environment and wait for backup
+
+# 2. Start local MongoDB (in dbutils folder)
+cd ~/Works/dbutils
+./db-start.sh up
+
+# 3. Restore backup locally (in dbrestore folder)
+cd ~/Works/dbrestore
+./db-restore.sh
+# Navigate to the backup created in step 1 and restore
+```
+
+## Documentation
+
+For more information:
+- MongoDB Documentation: https://docs.mongodb.com/
+- mongorestore Manual: https://docs.mongodb.com/database-tools/mongorestore/
+- 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 simplify the restoration of MongoDB database backups to local development environments for AdAstra projects.