Database Backups

We strongly recommend that you back up your WHMCS database regularly. This ensures the safety of your data if a server or system failure occurs.

Regular backups help to protect your customer data and WHMCS configuration, and they are vital if you run into certain problems. WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address. You can also request a full cPanel backup for a specific user as part of the automatic backup process.

You can access this feature at Configuration () > System Settings > Database Backups.

Data in WHMCS

WHMCS is effectively comprised of three key parts:

The database contains all of the settings and data that WHMCS uses.
The files tell the software how to operate and control its appearance.
The configuration file allows the files to communicate with the database.

Because the database itself contains all of the data, you can restore a WHMCS installation as long as you have a copy of that database.

For steps to restore your WHMCS installation using a database backup, see Restore the WHMCS Database.

Automated Database Backup

WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address. We recommend using this method to back up your database regularly.

Backup Options

When you enable automated backups, you can choose from the following backup options:

SFTP/FTP Backup — Back up your data to an FTP or SFTP location. The system will store the WHMCS-generated zipped SQL file on the specified remote server.
This option only supports FTP and SFTP. It does not support other protocols like FTPS and FTP/TLD.
cPanel Backups — Back up your data using the cPanel API functions for the cPanel Backup Wizard feature. When you enable this backup option, you must create a cPanel API token in WHM at Development » Manage API Tokens with the basic-system-info and cpanel-api permissions.
When you select this backup type, the system cron only requests that the system starts a full backup using cPanel’s Backup Wizard feature. It will not detect completion, move the backup file, or provide notification.
Daily Email Backups — Back up your data and email the generated backup file to the specified email address.
This method may fail for large databases due to system memory or time execution limits. We do not recommend it for large installations.

Enable Automated Backups

To enable automatic backups:

Go to Configuration () > System Settings > Database Backups.
Click on the desired backup option (see above).
Enter the necessary information for the selected option:
- For SFTP/FTP Backup, enter the hostname, port, username, password, and destination.
  - Enter the FTP destination relative to the login folder for the FTP or SFTP account that you are using. For example, if the folder when you log in is at /home/user and the backup should exist in /home/user/backups, enter backups/. If you intend to upload the backup file directly within the login folder, leave this value blank.
  - Check Use Secure FTP/SFTP (Recommended) to ensure that the backup upload uses an SFTP connection.
  - Check FTP Passive Mode to use passive mode.
- For cPanel Backups, enter the hostname, username, and password for the cPanel account that hosts your WHMCS installation. You can select from the following backup destinations:
  - Remote FTP Server — Use FTP to store the backup file on a remote server.
  - Remote FTP Server (Passive connection) — Use passive FTP to store the backup file on a remote server.
  - Secure Copy (SCP) — Use SCP to store the backup file on a remote server.
  - Home Directory — Save the backup file to the server. This option generates the backup file in the cPanel account’s home directory, which the system will include in any disk space limits. We recommend moving this backup manually to another location.
- For Daily Email Backups, enter the email address to receive backups.
If you selected SFTP/FTP Backup or cPanel Backup, click Test Connection to perform a connection test. These backup options require a successful connection test to ensure that details are valid and that WHMCS can connect to the server.
Click Save & Activate.

Disable Automatic Backups

To disable an automatic backup method, click Deactivate for it at Configuration () > System Settings > Database Backups.

Manual Database Backup

The system cron can perform a backup as one of its tasks. By default, it performs this task once per day.

You can manually download a backup of the WHMCS database at Utilities > System > Database Status.
You can execute the backup task manually by running the following command:
php -q cron.php do --DatabaseBackup

For more information, see System Cron.

The configuration.php File

Make certain that you are backing up the configuration.php file in the main whmcs directory. This file contains the encryption hash value that is unique to your particular installation, which encrypts sensitive data.

If you lose the encryption hash value, the system won’t be able to decrypt your data.

Because of this, it is important to keep a backup of this file in a secure location in case reinstallation is necessary.

For more information, see The configuration.php File.

Large Installations and Backups

As a database grows, it becomes too big for a PHP script like the WHMCS cron job to handle, due to the amount of data in it exceeding various server limits, usually when the database exceeds 20 MB. The size prevents the system from completing an FTP or email backup.

In this case, we recommend using the cPanel Backup option instead (if you installed WHMCS on a cPanel & WHM server). The cPanel system processes can generate larger backup files without impacting the performance of your website.

When switching to cPanel or external backups, you must disable the FTP and email backup features. This prevents errors with the cron due to the large database size.

If you are not on a cPanel server, you can use an external tool like mysqldump to export your database.

For more information, see the MySQL Documentation.

Common Errors

If database backups fail, the problem is usually due to large database sizes that cause PHP to be unable to process the backup within its set limitations.

You may also see the following common errors:

Error	Description	Recommended Solution
`Table 'xxx' doesn't exist when using LOCK TABLES`	The named table (`xxx`) has crashed or is corrupted.	Running a MySQL® repair operation will resolve this. You can repair tables using the cPanel MySQL Databases feature or using a tool like phpMyAdmin.
`Database backup unavailable due to missing required zip extension`	The `ZipArchive` PHP class is missing from your PHP configuration.	Enable the `ZipArchive` PHP class and recompile PHP.
`Database backup error 'Please provide a valid dump path'`	WHMCS cannot access the `/tmp` working directory during the backup generation process.	Ensure that the `open_basedir` directive is disabled in your PHP configuration and that the `/tmp` directory is writeable and is not full.

database database-backups

Last modified: October 30, 2024