db-helper

db-helper is a standalone TypeScript CLI for safe Mongo backup, sync, restore, recovery, and maintenance operations across development, test, and production. The executable command is dbh.

Setup

The standalone setup flow is now:

1. dbh init
2. dbh config validate
3. dbh doctor

Init Walkthrough

dbh init creates a config at the default user location unless you pass --config <path>.

Press Enter to accept the default shown in brackets.

Prompt-by-prompt:

# Mongo auth database used by generated connection URIs
Mongo auth source [admin]:

Use admin unless your Mongo users authenticate against a different auth DB.

# default restore behavior for commands that still honor this setting
Default drop on restore [true]:

Use true unless you have a specific reason to keep restore non-dropping by default.

# local directory where db-helper stores backup folders
Backup root [/tmp/db-helper-backups]:

Use a durable path if you want backups to survive reboots and temp cleanup.

# temp working directory for archives and intermediate files
Temp root [/tmp/db-helper]:

Usually the default is fine.

Development prompts:

# human label shown in menus and output
development label [Local Development]:

# local or remote
development kind [local]:

For a normal local development database, keep local.

# machine or DNS name for the environment
development host [localhost]:

# Mongo host used in the connection string
development mongo host [localhost]:

# Mongo TCP port
development mongo port [27017]:

# actual database name on the server
development database name [development]:

# Mongo username
development mongo user []:

# Mongo password
development mongo password []:

Test prompts use the same database fields, plus SSH:

# human label shown in menus and output
test label [Test Server]:

# local or remote
test kind [remote]:

For a hosted test server, keep remote.

# SSH host / machine hostname
test host [test.example.com]:

# Mongo host as seen from that remote machine
test mongo host [localhost]:

# Mongo TCP port on the remote machine
test mongo port [27017]:

# database name on test
test database name [development]:

# Mongo username on test
test mongo user []:

# Mongo password on test
test mongo password []:

# SSH username
test ssh user []:

Leave this blank if your SSH host alias or local SSH config supplies the user.

# SSH private key path
test ssh key path []:

Leave this blank to use your SSH agent, macOS keychain-backed identities, or ~/.ssh/config.

Production prompts are the same shape:

# human label shown in menus and output
production label [Production Server]:

# local or remote
production kind [remote]:

# SSH host / machine hostname
production host [prod.example.com]:

# Mongo host as seen from that remote machine
production mongo host [localhost]:

# Mongo TCP port
production mongo port [27017]:

# production database name
production database name [production]:

# production Mongo username
production mongo user []:

# production Mongo password
production mongo password []:

# production SSH username
production ssh user []:

Leave this blank if your SSH host alias or local SSH config supplies the user.

# production SSH private key path
production ssh key path []:

Leave this blank to use your SSH agent, macOS keychain-backed identities, or ~/.ssh/config.

Current limitation:

• passwords are currently visible while typing

Typical first-run flow:

# install the CLI globally
npm install -g @dodefey/db-helper

# create the config interactively
dbh init

# validate config shape
dbh config validate

# validate tooling and connectivity
dbh doctor

If you already have the old env-file format, import it instead:

# import a legacy env file into config.json format
dbh init --from-env-file /path/to/.env

By default, the CLI looks for configuration in this order:

• ./config.json
• ~/.config/db-helper/config.json
• a repo-local fallback config during development

You can always override that with --config <path>.

Install

# install the published CLI globally for normal operator use
npm install -g @dodefey/db-helper

# bootstrap the user-level config interactively
dbh init

# validate config shape without network checks
dbh config validate

# validate config and connectivity
dbh doctor

For repo-local development, you can still install from the current checkout instead:

# install directly from the current repo checkout
npm install -g .

# show which config file dbh will use
dbh config path

# inspect config safely with secrets redacted
dbh config show --redacted

# import a config from the legacy env-file format
dbh init --from-env-file /path/to/.env

# run the CLI in place during development
npm install && npm start -- --help

# validate a non-default config file explicitly
dbh config validate --config /path/to/config.json

Command Reference

# open the interactive workflow menu
dbh interactive

# create a timestamped backup
dbh backup create --from production

# list backups, newest first
dbh backup list

# inspect one backup manifest
dbh backup inspect --backup 2026-03-16T10-30-00-production

# sync between allowed environments
dbh sync --from production --to development --yes

# restore a full backup
dbh restore full --backup 2026-03-16T10-30-00-production --to development --yes

# restore a single collection
dbh restore collection --backup 2026-03-16T10-30-00-production --collection orders --to test --yes

# guided recovery workflow
dbh recover

# validate local tooling and connectivity
dbh doctor

Backup

backup is the command for capturing a full snapshot of one configured environment into a local archive plus manifest. In practice, it is most useful before risky work, before replacing a target with sync or restore, or when you want to preserve a known-good production snapshot for later recovery.

It creates a timestamped backup directory under the configured backup root, writes dump.archive.gz, writes manifest.json, and validates the result before reporting success. If backup creation fails or is interrupted, dbh treats the result as invalid and attempts cleanup of incomplete artifacts.

Usage

Run doctor first if tooling, SSH, or database connectivity is in doubt.

Common workflows:

# create a production backup before maintenance
dbh backup create --from production

# create a manual recovery point before syncing into development
dbh backup create --from development --note "pre-sync recovery point" --tag pre-sync

