Frappe Bench Backup and Restore Guide: Moving Database from Production to Local

When debugging issues in your Frappe/ERPNext application, sometimes you need to work with a copy of your production database locally. This guide walks you through the safe process of backing up your production database and restoring it to your local development environment.

Step 1: Create a Backup on Your Production Server

SSH into your production server and navigate to your bench directory:

cd /home/user/bench-directory

Create a backup of your site (replace your_site_name with your actual site name):

bench --site your_site_name backup

This command will create a compressed database backup file in your sites directory.

Step 2: Download the Backup File

Access your Frappe/ERPNext admin interface via browser:

https://your-domain.com/app/backups

In the Backups Manager:

1. Set the number of backups you want to retain (1 keeps only the latest)
2. Click "Download Files Backup" to get the most recent backup
3. Note the file size to ensure you're downloading the complete backup

The downloaded file will have a naming convention like: 20250824_093711-example_site-database.sql.gz

Step 3: Prepare Your Local Environment

Move the downloaded backup file to your local bench directory (where your Procfile is located).

Step 4: Restore the Backup Locally

Navigate to your local bench directory and activate your virtual environment if needed, then run:

bench --site local_site_name restore path/to/backup_file.gz

Step 5: Run Database Migrations

After restoration, run migrations to ensure your database schema is up to date:

bench migrate

You may be prompted for your MySQL password during this process.

Important Considerations

1. File Size Check: Ensure the downloaded backup size matches what you saw in the admin interface
2. Scheduled Backups: Be aware of automatic backup schedules that might create new backups during your download process
3. Version Compatibility: Make sure your local bench version is compatible with your production version
4. Security: Always handle production backups with appropriate security measures

Troubleshooting Tips

• If the restore fails, check that you have enough disk space locally
• Ensure your local site is properly set up before restoring
• Verify database credentials in your local site configuration

This process allows you to safely work with production data locally while debugging issues, without risking your live environment.

Note: Always anonymize or remove sensitive data before using production backups for development purposes.