Skip to main content
This guide takes you through setup, your first backup, and your first restore. Total time: about 5 minutes.
Haven’t installed DBdock yet? See the installation guide.

​
1. Initialize

Run init once in your project directory. It walks you through everything interactively. 
npx dbdock init
It will ask for:
  • Database connection (host, port, user, database name)
  • Storage provider (local disk, S3, R2, or Cloudinary)
  • Encryption (recommended for cloud storage)
  • Alerts (optional — Slack and email)
Security-first by default. Non-sensitive config goes to dbdock.config.json (safe for git). Secrets go to .env, and .gitignore is updated automatically.

​
2. Create your first backup

npx dbdock backup
You’ll see real-time progress: 
████████████████████ | 100% | 45.23/100 MB | Speed: 12.50 MB/s | ETA: 0s | Uploading to S3
✔ Backup completed successfully
The backup is encrypted (if enabled), compressed, and streamed directly to your configured storage.

​
3. Restore a backup

npx dbdock restore
DBdock shows a list of backups and lets you pick one: 
Progress:
────────────────────────────────────────────────────────
  ✔ Downloading backup
  ✔ Decrypting data
  ✔ Decompressing data
  ⟳ Restoring to database...
────────────────────────────────────────────────────────
✔ All steps completed in 8.42s
You can also restore into a different database. Pick “New Database Instance (Migrate)” when prompted and provide the target connection details — great for refreshing staging from production.

​
4. Verify everything works

Before trusting DBdock in production, run the self-test: 
npx dbdock test
This checks:
  • Database connection
  • Storage provider access
  • Alert configuration (if enabled)

​
Environment-only setup (no config file)

Prefer not to commit a config file? Run DBdock entirely from environment variables: 
# .env
DBDOCK_DB_URL=postgresql://user:password@host:5432/database
STORAGE_PROVIDER=s3
STORAGE_BUCKET=my-backups
DBDOCK_STORAGE_ACCESS_KEY=your-key
DBDOCK_STORAGE_SECRET_KEY=your-secret
DBDOCK_ENCRYPTION_SECRET=your-64-char-hex-key
Then: 
npx dbdock backup
See the configuration reference for all available variables.

​
What to do next

Explore commands

Every command, every flag, with examples.

Choose storage

S3, R2, Cloudinary, or local disk.

Set up alerts

Slack, email, or custom webhooks.

Schedule backups

Automated cron-based backups.