Database Backups

Configure automated backups and restore procedures for your databases

Dokploy provides built-in automated backup functionality for all supported databases. Backups are stored in S3-compatible destinations and can be scheduled with cron expressions.

Supported Databases

Automated backups are available for:

• PostgreSQL: Using pg_dump
• MySQL: Using mysqldump
• MariaDB: Using mariadb-dump
• MongoDB: Using mongodump
• Compose Services: Volume-based backups

Redis typically doesn’t require separate backups - use RDB/AOF persistence instead. See Redis documentation for persistence configuration.

Backup Destinations

Before creating backups, configure a backup destination:

S3-Compatible Storage

Dokploy uses Rclone to support various S3-compatible storage providers:

• Amazon S3
• Backblaze B2
• Cloudflare R2
• DigitalOcean Spaces
• MinIO
• Wasabi
• Any S3-compatible service

1. Navigate to Destinations

   Go to Settings > Backup Destinations in your Dokploy dashboard.

2. Add Destination

   Click Add Destination and provide:

   • Name: Identifier for this destination
   • Provider: S3-compatible provider type
   • Bucket: Bucket name
   • Region: Bucket region
   • Access Key ID: S3 access key
   • Secret Access Key: S3 secret key
   • Endpoint (optional): Custom endpoint URL
3. Test Connection

   Verify the destination is accessible before saving.

Creating a Backup

1. Navigate to Database

   Open the database you want to backup in your Dokploy dashboard.

2. Open Backups

   Click the Backups tab.

3. Create Backup Configuration

   Click Add Backup and configure:

   Basic Settings:

   Database Name: myapp           # Database to backup
   Destination: S3 Production     # Previously configured destination
   Prefix: prod-db                # Folder prefix in S3
   

   Schedule:

   # Cron expression for backup frequency
   0 2 * * *    # Daily at 2 AM
   0 */6 * * *  # Every 6 hours
   0 0 * * 0    # Weekly on Sunday
   

   Retention:

   Keep Latest: 7    # Number of backups to retain
   

   Use crontab.guru to help construct cron expressions.

4. Enable and Deploy

   • Check Enabled to activate the backup schedule
   • Click Create to save
   • The backup will run according to the schedule

Backup Configuration

Schedule Syntax

Cron expression format: minute hour day month weekday

Common schedules:

Schedule	Cron Expression	Use Case
Every hour	0 * * * *	High-frequency changes
Every 6 hours	0 */6 * * *	Active databases
Daily at 2 AM	0 2 * * *	Standard production
Daily at midnight	0 0 * * *	End-of-day backup
Weekly (Sunday 2 AM)	0 2 * * 0	Lower-priority databases
Monthly (1st at 2 AM)	0 2 1 * *	Archives

Backup Retention

The Keep Latest setting determines how many backups to retain:

Keep Latest: 7    # Keeps 7 most recent backups
Keep Latest: 30   # Keeps 30 most recent backups
Keep Latest: 0    # Keeps all backups (not recommended)

Retention strategy:

• Older backups are automatically deleted
• Deletion happens after successful new backup
• Helps manage storage costs
• Recommended: 7-30 backups depending on change frequency

Backup Path Structure

Backups are stored in S3 with this structure:

{bucket}/{prefix}/{database}-{timestamp}.{extension}

Example:
my-backups/prod-db/myapp-2024-02-28-020000.sql.gz
my-backups/prod-db/myapp-2024-02-29-020000.sql.gz

Database-Specific Backup Details

PostgreSQL Backups

PostgreSQL backups use pg_dump with gzip compression:

# Backup command executed:
pg_dump -h postgres-prod -U appuser -d myapp | gzip > backup.sql.gz

# File format:
myapp-YYYY-MM-DD-HHMMSS.sql.gz

What’s included:

• Complete database schema
• All table data
• Indexes
• Constraints
• Views
• Functions and triggers

MySQL/MariaDB Backups

MySQL and MariaDB use mysqldump or mariadb-dump:

# Backup command:
mysqldump -h mysql-app -u appuser -p myapp | gzip > backup.sql.gz

# File format:
myapp-YYYY-MM-DD-HHMMSS.sql.gz

What’s included:

• Database schema
• Table data
• Indexes
• Triggers
• Views
• Stored procedures

