adastra_scripts/dbdump_mongo/README.md

# 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

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

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

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

```bash
# 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
```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

### mongodump not found
```bash
# 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:

```bash
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):

```bash
# 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](mailto: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.