How to Backup and Restore an ERPNext Site Using the Bench CLI
Backup & Restore ERPNextLearn the step-by-step process for creating and restoring backups of your ERPNext site, including database and files, using essential bench commands.
Properly backing up and restoring your ERPNext site is a critical administrative task for disaster recovery, server migration, or creating staging environments. The Frappe Bench Command Line Interface (CLI) provides a powerful and straightforward set of tools to manage this process. This guide covers the end-to-end workflow for creating a complete site backup and restoring it successfully.
⚡ Quick Command Reference
Copy these commonly used commands for immediate use.
| Task | Command |
|---|---|
| Backup Everything | bench backup --with-files |
| Backup DB Only | bench backup |
| Restore Site | bench restore /path/to/backup.sql.gz |
| Update Schema | bench migrate |
| Access DB Console | bench mysql |
1 // 1. Select the site you want to back up 2 bench use your_site_name.com 3
4 // 2. Take a backup of the database only 5 bench backup 6
7 // 3. Take a backup including database, public, and private files (Recommended) 8 bench backup --with-files 9
10 // Example: Specifying the site directly 11 bench --site erp.example.com backup --with-files 12
13 // --- RESTORE PROCESS --- 14
15 // 1. Drop the current database to ensure a clean restore 16 // This is a destructive action! 17 bench --site your_site_name.com mysql 18 -- You are now in the MariaDB/MySQL console 19 DROP DATABASE `_your_database_name`; 20 exit; 21
22 // 2. Restore the database from an SQL backup file 23 bench --site your_site_name.com restore path/to/your/database.sql.gz 24
25 // 3. IMPORTANT: Copy the 'encryption_key' from the old site_config.json to the new one. 26
27 // 4. Restore database and files together using the --force flag 28 bench --force --site your_site_name.com restore /path/to/database.sql.gz --with-public-files /path/to/public-files.tar --with-private-files /path/to/private-files.tar
Understanding This Code
What It Does
This set of commands provides a complete workflow for creating full backups (database and files) of an ERPNext site and restoring them to a new or existing bench instance.
When To Use
Use these commands during site migrations, before major upgrades, for disaster recovery, or for creating development/staging environments from a production backup.
Prerequisites
- •SSH access to the server hosting ERPNext
- •Frappe Bench has been initialized
- •Sudo or appropriate user permissions for file system and database operations
Key Concepts
Important ideas to understand in this code
Bench CLI
The Frappe Bench CLI is the primary tool for managing Frappe/ERPNext installations. It simplifies tasks like creating sites, installing apps, running migrations, and managing backups.
Learn moreSite Backups (`--with-files`)
A standard 'bench backup' only saves the database. The '--with-files' flag is crucial as it also archives the 'public/files' and 'private/files' directories, which contain user uploads and attachments.
Learn moresite_config.json & encryption_key
This file, located in `sites/{your_site_name}/`, contains site-specific configurations, including database credentials and the vital 'encryption_key'. This key is used to encrypt sensitive data. It MUST be identical between the source and restored site for data to be readable.
Learn moreStep-by-Step Tutorial
Follow along to understand how this code works
Create a Complete Backup
First, navigate to your bench directory. Use the 'bench backup' command with the '--with-files' flag to ensure both your database and your user-uploaded files are included. This will create several files (SQL, public files tar, private files tar) in your site's `private/backups` folder.
cd /path/to/your/frappe-bench/
bench backup --site your_site_name.com --with-filesPrepare the Target Site for Restore
On the destination server, you must drop the existing database to prevent conflicts. The 'bench mysql' command gives you direct access to the database console. This is a destructive step, so be certain you are on the correct site.
bench --site your_site_name.com mysql
-- In the MariaDB/MySQL prompt:
DROP DATABASE `_your_database_name`;
exit;Restore the Database and Files
Use the 'bench restore' command. The '--force' flag is often needed to bypass certain checks. Provide the full paths to your database backup, public files, and private files archives.
bench --force --site your_site_name.com restore \
/path/to/20230101_xxxx_database.sql.gz \
--with-public-files /path/to/20230101_xxxx-files.tar \
--with-private-files /path/to/20230101_xxxx-private-files.tarCopy the Encryption Key
This is the most critical step. After restoring, find the `site_config.json` file from your source site's backup or original server. Copy the value of `encryption_key` and paste it into the `site_config.json` of your newly restored site. Without this, you will face decryption and permission errors.
// Example of site_config.json entry
{
"db_name": "_your_database_name",
"db_password": "...",
"encryption_key": "COPY THIS VALUE"
}Run Migrations
After restoring the database and fixing the encryption key, run 'bench migrate' to ensure the database schema is up-to-date with the installed Frappe/ERPNext apps version.
bench --site your_site_name.com migrateCommon Issues & Solutions
Troubleshoot problems you might encounter