adastra_scripts/dbrestore_mongo/README.md

# 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.