65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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).
|
|
|
|
### dbrestore_mongo — backup directory navigation
|
|
|
|
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`)
|