Skip to main content

​
Setup your development

Learn how to set up DBdocks 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 DBdocks

Run the interactive setup wizard to create your secure configuration. 
npx dbdock init
This command will guide you through:
  1. Database connection: Host, port, credentials.
  2. Storage provider: Local, S3, R2, or Cloudinary.
  3. Encryption/Compression: Security settings.
  4. Email and Slack alerts: Optional notification settings.
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

​
Migrate Legacy Configurations

If you have an existing configuration with secrets embedded in dbdock.config.json, migrate to the secure approach: 
npx dbdock migrate-config
This extracts secrets from your config file, creates .env, and updates your config to use environment variables.

​
Create a Backup

Once initialized, you can create your first backup immediately. 
npx dbdock backup
You will see a real-time progress bar as your database is backed up, compressed, encrypted, and uploaded to your chosen storage. 
████████████████████ | 100% | 45.23/100 MB | Speed: 12.50 MB/s | ETA: 0s | Uploading to S3
✔ Backup completed successfully

​
Restore a Backup

Restoring is just as easy. Run the restore command to see a list of available backups. 
npx dbdock restore
Select the backup you want to restore, and DBdocks will handle the download, decryption, decompression, and restoration process. 
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.