Special considerations:

• Root password required for backup
• Large tables may impact performance
• Consider --single-transaction for InnoDB

MongoDB Backups

MongoDB backups use mongodump with compression:

# Backup command:
mongodump --host mongo-prod --username admin --authenticationDatabase admin \
  --archive=backup.archive.gz --gzip

# File format:
backup-YYYY-MM-DD-HHMMSS.archive.gz

What’s included:

• All collections
• Indexes
• Collection metadata
• Database configuration

Special considerations:

• Requires admin user credentials
• Large datasets may take time
• Locks collections briefly during dump

Compose Backups

Compose service backups create volume archives:

# Creates tar.gz of specified volumes
tar czf backup.tar.gz /volumes/data

# File format:
compose-service-YYYY-MM-DD-HHMMSS.tar.gz

What’s included:

• All files in specified volumes
• File permissions and ownership
• Directory structure

Manual Backups

Run a backup manually outside the schedule:

1. Navigate to Backups tab
2. Find your backup configuration
3. Click Run Now
4. Wait for backup to complete
5. Check destination for new backup file

Use manual backups:

• Before major database changes
• Before version upgrades
• Before data migrations
• To test backup configuration

Restoring Backups

Restore a database from a backup:

1. Navigate to Database

   Open the database you want to restore in Dokploy.

2. Access Restore

   Go to Backups > Restore Backup.

3. Select Backup

   Choose the backup configuration and browse available backup files:

   • Select the Destination
   • Browse available backups
   • Choose the backup file to restore

   Backup files are listed with timestamps:

   myapp-2024-02-28-020000.sql.gz
   myapp-2024-02-27-020000.sql.gz
   myapp-2024-02-26-020000.sql.gz
   
4. Configure Restore

   Specify restore options:

   Database Name:

   # Name of target database
   myapp    # Restore to existing database (overwrites!)
   myapp_restored  # Restore to new database
   

   Credentials:

   • For PostgreSQL: User password
   • For MySQL/MariaDB: Root password
   • For MongoDB: Admin password
5. Start Restore

   Click Restore to begin:

   • Database will be stopped
   • Backup file downloaded from S3
   • Data restored to database
   • Database restarted

   Restoring to an existing database will overwrite all current data. Always backup current data first.

6. Verify Restore

   After restore completes:

   1. Check database logs for errors
   2. Verify data integrity
   3. Test application connections
   4. Confirm all data is present

Restore Process Details

PostgreSQL Restore

# Restore command:
gunzip < backup.sql.gz | psql -h postgres-prod -U appuser -d myapp

# For new database:
creatdb myapp_restored
gunzip < backup.sql.gz | psql -h postgres-prod -U appuser -d myapp_restored

MySQL/MariaDB Restore

# Restore command:
gunzip < backup.sql.gz | mysql -h mysql-app -u root -p myapp

# For new database:
mysql -u root -p -e "CREATE DATABASE myapp_restored"
gunzip < backup.sql.gz | mysql -h mysql-app -u root -p myapp_restored

MongoDB Restore

# Restore command:
mongorestore --host mongo-prod --username admin --authenticationDatabase admin \
  --archive=backup.archive.gz --gzip --drop

# --drop removes existing collections before restore

Monitoring Backups

Backup Status

Check backup status in the dashboard:

• Last Run: Timestamp of last backup
• Status: Success or error
• File Size: Size of last backup
• Next Run: Scheduled next backup time

Backup Logs

View detailed backup logs:

1. Navigate to Backups tab
2. Click on a backup configuration
3. View Backup History
4. Check logs for any errors

Common log messages:

# Success
Backup completed successfully
Uploaded to s3://my-bucket/prod-db/myapp-2024-02-28-020000.sql.gz
Retention: Kept 7 backups, deleted 1 old backup

# Errors
Error: Failed to connect to database
Error: Insufficient permissions on S3 bucket
Error: Backup file too large for destination

Backup Best Practices

Frequency

1. Production databases: Daily or more frequent
2. Development databases: Weekly or on-demand
3. Critical data: Every 6 hours or hourly
4. Archives: Monthly or quarterly

Retention

1. Hot backups: 7-14 days for quick recovery
2. Warm backups: 30-90 days for compliance
3. Cold backups: Long-term archives (manual)

