adastra_scripts/dbrestore_mongo

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:

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

./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:

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

brew tap mongodb/brew
brew install mongodb-database-tools

Linux (Ubuntu/Debian)

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

# Check if MongoDB Database Tools is installed
mongorestore --version

# If not installed, see "Installation" section above

.env file not found

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

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:

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

Organization: AdAstra

Project: adastra_scripts

This utility was created to simplify the restoration of MongoDB database backups to local development environments for AdAstra projects.