Configuration

Configure DBDock via dbdock.config.json or environment variables

Configuration can come from dbdock.config.json (generated by npx dbdock init) or entirely from environment variables. You can also mix: use a config file and override database or other settings via env (e.g. DBDOCK_DB_URL).

Security First: DBDock uses a hybrid configuration approach. Secrets (passwords, keys) are stored in environment variables, not in the config file. This keeps your secrets safe and your config file safe for version control.

Structure

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

Database

Configuration for connecting to your PostgreSQL database.

Option 1: Full URL via environment (recommended for env-only or CI)

Set DBDOCK_DB_URL or DATABASE_URL to a full PostgreSQL URL. When set, it overrides any database section in dbdock.config.json. No separate password variable is needed.

DBDOCK_DB_URL=postgresql://user:password@host:5432/database
# or
DATABASE_URL=postgresql://user:password@host:5432/database

Option 2: Config file + password in env

"database": {
  "type": "postgres",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "database": "myapp"
}

The password is stored in the DBDOCK_DB_PASSWORD environment variable, not in the config file.

Option 3: Env-only (no config file)

You can run without dbdock.config.json by setting DBDOCK_DB_URL (or DATABASE_URL) plus storage and other env vars (e.g. STORAGE_PROVIDER, DBDOCK_STORAGE_ACCESS_KEY, DBDOCK_STORAGE_SECRET_KEY). See Environment Variables Reference below.

Using .pgpass

For enhanced security, you can use PostgreSQL’s .pgpass file instead of environment variables:

touch ~/.pgpass
chmod 600 ~/.pgpass
echo "localhost:5432:myapp:postgres:my-secure-password" >> ~/.pgpass

DBDock will automatically use .pgpass when available.

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"
  }
}

Set credentials via environment variables:

DBDOCK_STORAGE_ACCESS_KEY=your-access-key
DBDOCK_STORAGE_SECRET_KEY=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"
  }
}

Set credentials via environment variables (same as S3 above).

Cloudinary

Stores backups in Cloudinary.

"storage": {
  "provider": "cloudinary",
  "cloudinary": {
    "cloudName": "your-cloud"
  }
}

Set credentials via environment variables:

DBDOCK_CLOUDINARY_API_KEY=your-api-key
DBDOCK_CLOUDINARY_API_SECRET=your-api-secret

Backup Settings

Control how backups are created and retained.

"backup": {
  "format": "custom",
  "compression": {
    "enabled": true,
    "level": 6
  },
  "encryption": {
    "enabled": true
  },
  "retention": {
    "enabled": true,
    "maxBackups": 100,
    "maxAgeDays": 30,
    "minBackups": 5,
    "runAfterBackup": true
  }
}

Note: The encryption key is stored in the DBDOCK_ENCRYPTION_SECRET environment variable, not in the config file.

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). Store it in the DBDOCK_ENCRYPTION_SECRET environment variable.

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
    },
    "from": "[e-mail]",
    "to": ["[e-mail]", "[e-mail]"]
  },
  "slack": {
    "enabled": true,
    "webhookUrl": "https://hooks.slack.com/services/..."
  }
}

Note: SMTP credentials (user, pass) are stored in environment variables:

• DBDOCK_SMTP_USER - SMTP username
• DBDOCK_SMTP_PASS - SMTP password

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
  }
}

Set credentials via environment variables:

DBDOCK_SMTP_USER=[e-mail]
DBDOCK_SMTP_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
  }
}

Set credentials:

DBDOCK_SMTP_USER=apikey
DBDOCK_SMTP_PASS=YOUR_SENDGRID_API_KEY

AWS SES:

{
  "smtp": {
    "host": "email-smtp.us-east-1.amazonaws.com",
    "port": 587,
    "secure": false
  }
}

Set credentials:

DBDOCK_SMTP_USER=YOUR_SMTP_USERNAME
DBDOCK_SMTP_PASS=YOUR_SMTP_PASSWORD

Mailgun:

{
  "smtp": {
    "host": "smtp.mailgun.org",
    "port": 587,
    "secure": false
  }
}

Set credentials:

DBDOCK_SMTP_USER=[e-mail]
DBDOCK_SMTP_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

Environment Variables Reference

DBDock uses environment variables for all sensitive credentials. Set these in your .env file. You can configure entirely via env (no dbdock.config.json) using DBDOCK_DB_URL or DATABASE_URL plus the storage and other variables below.

Variable	Description	Required
DBDOCK_DB_URL	Full PostgreSQL URL (postgresql://user:pass@host:5432/db)	No (use or DATABASE_URL or separate fields)
DATABASE_URL	Same as DBDOCK_DB_URL (alternate name)	No
DBDOCK_DB_PASSWORD	Database password	Yes (if not using DBDOCK_DB_URL / DATABASE_URL)
DB_HOST, DB_PORT, DB_USER, DB_NAME	Database connection (when not using URL)	No (defaults used if omitted)
DBDOCK_STORAGE_ACCESS_KEY	Storage access key (S3/R2)	Yes (for cloud storage)
DBDOCK_STORAGE_SECRET_KEY	Storage secret key (S3/R2)	Yes (for cloud storage)
DBDOCK_CLOUDINARY_API_KEY	Cloudinary API key	Yes (for Cloudinary)
DBDOCK_CLOUDINARY_API_SECRET	Cloudinary API secret	Yes (for Cloudinary)
DBDOCK_ENCRYPTION_SECRET	64-char hex encryption key	Yes (if encryption enabled)
DBDOCK_SMTP_USER	SMTP username	No (for email alerts)
DBDOCK_SMTP_PASS	SMTP password	No (for email alerts)
DBDOCK_SLACK_WEBHOOK	Slack webhook URL	No (for Slack alerts)
DBDOCK_STRICT_MODE	Enforce env-only secrets	No

Note: When DBDOCK_DB_URL or DATABASE_URL is set, the database password is read from the URL and DBDOCK_DB_PASSWORD is not required. DBDock reads from both .env and .env.local (.env.local takes priority).