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:

Verify MongoDB tools are installed
Load your configuration
Ask for the path to your backups directory
Guide you through the directory structure
Show a summary of what will be restored
Ask for confirmation
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)

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:

Shows available subdirectories
Asks you to choose one
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

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.

README.md

MongoDB Restore Utility (Standalone)