CLI Commands

Comprehensive guide to DBDock CLI commands

init — Set up in 30 seconds

Run once. It walks you through everything interactively.

npx dbdock init

It asks for your database connection, picks your storage (Local, S3, R2, Cloudinary), sets up encryption if you want it, and optionally configures Slack/Email alerts.

What happens under the hood:

• Config (safe stuff) goes to dbdock.config.json — commit this
• Secrets go to .env — never committed, .gitignore updated automatically

You can also run without a config file: set DBDOCK_DB_URL (or DATABASE_URL) and other env vars and DBDock will use env-only configuration.

migrate-config — Fix legacy configs

npx dbdock migrate-config

Got secrets sitting in dbdock.config.json from an older version? This extracts them to .env, cleans up your config, and updates .gitignore. One command, done.

backup — One command, full backup

Real-time progress. Streams directly to your storage provider. Done.

npx dbdock backup [options]

Options

Option	Description
--encrypt / --no-encrypt	Toggle encryption (overrides config)
--compress / --no-compress	Toggle compression (overrides config)
--encryption-key <key>	Specify a 64-char hex encryption key
--compression-level <1-11>	Set compression level (default: 6)

Example

npx dbdock backup --encrypt --compress --compression-level 9

Backup Formats

DBDock supports multiple PostgreSQL backup formats:

• custom (default) - PostgreSQL custom binary format (.sql)
• plain - Plain SQL text format (.sql)
• directory - Directory format (.dir)
• tar - Tar archive format (.tar)

Generate Encryption Key

Generate a secure 64-character hexadecimal encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

The key must be exactly 64 hexadecimal characters (0-9, a-f, A-F).

restore — Interactive restore with smart filtering

npx dbdock restore

Got 200+ backups? It auto-enables smart filtering — search by date, keyword, or just grab the most recent ones. No scrolling through walls of text. You can also restore to a completely different database; pick “New Database Instance (Migrate)” when prompted and enter the target connection details.

Smart filtering:

• Show recent (last 10)
• Date range (24h, 7d, 30d, 90d, custom)
• Search by keyword/ID

Migration Support:

You can choose to restore to a New Database Instance during the restore process. This is perfect for migrating data between servers (e.g., from staging to production or local to cloud).

1. Run npx dbdock restore
2. Select a backup
3. Choose “New Database Instance (Migrate)”
4. Enter connection details for the target database

Shows database stats and requires confirmation before restore.

list — See all your backups

npx dbdock list [options]

Options

Option	Description
--recent <number>	Show the last N backups
--search <keyword>	Search backups by keyword or ID
--days <number>	Show backups from the last N days

Examples

npx dbdock list --recent 10
npx dbdock list --search "pre-deploy"

Auto-filters when you have 50+ backups so the output stays clean.

copydb — Copy a database with just two URLs

No config files. No setup. Just paste two PostgreSQL URLs.

npx dbdock copydb "postgresql://user:pass@source:5432/mydb" "postgresql://user:pass@target:5432/mydb"

It tests both connections, shows you the source DB size and table count, warns you if the target has existing data, and asks for confirmation before doing anything. Streams pg_dump directly into pg_restore — no temp files, no waiting.

Options

Option	Description
--schema-only	Copy tables, indexes, constraints — no data
--data-only	Copy data only (schema must exist on target)
--verbose	Show detailed pg_dump/pg_restore output

Environment consolidation

npx dbdock copydb "prod_url" "staging_url"
npx dbdock copydb "staging_url" "prod_url"
npx dbdock copydb "prod_url" "postgresql://postgres:pass@localhost:5432/myapp"
npx dbdock copydb --schema-only "prod_url" "staging_url"

Perfect for moving between Neon, Supabase, Railway, RDS, or any Postgres host.

delete — Remove backups

npx dbdock delete              # Interactive picker
npx dbdock delete --key <id>   # Delete specific backup
npx dbdock delete --all        # Nuke everything (with confirmation)

cleanup — Auto-clean old backups

npx dbdock cleanup              # Interactive with preview
npx dbdock cleanup --dry-run    # See what would be deleted
npx dbdock cleanup --force      # Skip confirmation

Shows you exactly what gets deleted and how much space you reclaim before doing anything.

schedule — Manage cron schedules

dbdock schedule

Add, remove, or toggle backup schedules. Comes with presets (hourly, daily at midnight, daily at 2 AM, weekly, monthly) or use a custom cron expression. Saves to dbdock.config.json.

Heads up: Schedules only run when DBDock is integrated into your Node.js app (see Programmatic Usage). The CLI just manages the config.

analyze — Understand your database first

npx dbdock analyze "mongodb://localhost:27017/myapp"
npx dbdock analyze "postgresql://user:pass@localhost:5432/myapp"

Scans the source database and shows collections/tables, field types, nested structures, and inconsistencies. Use before running a cross-database migration.

migrate — Cross-database migration (MongoDB ↔ PostgreSQL)

npx dbdock migrate "mongodb://localhost:27017/myapp" "postgresql://user:pass@localhost:5432/myapp"

DBDock analyzes the source, generates a schema mapping proposal, and presents it for review before touching anything. Supports --dry-run, --incremental --since <date>, --config, --export-config, --batch-size, --max-depth. Failed rows go to _migration_errors; nothing executes without your confirmation.

status — Check schedules and service health

dbdock status

Example Output

📅 Scheduled Backups:

┌─────┬──────────────┬─────────────────┬──────────┐
│  #  │ Name         │ Cron Expression │ Status   │
├─────┼──────────────┼─────────────────┼──────────┤
│   1 │ daily        │ 0 * * * *       │ ✓ Active │
│   2 │ weekly       │ 0 0 * * 0       │ ✗ Paused │
└─────┴──────────────┴─────────────────┴──────────┘

Total: 2 schedule(s) - 1 active, 1 paused

🚀 Service Status:

🟢 Running (PM2)
  PID: 12345
  Uptime: 2d 5h
  Memory: 45.23 MB

test — Verify everything works

npx dbdock test

Tests your database connection, storage provider, and alert config. Run this first if something feels off.