Skip to main content
The dbdock.config.json file controls all aspects of DBdocks. It is automatically generated by npx dbdock init but can be edited manually.

​
Structure

{
  "database": { ... },
  "storage": { ... },
  "backup": { ... },
  "alerts": { ... }
}

​
Database

Configuration for connecting to your PostgreSQL database. 
"database": {
  "type": "postgres",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "your-password",
  "database": "myapp"
}

​
Storage

DBDock supports multiple storage providers.

​
Local

Stores backups on the local filesystem. 
"storage": {
  "provider": "local",
  "local": {
    "path": "./backups"
  }
}

​
AWS S3

Stores backups in an Amazon S3 bucket. 
"storage": {
  "provider": "s3",
  "s3": {
    "bucket": "my-backups",
    "region": "us-east-1",
    "accessKeyId": "YOUR_ACCESS_KEY",
    "secretAccessKey": "YOUR_SECRET_KEY"
  }
}

​
Cloudflare R2

Stores backups in Cloudflare R2. 
"storage": {
  "provider": "r2",
  "s3": {
    "bucket": "my-backups",
    "region": "auto",
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "accessKeyId": "YOUR_ACCESS_KEY",
    "secretAccessKey": "YOUR_SECRET_KEY"
  }
}

​
Cloudinary

Stores backups in Cloudinary. 
"storage": {
  "provider": "cloudinary",
  "cloudinary": {
    "cloudName": "your-cloud",
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET"
  }
}

​
Backup Settings

Control how backups are created and retained. 
"backup": {
  "format": "custom",
  "compression": {
    "enabled": true,
    "level": 6
  },
  "encryption": {
    "enabled": true,
    "key": "64-character-hex-key..."
  },
  "retention": {
    "enabled": true,
    "maxBackups": 100,
    "maxAgeDays": 30,
    "minBackups": 5,
    "runAfterBackup": true
  }
}

​
Backup Formats

DBDock supports multiple PostgreSQL backup formats:
  • custom (default) - PostgreSQL custom binary format (.sql)
  • plain - Plain SQL text format (.sql)
  • directory - Directory format (.dir)
  • tar - Tar archive format (.tar)

​
Encryption Key

Generate a secure 64-character hexadecimal encryption key: 
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
The key must be exactly 64 hexadecimal characters (0-9, a-f, A-F).

​
Retention Policy

Automatic cleanup to prevent storage bloat from frequent backups. How it works:
  • Keeps most recent minBackups (safety net, never deleted)
  • Deletes backups exceeding maxBackups limit (oldest first)
  • Deletes backups older than maxAgeDays (respecting minBackups)
  • Runs automatically after each backup (if runAfterBackup: true)
  • Manual cleanup: npx dbdock cleanup
Configuration:
  • maxBackups: Maximum number of backups to keep.
  • maxAgeDays: Delete backups older than this many days.
  • minBackups: Always keep at least this many recent backups, regardless of age.
  • runAfterBackup: If true, cleanup runs automatically after every successful backup.
Safety features:
  • Always preserves minBackups most recent backups
  • Shows preview before deletion
  • Detailed logging of what was deleted
  • Error handling for failed deletions

​
Alerts

Configure email and Slack notifications for backup events. Alerts work with both programmatic usage and CLI commands. 
"alerts": {
  "email": {
    "enabled": true,
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "your-email@gmail.com",
        "pass": "your-app-password"
      }
    },
    "from": "backups@yourapp.com",
    "to": ["admin@yourapp.com", "devops@yourapp.com"]
  },
  "slack": {
    "enabled": true,
    "webhookUrl": "https://hooks.slack.com/services/..."
  }
}

​
Slack Configuration

  1. Create a Slack App or use an existing one.
  2. Enable “Incoming Webhooks”.
  3. Create a new Webhook URL for your channel.
  4. Run npx dbdock init and paste the URL when prompted.

​
SMTP Provider Examples

Gmail: 
{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "your-email@gmail.com",
      "pass": "your-app-password"
    }
  }
}
Note: For Gmail, you need to create an App Password instead of using your regular password.
SendGrid: 
{
  "smtp": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "apikey",
      "pass": "YOUR_SENDGRID_API_KEY"
    }
  }
}
AWS SES: 
{
  "smtp": {
    "host": "email-smtp.us-east-1.amazonaws.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "YOUR_SMTP_USERNAME",
      "pass": "YOUR_SMTP_PASSWORD"
    }
  }
}
Mailgun: 
{
  "smtp": {
    "host": "smtp.mailgun.org",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "postmaster@your-domain.mailgun.org",
      "pass": "YOUR_MAILGUN_SMTP_PASSWORD"
    }
  }
}

​
Alert Content

Success alerts include:
  • Backup ID
  • Database name
  • Size (original and compressed)
  • Duration
  • Storage location
  • Encryption status
Failure alerts include:
  • Error message
  • Database details
  • Timestamp
  • Helpful troubleshooting tips
Important Notes:
  • ✅ Alerts work with programmatic usage (createBackup())
  • ✅ Alerts work with scheduled backups (cron jobs in your app)
  • ✅ Alerts work with CLI commands (npx dbdock backup)
  • Configuration is read from dbdock.config.json automatically
  • Multiple recipients supported in the to array for email
  • Alerts are sent asynchronously (won’t block backup completion)

​
Storage Permissions

​
AWS S3

Required IAM permissions for S3 storage:
  • s3:PutObject - Upload backups
  • s3:GetObject - Download backups
  • s3:ListBucket - List available backups
  • s3:DeleteObject - Delete old backups
All cloud backups are stored in the dbdock_backups/ folder with format: backup-YYYY-MM-DD-HH-MM-SS-BACKUPID.sql