# create a known-good snapshot with a note and tag
dbh backup create --from production --note "known good after deploy" --tag known-good

# list backups for one environment
dbh backup list --from production

# inspect one backup manifest before restore or review
dbh backup inspect --backup 2026-03-16T10-30-00-production

If backup create is interrupted during archive creation, manifest write, or validation, do not trust the partial result. The command will attempt cleanup, but an interrupted run should be treated as not having produced a usable backup unless it completed successfully.

Backup API

CLI forms:

dbh backup create --from <environment> [--note <text>] [--tag <tag>] [--quiet] [--verbose]
dbh backup list [--from <environment>] [--tag <tag>]
dbh backup inspect --backup <backup-name>

Required flags:

• backup create: --from
• backup inspect: --backup

Optional flags:

• backup create: --note, --tag, --quiet, --verbose
• backup list: --from, --tag

Output modes for backup create:

• --quiet reduces normal operator output
• --verbose allows raw subprocess output

Sync

sync is the command for refreshing one non-production database from another environment. In practice, that usually means replacing development or test with a fresh copy of production, or moving data between development and test.

It is a full-database replacement workflow, not a merge or replication tool. sync will copy the source database, restore it into the target with drop enabled, verify the result, and try to clean up temporary artifacts afterward. It never syncs into production, it does not support collection-only syncs, and an interrupted restore can still leave the target in a dirty state.

Usage

Run doctor first if tooling, SSH, or database connectivity is in doubt. If the target matters and you want a recovery point, create a backup before running sync.

Common workflows:

# refresh development from production
dbh sync --from production --to development

# refresh test from production without a confirmation prompt
dbh sync --from production --to test --yes

# move test data into development
dbh sync --from test --to development --yes

# create a manual backup of the target before syncing
dbh backup create --from development

If sync is interrupted during restore or verify, treat the target as dirty. The normal recovery path is to rerun sync from a known-good source or restore the target from backup.

Sync API

CLI form:

dbh sync --from <environment> --to <environment> [--yes] [--quiet] [--verbose]

Required flags:

• --from
• --to

Optional flags:

• --yes
• --quiet
• --verbose

Allowed paths:

• production -> development
• production -> test
• development -> test
• test -> development

Blocked paths:

• any sync into production
• self-syncs such as development -> development
• any path not explicitly listed above

Output modes:

• --quiet reduces normal operator output
• --verbose allows raw subprocess output

Operator expectations:

• interruption during dump means the target database was not modified
• interruption during restore or verify means the target database may be dirty
• if the target may be dirty, restore it from a known good backup or rerun sync before trusting it
• if target recovery matters, create a backup explicitly before running sync

Restore

restore is the command for applying a named backup to a target environment. In practice, it is most useful when you want to recover development, test, or production from a known-good backup, or when you need to restore one collection without replacing the full database.

It is a backup-to-target recovery workflow, not a merge tool. restore full validates the named backup, replaces the target with drop enabled, verifies the result, and enforces stronger safeguards for production. restore collection restores only one named collection from the backup with drop enabled.

Usage

Run doctor first if tooling, SSH, or database connectivity is in doubt. Before restoring into production, review the backup manifest with backup inspect so you know exactly which snapshot you are applying.

Common workflows:

# restore a known-good production backup into development
dbh restore full --backup 2026-03-16T10-30-00-production --to development

# restore a test environment from a known backup without a confirmation prompt
dbh restore full --backup 2026-03-16T10-30-00-production --to test --yes

# restore one collection from a backup into development
dbh restore collection --backup 2026-03-16T10-30-00-production --collection orders --to development

# restore production from a named backup with the required production safeguards
dbh restore full --backup 2026-03-16T10-30-00-production --to production --force-production-restore

If restore is interrupted during restore or verify, treat the target as dirty. The safe recovery path is to rerun the restore from a known-good backup or restore the target again before trusting it.

Restore API

CLI forms:

dbh restore full --backup <backup-name> --to <environment> [--yes] [--skip-pre-backup] [--force-production-restore] [--quiet] [--verbose]
dbh restore collection --backup <backup-name> --collection <name> --to <environment> [--yes] [--force-production-restore] [--quiet] [--verbose]

Required flags:

• restore full: --backup, --to
• restore collection: --backup, --collection, --to

Optional flags:

• restore full: --yes, --skip-pre-backup, --force-production-restore, --quiet, --verbose
• restore collection: --yes, --force-production-restore, --quiet, --verbose

Production restore expectations:

• restore full --to production requires --force-production-restore
• restore collection --to production requires --force-production-restore
• interactive production restore requires an additional typed confirmation
• production restore creates a pre-restore production backup by default
• --skip-pre-backup bypasses that automatic production backup

Output modes:

• --quiet reduces normal operator output
• --verbose allows raw subprocess output

Safety Model

• Sync is only allowed for production -> development, production -> test, development -> test, and test -> development.
• Sync into production is blocked in code.
• Production restore requires a named backup, --force-production-restore for non-interactive use, and an extra typed confirmation in interactive mode.
• Production restore creates a pre-restore production backup by default.

Backup Layout

Each backup is stored under:

<DB_BACKUP_ROOT>/<backup-name>/

Required contents:

• manifest.json
• dump.archive.gz

The manifest includes the backup name, source environment, database name, timestamp, tags, note, collection list, and collection counts when available.

Recovery Guide

See RECOVERY.md for the operator-focused restore flows.