Skip to main content

​
Setup your development

Learn how to set up DBDock locally and start managing your backups.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 18 or higher
  • PostgreSQL 12 or higher
  • PostgreSQL client tools (pg_dump, pg_restore, psql)
macOS
brew install postgresql
Ubuntu/Debian
sudo apt-get install postgresql-client
Windows Download from PostgreSQL Downloads

​
Initialize DBDock (30 seconds)

Run once. The interactive setup walks you through database connection, storage (Local, S3, R2, Cloudinary), encryption, and optional Slack/Email alerts. 
npx dbdock init
Security-first approach:
  • Saves non-sensitive config to dbdock.config.json (safe for git)
  • Saves secrets to .env (automatically gitignored)
  • Auto-updates .gitignore to exclude sensitive files
You can also run without a config file: set DBDOCK_DB_URL (or DATABASE_URL) and storage/encryption env vars in .env and use DBDock with env-only configuration.

​
Migrate legacy configs

Got secrets in dbdock.config.json? Run npx dbdock migrate-config — it extracts them to .env, cleans up your config, and updates .gitignore. One command, done.

​
Create a backup

Once initialized, create your first backup. Real-time progress; streams directly to your storage. Done. 
npx dbdock backup

████████████████████ | 100% | 45.23/100 MB | Speed: 12.50 MB/s | ETA: 0s | Uploading to S3
✔ Backup completed successfully

​
Restore a backup

Run the restore command, pick a backup (smart filtering if you have lots), and DBDock handles download, decryption, decompression, and restore. 
npx dbdock restore

Progress:
────────────────────────────────────────────────────────
  ✔ Downloading backup
  ✔ Decrypting data
  ✔ Decompressing data
  ⟳ Restoring to database...
────────────────────────────────────────────────────────
✔ All steps completed in 8.42s

​
Migrate to a New Database

You can also restore to a New Database Instance during the restore process. This is perfect for migrating data between servers:
  1. Run npx dbdock restore
  2. Select a backup
  3. Choose “New Database Instance (Migrate)”
  4. Enter connection details for the target database
DBDock will show database stats and require confirmation before restoring.