CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A collection of standalone Bash utility scripts for MongoDB operations (backup, restore, local dev environment). No build system, package manager, or test suite — each module is a self-contained shell script.

Modules

Module	Script	Purpose
`dbdump_mongo/`	`db-dump.sh`	Dump MongoDB databases across multiple named environments
`dbrestore_mongo/`	`db-restore.sh`	Restore a MongoDB dump to a target instance
`dbutils_mongo/`	`db-start.sh`	Spin up a local MongoDB + Mongo Express via Docker

Running the Scripts

# Backup — interactive environment picker
cd dbdump_mongo && bash db-dump.sh

# Restore — interactive backup directory navigator
cd dbrestore_mongo && bash db-restore.sh

# Local dev database — Docker-based
cd dbutils_mongo && bash db-start.sh up       # start
cd dbutils_mongo && bash db-start.sh down      # stop
cd dbutils_mongo && bash db-start.sh status
cd dbutils_mongo && bash db-start.sh logs
cd dbutils_mongo && bash db-start.sh clean     # remove volumes
cd dbutils_mongo && bash db-start.sh reconfigure

Environment Setup

Each module requires a .env file (copied from the corresponding .env.example). The .env files are git-ignored. dbdump_mongo supports multiple named environments stored as .env.<name> files with chmod 600 permissions.

Architecture Patterns

All three scripts share the same conventions:

Sub-command dispatch: a main() function routes $1 to cmd_<action>() functions.
Colored output: ANSI escape codes (\033[...m) for styled terminal output; consistent separator lines.
Prerequisite checks: each script validates its required tools (mongodump, mongorestore, docker, docker compose) at startup and exits early with a clear message if missing.
Interactive prompts: read -p / select menus guide the user through environment selection, directory navigation, and confirmation steps before any destructive action.

dbdump_mongo — multi-environment credential model

Named environments are stored as .env.<name> files alongside the main .env. Credentials include MONGO_USERNAME, MONGO_PASSWORD, MONGO_HOST, MONGO_PORT, APP_NAME. Dumps land in ./dumps/<appName>/<yyyymmdd_hhmm>/. The script generates MongoDB Atlas-compatible connection strings (ssl, replicaSet flags).

The script walks through backup directory hierarchies interactively. It detects valid restore targets by checking for .bson files (has_bson_files()). Before executing mongorestore, it shows a summary of connection details and the selected backup path and requires explicit confirmation.

dbutils_mongo — Docker Compose orchestration

Runs two containers on a dbutils-network bridge: MongoDB (configurable port, default MONGO_PORT) and Mongo Express (default port 8081). Data is persisted in named volumes mongodb-data and mongodb-config. On first run, setup_credentials() prompts interactively and writes .env. The mongo-init.js initializer creates a dataImportHistory collection with indexes on importDate and status.

External Dependencies

mongodump / mongorestore — MongoDB Database Tools (must be installed separately)
docker + docker compose (v2 plugin syntax)
bash (scripts use bash-specific features, not POSIX sh)

3.5 KiB Raw Blame History