{"id":16614,"library":"dbdock","title":"DBDock: Database Backup, Restore, and Migration","description":"DBDock is an enterprise-grade, CLI-first tool designed for comprehensive database operations, including backup, restore, cross-database migration (MongoDB ↔ PostgreSQL), and database copying. Currently at version 1.1.26, it offers a streamlined approach to repetitive database tasks, aiming to replace custom scripts with single commands. Key differentiators include its 'beautiful CLI' with real-time progress, built-in AES-256 encryption, Brotli compression, and support for multiple cloud storage providers like S3, R2, and Cloudinary. It provides interactive setup, intelligent filtering for operations like restore, and features like retention policies and email/Slack alerts. While primarily a command-line utility, DBDock also offers a programmatic TypeScript API, particularly for integration within NestJS applications, leveraging its peer dependencies on `@nestjs/common` and `@nestjs/core`. This allows developers to embed its powerful features directly into their Node.js applications and manage features like cron schedules programmatically.","status":"active","version":"1.1.26","language":"javascript","source_language":"en","source_url":"https://github.com/naheemolaide/dbdock-support","tags":["javascript","postgresql","postgres","mongodb","migration","cross-database","schema-migration","backup","restore","typescript"],"install":[{"cmd":"npm install dbdock","lang":"bash","label":"npm"},{"cmd":"yarn add dbdock","lang":"bash","label":"yarn"},{"cmd":"pnpm add dbdock","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for programmatic integration, especially within NestJS applications.","package":"@nestjs/common","optional":true},{"reason":"Peer dependency for programmatic integration, especially within NestJS applications.","package":"@nestjs/core","optional":true}],"imports":[{"note":"Used to initialize the DBDock context for programmatic access, reading configuration from `dbdock.config.json` and environment variables. ESM import is preferred.","wrong":"const { createDBDock } = require('dbdock');","symbol":"createDBDock","correct":"import { createDBDock } from 'dbdock';"},{"note":"Acquired from the initialized DBDock context (e.g., `dbdockContext.get(BackupService)`), this service provides methods for managing backups programmatically. Requires `createDBDock` first.","wrong":"const { BackupService } = require('dbdock');","symbol":"BackupService","correct":"import { BackupService } from 'dbdock';"},{"note":"The primary and recommended method of interaction for most users is via the command-line interface using `npx` or a global `npm install -g dbdock`.","wrong":"import { dbdock } from 'dbdock'; // This package is primarily a CLI tool; 'dbdock' is not a direct JavaScript function export.","symbol":"dbdock (CLI)","correct":"npx dbdock <command>"}],"quickstart":{"code":"npx dbdock init\n# Follow the interactive prompts to set up database connection, storage, encryption, and alerts.\n# This creates dbdock.config.json (non-sensitive) and .env (secrets).\n\n# Create a full backup with encryption and compression, streaming directly to configured storage.\n# Real-time progress is shown in the terminal.\nnpx dbdock backup\n\n# Restore a backup interactively, with smart filtering for many backups.\nnpx dbdock restore","lang":"bash","description":"Demonstrates the initial setup process and fundamental backup/restore operations using the CLI."},"warnings":[{"fix":"Ensure Node.js >=18.0.0 is installed. For PostgreSQL client tools, use `brew install postgresql` on macOS or `sudo apt-get install postgresql-client` on Ubuntu/Debian.","message":"DBDock requires Node.js 18 or higher and specific PostgreSQL client tools (`pg_dump`, `pg_restore`, `psql`) to be installed on the system path. Failure to meet these prerequisites will result in runtime errors for database operations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run `npx dbdock init` once for guided setup that automatically handles `.env` and `.gitignore`. Explicitly set `DBDOCK_DB_URL` and other sensitive variables as environment variables, not in `dbdock.config.json`.","message":"Configuration management uses a hybrid approach: non-sensitive settings go into `dbdock.config.json` (safe to commit), while sensitive secrets (e.g., database URLs, API keys) are stored in `.env` files (must be `.gitignore`d). Mismanaging these can expose credentials.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For active scheduling, you must integrate DBDock programmatically into a running Node.js application (e.g., a NestJS service) that can manage and trigger the cron tasks based on the configured schedules.","message":"Scheduled backups managed via `dbdock schedule` only execute when DBDock is integrated and running within a Node.js application. The CLI commands merely configure the schedule, but do not actively run the cron jobs themselves.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run `npx dbdock migrate-config` to automatically extract secrets from `dbdock.config.json` to a `.env` file and update your `.gitignore` to prevent committing them.","message":"Older versions might have stored sensitive secrets directly in `dbdock.config.json`. This is deprecated due to security risks.","severity":"deprecated","affected_versions":"<1.1.0 (approx)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Either install DBDock globally (`npm install -g dbdock`) or use `npx` to execute commands (`npx dbdock <command>`).","cause":"The `dbdock` command is not available in the system's PATH or `npx` is not being used.","error":"command not found: dbdock"},{"fix":"Install the PostgreSQL client tools for your operating system (e.g., `brew install postgresql` on macOS, `sudo apt-get install postgresql-client` on Debian/Ubuntu).","cause":"The PostgreSQL client tools (specifically `pg_dump`, `pg_restore`, `psql`) are not installed or not accessible in the system's PATH.","error":"Error: pg_dump: command not found"},{"fix":"Set the `DBDOCK_DB_URL` environment variable in your shell or a `.env` file, or run `npx dbdock init` to configure your database connection interactively.","cause":"DBDock requires a database connection URL, typically provided via `DBDOCK_DB_URL` or `DATABASE_URL` environment variables, or configured interactively via `dbdock init`.","error":"Error: Missing required environment variable: DBDOCK_DB_URL"}],"ecosystem":"npm"}