adastra_scripts/dbdump_mongo

MongoDB Dump Utility

This directory contains a standalone tool for backing up MongoDB databases from remote servers. It manages multiple environment configurations for easy switching between prod, uat, and other environments.

Quick Start

First Run

./db-dump.sh dump

The script will detect no environments and guide you through creating one. Answer the prompts with:

• Environment name (required): e.g., prod, uat, staging
• MongoDB username (required): The admin user
• MongoDB password (required): The admin password
• MongoDB host (required): e.g., cluster0.mongodb.net
• MongoDB port (required): Usually 27017 or 10255
• Application name (required): Used in connection string and dump folder name

Subsequent Runs

./db-dump.sh dump

The script will show you a list of configured environments and let you choose which one to backup, or create a new environment.

Commands

# Perform a backup of a selected environment
./db-dump.sh dump

# List all configured environments
./db-dump.sh list

# Add a new environment
./db-dump.sh add

# Delete an environment
./db-dump.sh delete

# Show help
./db-dump.sh help

How It Works

1. Environment Selection: On each run, you select from existing environments or create new ones
2. Credential Storage: Each environment's credentials are stored in .env.<name> files
3. MongoDB Connection: Connects using your credentials with MongoDB Atlas parameters (ssl, replicaSet, etc.)
4. Dump Creation: Uses mongodump to create a backup
5. Timestamped Output: Dumps are organized as ./dumps/<appName>/<yyyymmdd_hhmm>/

Configuration Files

Each environment is stored in a separate file:

.env.prod       # Production environment
.env.uat        # UAT environment
.env.staging    # Staging environment (if created)

Each file contains:

MONGO_USERNAME=<username>
MONGO_PASSWORD=<password>
MONGO_HOST=<host>
MONGO_PORT=<port>
APP_NAME=<appName>

Directory Structure

dbdump/
├── db-dump.sh              # Main script
├── .env.prod              # Production config (created by user)
├── .env.uat               # UAT config (created by user)
├── .env.example           # Example configuration
├── .gitignore             # Git ignore rules
├── README.md              # This file
└── dumps/                 # Created automatically
    ├── prod/
    │   ├── 20260414_1632/
    │   │   ├── admin/
    │   │   └── myapp/
    │   └── 20260414_1645/
    └── uat/
        └── 20260414_1632/

Dump Output

Dumps are stored with the following structure:

dumps/<appName>/<yyyymmdd_hhmi>/
  admin/           # System databases
  config/
  myapp/           # Application databases
  system.profile/

Each backup preserves the complete database structure and is ready to be restored using mongorestore.

Accessing Dumps

To view or restore a dump:

# List recent dumps
ls -lh dumps/prod/

# Restore a dump to local MongoDB
mongorestore --uri "mongodb://localhost:27017" dumps/prod/20260414_1632/

# Copy dump to another location
cp -r dumps/prod/20260414_1632/ /backup/prod-backup-20260414/

Security

• Configuration files have restricted permissions (600)
• Credentials are stored locally in .env.* files
• These files are git-ignored for security
• Never commit .env.* files to version control

Requirements

• MongoDB Database Tools: Download from https://www.mongodb.com/try/download/database-tools
  • Specifically requires mongodump command
• Bash shell
• Network access to MongoDB server

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

mongodump not found

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

# If not installed, see "Installation" section above

Connection refused

• Verify host and port are correct
• Check network connectivity to MongoDB server
• Ensure firewall allows access

Authentication failed

• Verify username and password
• Check the user has admin permissions
• Confirm the authSource=admin parameter

Port already displaying in error

The connection string is checked for errors. If you see connection errors, the script displays the exact MongoDB error message.

Advanced Usage

Manual mongodump command (for reference)

The script constructs and runs this command automatically:

mongodump --uri "mongodb://<username>:<password>@<host>:<port>/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<appName>@" -o ./dumps/<appName>/<yyyymmdd_hhmm>

Scheduling automated backups

You can schedule regular backups using cron (Linux/macOS):

# Add to crontab
crontab -e

# Daily dump at 3 AM for production environment
0 3 * * * cd /path/to/dbdump && ./db-dump.sh dump << EOF
1
EOF

Support

For MongoDB connection issues, refer to:

• MongoDB Documentation: https://docs.mongodb.com/
• 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 enable efficient backup and versioning of MongoDB databases from remote servers for AdAstra projects.