From dfd8f7b22b8101de3db532fa8e001c4488e3c5ff Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Tue, 28 Apr 2026 21:26:23 +0200 Subject: [PATCH] dbrestore initial commit --- dbrestore_mongo/.env.example | 14 ++ dbrestore_mongo/.gitignore | 10 ++ dbrestore_mongo/README.md | 277 ++++++++++++++++++++++++++++++ dbrestore_mongo/db-restore.sh | 312 ++++++++++++++++++++++++++++++++++ 4 files changed, 613 insertions(+) create mode 100644 dbrestore_mongo/.env.example create mode 100644 dbrestore_mongo/.gitignore create mode 100644 dbrestore_mongo/README.md create mode 100755 dbrestore_mongo/db-restore.sh diff --git a/dbrestore_mongo/.env.example b/dbrestore_mongo/.env.example new file mode 100644 index 0000000..0385e8a --- /dev/null +++ b/dbrestore_mongo/.env.example @@ -0,0 +1,14 @@ +# MongoDB Restore Configuration +# Copy this file to .env and update with your values +# This configuration should match your local MongoDB instance + +# MongoDB credentials (for the target database) +MONGO_USERNAME=admin +MONGO_PASSWORD=password +MONGO_HOST=localhost +MONGO_PORT=27017 +MONGO_DATABASE=adastradb +MONGO_AUTHSOURCE=admin + +# Note: The connection string will be constructed as: +# mongodb://:@:/?authSource= diff --git a/dbrestore_mongo/.gitignore b/dbrestore_mongo/.gitignore new file mode 100644 index 0000000..1a857c0 --- /dev/null +++ b/dbrestore_mongo/.gitignore @@ -0,0 +1,10 @@ +# Environment configuration file (contains sensitive credentials) +.env +!.env.example + +# OS files +.DS_Store +Thumbs.db + +# Logs +*.log diff --git a/dbrestore_mongo/README.md b/dbrestore_mongo/README.md new file mode 100644 index 0000000..bc25847 --- /dev/null +++ b/dbrestore_mongo/README.md @@ -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://:@:/?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. diff --git a/dbrestore_mongo/db-restore.sh b/dbrestore_mongo/db-restore.sh new file mode 100755 index 0000000..2018ad9 --- /dev/null +++ b/dbrestore_mongo/db-restore.sh @@ -0,0 +1,312 @@ +#!/bin/bash + +# Author: Julien Gautier +# Organization: AdAstra +# Project: adastra_scripts +# +################################################################################ +# MongoDB Restore Utility Script (Standalone) +# +# This script restores MongoDB database dumps from backup files. +# It provides interactive navigation through dump directories and restores +# to a configured MongoDB instance. +# +# Usage: ./db-restore.sh +# +# Configuration: +# Requires .env file with MongoDB connection details: +# - MONGO_USERNAME +# - MONGO_PASSWORD +# - MONGO_HOST +# - MONGO_PORT +# - MONGO_DATABASE +# - MONGO_AUTHSOURCE +# +# Example command (what the script executes): +# mongorestore --uri "mongodb://user:pass@host:port/db?authSource=admin" /path/to/dumps +# +################################################################################ + +set -e + +# Configuration +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ENV_FILE="${SCRIPT_DIR}/.env" + +# Global variables +SELECTED_DUMP_PATH="" + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +NC='\033[0m' + +# Helper functions +print_info() { + echo -e "${BLUE}┣━${NC} ${CYAN}${1}${NC}" +} + +print_success() { + echo -e "${GREEN}✓ ${1}${NC}" +} + +print_error() { + echo -e "${RED}✗ ${1}${NC}" +} + +print_warning() { + echo -e "${YELLOW}⚠ ${1}${NC}" +} + +print_separator() { + echo -e "${BLUE}┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +} + +print_separator_up() { + echo -e "${BLUE}┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +} + +print_separator_down() { + echo -e "${BLUE}┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +} + +print_section() { + echo + print_separator_up + print_info "$1" + print_separator_down + echo +} + +check_mongorestore() { + if ! command -v mongorestore &> /dev/null; then + print_error "mongorestore is not installed or not in PATH" + print_info "Install MongoDB Database Tools from: https://www.mongodb.com/try/download/database-tools" + exit 1 + fi + print_success "mongorestore found: $(mongorestore --version | head -1)" +} + +check_env_file() { + if [[ ! -f "$ENV_FILE" ]]; then + print_error "Configuration file not found: $ENV_FILE" + print_info "Please create .env file with the following variables:" + print_info " MONGO_USERNAME=" + print_info " MONGO_PASSWORD=" + print_info " MONGO_HOST=" + print_info " MONGO_PORT=" + print_info " MONGO_DATABASE=" + print_info " MONGO_AUTHSOURCE=" + print_info "You can copy from .env.example" + exit 1 + fi +} + +load_config() { + # shellcheck source=/dev/null + source "$ENV_FILE" + + # Validate required variables + if [[ -z "$MONGO_USERNAME" ]] || [[ -z "$MONGO_PASSWORD" ]] || [[ -z "$MONGO_HOST" ]] || \ + [[ -z "$MONGO_PORT" ]] || [[ -z "$MONGO_DATABASE" ]] || [[ -z "$MONGO_AUTHSOURCE" ]]; then + print_error "Missing required configuration variables in .env file" + exit 1 + fi +} + +has_bson_files() { + local dir="$1" + [[ -n $(find "$dir" -maxdepth 1 -type f -name "*.bson" 2>/dev/null | head -1) ]] +} + +has_subdirectories() { + local dir="$1" + [[ -n $(find "$dir" -maxdepth 1 -type d ! -name "." ! -name ".." 2>/dev/null | head -1) ]] +} + +navigate_to_dump() { + SELECTED_DUMP_PATH="" + local current_path="$1" + + # Expand ~ in path + current_path="${current_path/#\~/$HOME}" + + # Check if path exists + if [[ ! -d "$current_path" ]]; then + print_error "Path does not exist: $current_path" + return 1 + fi + + # If this directory has BSON files, we're at the right level + if has_bson_files "$current_path"; then + SELECTED_DUMP_PATH="$current_path" + return 0 + fi + + # If no subdirectories and no BSON files, this isn't a valid dump directory + if ! has_subdirectories "$current_path"; then + print_error "No BSON files found and no subdirectories in: $current_path" + return 1 + fi + + # Navigate through subdirectories + while true; do + print_separator_up + print_info "Select Dump Directory" + print_separator_down + echo + print_info "Current location: $current_path" + echo + + # Get list of subdirectories + local subdirs=() + local count=0 + + # Read subdirectories into array (null-terminated, excluding . and ..) + while IFS= read -r -d '' subdir; do + subdirs+=("$subdir") + echo " $((++count))) $(basename "$subdir")" + done < <(find "$current_path" -maxdepth 1 -mindepth 1 -type d -print0 | sort -z) + + if [[ $count -eq 0 ]]; then + print_error "No subdirectories found in: $current_path" + return 1 + fi + + echo + echo -n "Enter your choice (1-$count): " + read choice + + if [[ "$choice" =~ ^[0-9]+$ ]] && [[ $choice -ge 1 ]] && [[ $choice -le $count ]]; then + current_path="${subdirs[$((choice - 1))]}" + + # Check if this directory has BSON files + if has_bson_files "$current_path"; then + SELECTED_DUMP_PATH="$current_path" + return 0 + fi + + # If no more subdirectories and no BSON files, error + if ! has_subdirectories "$current_path"; then + print_error "No BSON files found in: $current_path" + return 1 + fi + # Continue loop to show next level + else + print_error "Invalid choice" + fi + done +} + +get_backup_summary() { + local dump_path="$1" + local bson_count=$(find "$dump_path" -name "*.bson" -type f 2>/dev/null | wc -l) + local total_size=$(du -sh "$dump_path" 2>/dev/null | cut -f1) + + echo "Backup files: $bson_count" + echo "Total size: $total_size" +} + +show_summary() { + local dump_path="$1" + + print_section "Restore Summary" + + echo "MongoDB Connection:" + echo " Host: $MONGO_HOST" + echo " Port: $MONGO_PORT" + echo " Username: $MONGO_USERNAME" + echo " Database: $MONGO_DATABASE" + echo " AuthSource: $MONGO_AUTHSOURCE" + echo + echo "Backup Source:" + echo " Location: $dump_path" + echo " $(get_backup_summary "$dump_path")" + echo + echo "Connection string:" + echo " mongodb://:@$MONGO_HOST:$MONGO_PORT/$MONGO_DATABASE?authSource=$MONGO_AUTHSOURCE" + echo +} + +confirm_restore() { + echo -n "Do you want to proceed with the restore? (yes/no): " + read response + [[ "$response" == "yes" ]] +} + +perform_restore() { + local dump_path="$1" + + print_separator_up + print_info "Starting MongoDB Restore..." + print_separator_down + echo + + # Construct connection string + local connection_uri="mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}/${MONGO_DATABASE}?authSource=${MONGO_AUTHSOURCE}" + + # Perform restore + if mongorestore --uri "$connection_uri" "$dump_path" 2>&1; then + print_success "Restore completed successfully" + return 0 + else + print_error "Restore operation failed" + return 1 + fi +} + +main() { + print_separator_up + print_info "MongoDB Restore Utility" + print_separator_down + + # Initial checks + check_mongorestore + check_env_file + load_config + + print_success "Configuration loaded" + echo + + # Ask for initial dump path + print_info "Enter the path to the dumps directory" + echo " Example: ~/Works/dbdump/dumps" + echo + echo -n "Dumps path: " + read dumps_path + + if [[ -z "$dumps_path" ]]; then + print_error "Dumps path cannot be empty" + return 1 + fi + + # Navigate to the correct dump directory + print_info "Navigating to backup location..." + navigate_to_dump "$dumps_path" + if [[ $? -ne 0 ]]; then + print_error "Failed to select backup directory" + return 1 + fi + + # Show summary of what will be restored + show_summary "$SELECTED_DUMP_PATH" + + # Ask for confirmation + if ! confirm_restore; then + print_info "Restore operation cancelled" + return 1 + fi + + # Perform the restore + if perform_restore "$SELECTED_DUMP_PATH"; then + print_success "Restore operation completed" + else + print_error "Restore operation failed" + return 1 + fi +} + +main "$@"