Storage

1. Use different regions: Store backups in different region than database
2. Lifecycle policies: Use S3 lifecycle rules for long-term storage
3. Monitor costs: Track storage usage and optimize retention
4. Test restores: Regularly test restore procedures

Security

1. Encrypt backups: Use S3 server-side encryption
2. Secure credentials: Rotate S3 access keys regularly
3. Limit access: Use IAM policies to restrict backup access
4. Audit logs: Monitor backup and restore operations

Troubleshooting

Backup not running

If backups aren’t executing:

1. Check if enabled: Verify backup configuration is enabled
2. Verify cron schedule: Ensure cron expression is valid
3. Check database status: Database must be running
4. Review logs: Check backup logs for errors
5. Test destination: Verify S3 destination is accessible

Backup fails with authentication error

Database credential issues:

1. Verify database password: Check password is correct
2. Check user permissions: User needs backup privileges
3. PostgreSQL: User must own database or have pg_dump rights
4. MySQL/MariaDB: Need PROCESS and LOCK TABLES privileges
5. MongoDB: User must have backup role

Cannot connect to S3

S3 destination connectivity issues:

1. Verify credentials: Check access key and secret key
2. Check bucket: Ensure bucket exists and is accessible
3. Test permissions: Verify write permissions on bucket
4. Check endpoint: Confirm endpoint URL if using custom provider
5. Network access: Ensure firewall allows S3 connections

Backup files too large

Large backup file issues:

1. Compression: Backups are gzipped but may still be large
2. Check database size: Use du to check volume size
3. Increase timeout: Adjust backup timeout if needed
4. Consider incremental: Not currently supported - contact support
5. Storage limits: Ensure S3 bucket has sufficient space

Restore fails

Restore operation issues:

1. Check credentials: Verify restore user has proper rights
2. Database exists: Ensure target database exists
3. Stop applications: Stop apps using database during restore
4. Sufficient space: Verify disk space for restored data
5. Compatible version: Backup and restore versions should match

Old backups not deleted

Retention policy not working:

1. Check retention setting: Verify “Keep Latest” is configured
2. Wait for next backup: Deletion happens after successful backup
3. Manual cleanup: Delete old backups manually from S3 if needed
4. Check logs: Review backup logs for deletion errors
5. S3 permissions: Ensure delete permission on bucket

Disaster Recovery

Prepare for disaster recovery scenarios:

Recovery Plan

1. Document procedures: Write step-by-step restore instructions
2. Test regularly: Practice restores monthly
3. Multiple destinations: Use multiple S3 buckets/regions
4. Monitor backups: Set up alerts for failed backups
5. Automate testing: Script restore tests to temporary databases

RTO and RPO

Recovery Time Objective (RTO):

• How quickly can you restore?
• Depends on backup size and network speed
• Test to establish realistic RTO

Recovery Point Objective (RPO):

• How much data loss is acceptable?
• Determined by backup frequency
• More frequent backups = lower RPO

Example Recovery Scenario

1. Detect Issue

   Database corruption or data loss detected.

2. Stop Applications

   Prevent further data modifications.

3. Identify Backup

   Find most recent valid backup before corruption.

4. Restore Database

   Use restore procedure to recover data.

5. Verify Data

   Check data integrity and completeness.

6. Resume Operations

   Restart applications and monitor.

7. Post-Mortem

   Document incident and improve procedures.

Advanced Backup Strategies

Multi-Region Backups

For critical data, maintain backups in multiple regions:

1. Create multiple backup destinations (different regions)
2. Configure separate backup jobs for each destination
3. Use same schedule for consistency
4. Monitor all backup jobs

Backup Verification

Automatically verify backup integrity:

1. Periodically restore to temporary database
2. Run integrity checks
3. Verify row counts
4. Test application queries
5. Automate with scripts

Backup Compression

All backups are automatically gzipped for efficiency:

# Compression ratios (typical):
PostgreSQL: 5:1 to 10:1
MySQL/MariaDB: 4:1 to 8:1
MongoDB: 3:1 to 6:1

# Example:
Uncompressed: 1GB
Compressed: 100-200MB

Next Steps

PostgreSQL

Back to PostgreSQL documentation

Database Overview

View all database options