DBDock: Database Backup, Restore, and Migration

1.1.26 · active · verified Wed Apr 22

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.

Common errors

```
command not found: dbdock
```
cause The `dbdock` command is not available in the system's PATH or `npx` is not being used.

fix Either install DBDock globally (`npm install -g dbdock`) or use `npx` to execute commands (`npx dbdock <command>`).
```
Error: pg_dump: command not found
```
cause The PostgreSQL client tools (specifically `pg_dump`, `pg_restore`, `psql`) are not installed or not accessible in the system's PATH.

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).
```
Error: Missing required environment variable: DBDOCK_DB_URL
```
cause DBDock requires a database connection URL, typically provided via `DBDOCK_DB_URL` or `DATABASE_URL` environment variables, or configured interactively via `dbdock init`.

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.

Warnings

gotcha 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.
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.
gotcha 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.
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`.
gotcha 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.
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.
deprecated Older versions might have stored sensitive secrets directly in `dbdock.config.json`. This is deprecated due to security risks.
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.

Install

npm install dbdock npm
yarn add dbdock yarn
pnpm add dbdock pnpm

Imports

createDBDock
wrong:
```
const { createDBDock } = require('dbdock');
```
correct:
```
import { createDBDock } from 'dbdock';
```
Used to initialize the DBDock context for programmatic access, reading configuration from `dbdock.config.json` and environment variables. ESM import is preferred.
BackupService
wrong:
```
const { BackupService } = require('dbdock');
```
correct:
```
import { BackupService } from 'dbdock';
```
Acquired from the initialized DBDock context (e.g., `dbdockContext.get(BackupService)`), this service provides methods for managing backups programmatically. Requires `createDBDock` first.
dbdock (CLI)
wrong:
```
import { dbdock } from 'dbdock'; // This package is primarily a CLI tool; 'dbdock' is not a direct JavaScript function export.
```
correct:
```
npx dbdock <command>
```
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`.

Quickstart

Demonstrates the initial setup process and fundamental backup/restore operations using the CLI.

npx dbdock init
# Follow the interactive prompts to set up database connection, storage, encryption, and alerts.
# This creates dbdock.config.json (non-sensitive) and .env (secrets).

# Create a full backup with encryption and compression, streaming directly to configured storage.
# Real-time progress is shown in the terminal.
npx dbdock backup

# Restore a backup interactively, with smart filtering for many backups.
npx dbdock restore

view raw JSON →