We use cookies to make your viewing experience better. By accepting you consent, you agree to our Cookie policy

Improve your Craft CMS skills

How To Restore A Database In Craft CMS

10 min read
Andy Golpys Made By Shape Founder

Restoring a database is a critical recovery process for any Craft CMS site. When disaster strikes and data is corrupted or lost, restores provide a lifeline. This guide will provide Craft users with invaluable techniques to backup, securely store, and reliably restore databases when the need arises. By following these best practices, you can confidently protect and revive your Craft site if the worst happens.

Craft CMS databases can be restored using built-in or third party backup tools. Follow these steps: take site offline, create fresh database, import backup, update .env credentials, clear caches, resave assets, rebuild indexes, and test front/backend. Schedule regular backups, store securely offsite, encrypt, restrict access. Troubleshoot issues via logs and configurations.

When to Restore a Database in Craft CMS

Recovering from Database Corruption and Failed Updates

At times, issues like database corruption or failed updates can damage your Craft CMS site, necessitating a restore. Database corruption can occur due to software faults, storage problems, or human error during a botched update. Typical symptoms include site crashing, data anomalies, and features malfunctioning.

Restoring a backup when corruption strikes allows reverting to an earlier stable version. However, this results in permanent data loss since the latest entries made after the backup will be discarded. Hence, regularly scheduled backups are vital. For minor corruption, repairing the database might suffice but major damage calls for a full restore.

Failed updates also often require database restores. Whether it's a core update gone wrong or a problematic plugin/module update, rollbacks become essential. For example, a plugin update could trigger conflicts and break vital site functions. By restoring the database, the site can be reverted to the pre-update state, allowing debugging of the issue before retrying the update.

Overall, database restores provide a critical recovery mechanism from common mishaps like corruption or update failures. With robust backup routines, web managers can swiftly undo serious database issues and restore normal operations.

Migrating Sites to New Servers

Migrating a Craft site from one server to another invariably requires a database restore on the new server. This could be moving hosts or transitioning the site in-house to your own infrastructure. The database contains all the site data, so restoring it is imperative.

The typical migration workflow involves fully backing up the database from the original server and transferring it to the new environment. Most hosting control panels include tools to directly backup/download the database. After uploading the backup to the new server, the database is restored to populate the CMS with all its original content and settings.

Database restoration ensures continuity after the disruptive server change. It also guarantees all the real-time edits on the live site get ported over, unlike outdated manual exports. The new server can precisely mirror the old configuration minus intermittent downtime for visitors.

Some key pointers when restoring the database during migration - use a recent backup, adjust any hardcoded URLs, clear caches and reindex search. This smooths the transition by minimizing mismatches between the old and new environments.

Syncing Live and Development Environments

For developers working on new features, restoring the live/production database into local and staging environments is often necessary. It provides real data to work against instead of dummy content.

The typical workflow looks like:

  • Developer takes a fresh backup of the live database

  • Restore this on their local Craft CMS instance

  • Now they can build new features using actual site content and structure

  • Any changes can be tested safely without affecting production

  • Upon feature completion, changes are deployed to staging and then production servers

This syncing allows building locally with production data. Things like content relationships, structure, real-world edge cases are reproduced locally. Testing is more robust when security, performance, integrations can be verified against the real database.

Restoring production data does carry small privacy risks regarding personal user data in local machines. Developers need to be careful about properly wiping data after testing. Automated syncing using orchestration tools can minimize manual restores to one-off cases.

Database restores are indispensable when syncing live data to lower environments. It enables development grounded in production reality, not mock data. With proper access controls, the risks can be effectively mitigated too.

Prerequisites for Restoring a Craft CMS Database

Accessing Database Backups

The first prerequisite for restoring a Craft CMS database is having access to complete and recent database backups. Without a properly backed-up copy of the database, restores are impossible.

Ideally, the site should have routine scheduled backups to an external location, either performed manually or via automated tools. Backup frequency depends on site activity and risk tolerance - daily or weekly backups are common. The backups must be stored securely to prevent unauthorized access or tampering.

When a restore is required, the administrator needs to obtain the latest usable backup. This might involve downloading it from an off-site storage provider or copying it from a local backup server. Proper credentials and permissions are necessary to retrieve the backup file.

Some key pointers around accessing Craft database backups:

  • Maintain a documented on-site and off-site backup routine

  • Rotate through incremental backups so you have multiple restore points

  • Keep backups in accessible but secure storage like encrypted S3 buckets

  • Control access to backups so only authorized personnel can retrieve them

  • Test backups periodically by restoring copies to isolate environments

By investing in robust backup infrastructure and processes, admins guarantee restore capability when the need arises.

Backup and Database Compatibility

Another critical prerequisite is ensuring compatibility between the backup file and target database. The backup must be in the proper format (SQL file, database dump etc.) supported by the database system.

Additionally, the database version in the backup must match the current production version. For example, restoring a Craft 3.1 backup to a Craft 3.5 system will cause conflicts. The backup should always be the same or lower version.

Dependencies like plugins and CMS version also factor in. If the live site has a newer plugin version compared to when the backup was taken, incompatibilities may surface after restoring this backup.

Some tips for smooth compatibility:

  • Record Craft CMS, database, PHP and plugin versions at backup time

  • Optimize and sanitize data before backing up

  • Stick to native backup utilities provided by the database vendor

  • Test restores on staging environment before overwriting production

Overall, due diligence around backup and database compatibility minimizes nasty surprises down the line. Always match the target environment instead of assuming backups will work seamlessly.

User Privileges and Permissions

Finally, the administrator performing the Craft CMS database restore requires adequate user privileges. Typically, this would be a user with full administrative control over the database.

At a minimum, the user should have:

  • Permissions to access database storage and servers


  • Ability to import and execute SQL scripts

  • Access to tools like phpMyAdmin or MySQL command line

Ideally, restores should be performed using the native database user like root or admin user.

Alternatively, a separate user can be created and granted the necessary privileges.

Restricting restore capabilities enhances security. Global READ/WRITE access allows even basic users to overwrite or maliciously alter data. Control panel users only require permissions to modules like Assets and Entries.

Privileged database access allows authorized personnel to safely restore Craft backups when needed. Restricting it locks down the database against unintended tampering. Match privileges to operational needs for balance.

Step-by-Step Guide to Restoring a Craft CMS Database

Preparing the Database for Restore

Once the backup is validated, the first step is preparing the target database. This involves:

  • Taking the site offline or blocking access to prevent mid-restore edits. A maintenance page should notify users.

  • Creating a fresh, empty database instance on the target server. This provides a blank slate for the restore.

  • Setting the needed database config values like hostname, database name, user/password.

  • Importing the database backup into the empty database using CLI tools like mysql or GUI tools like phpMyAdmin.

  • Running manual commands or scripts to optimize the imported database if needed. This may include clearing caches, updating schemas or permissions etc.

Proper preparation minimizes errors when overwriting the existing database. It also avoids conflicts between old data and the imported backup. A few dry runs in a staging environment can help validate this prepared state.

Updating Database Settings and Credentials

After the restore, the Craft CMS .env file needs updating to point to the new database. This involves:

  • Setting the correct database credentials like DB_SERVER, DB_USER, DB_PASSWORD etc.

  • Double checking these match the restored database's credentials.

  • Adjusting other settings like DB_SCHEMA based on the new environment.

  • Testing the connection by reloading Craft backend or running a DB query.

  • Troubleshooting errors if connectivity fails - it could be a credential typo, wrong port or missing plugin.

This step re-establishes the linkage between Craft and the restored database. The CMS cannot function without this active connection. Settings should be verified in both .env and database config files.

Post Restore Cleanup and Verification

Once the database is restored and Craft reconnected, cleanup tasks help smooth operations:

  • Clear all caches to purge invalid or outdated cached data after the restore.

  • Rebuild search indexes to sync them with restored content.

  • Resave all assets to update their paths and Volume info.

  • Check front-end pages to confirm public site works as expected.

  • Test critical back-end functions - edit entries, create users, process orders etc.

  • Examine logs for any glaring errors caused by the restore.

Thorough verification and cleanup avoids lingering issues post-restore. Problems like conflicting asset paths or a wonky search index only surface down the line if unchecked. A full-site audit identifies anomalies before launch.

Careful attention at each step of database restore and post-restore cleanup ensures a smooth transition with minimal downtime. The process requires precision - validating credentials, connections, caches and content at every point safeguards the migration.

Backing Up a Craft CMS Database

Native Craft CMS Backup Tool

Craft CMS includes a built-in database backup utility to simplify the process. It creates a backup archive that includes the database, asset files and plugin folders.

To use it, navigate to Utilities > Backups in the control panel. Choose a descriptive name and hit "Backup database". This will package the backup and download it. The native tool provides options to exclude specific volumes and plugins.

Benefits of the native backup tool

  • Simple one-click backups without technical complexity

  • Directly integrated into the control panel

  • Allows periodic scheduled backups to be configured

  • Can password-protect archives for security

  • Stores backups on the server itself by default

The native tool may not be robust enough for large complex sites. But for smaller sites, it provides a handy way to manually or automatically backup the database.

Command Line and GUI Tools

For advanced database backup needs, command line tools like mysqldump and phpMyAdmin are common.

Mysqldump exports MySQL databases to SQL text files. It is extremely fast and can be run via scripts for automated backups. Mysqldump creates functional backups readily restored via the mysql CLI tool.

PHPMyAdmin offers a GUI to backup databases. Just click "Export" and download the gzipped SQL file. Easy to use but limited in scheduling capabilities. Offers slightly less flexibility than mysqldump.

Some pointers when using CLI/GUI tools:

  • Optimize databases before backup for smaller file sizes

  • Automate backups using cron jobs or similar

  • Encrypt and securely transmit offsite after backup

  • Validate backups by testing restores

These methods provide granular control for developers backing up sites locally or remotely.

Automated Scheduled Backups

For set-and-forget database backups, automating them via scripts or services is ideal. This ensures regular backups without manual intervention.

Scripting tools like WP-CLI, database cron jobs, Laravel scheduler etc allow running mysqldump or similar periodically. The backup script outputs files to cloud storage like S3 or Dropbox.

Third-party services like BackupBuddy and UpDraftPlus also simplify automated database backups. Just install the plugin and configure schedule, retention rules etc.

Some tips for automated backups:

  • Schedule daily or weekly based on database change rate

  • Retain multiple backup versions for redundancy

  • Test restores regularly to validate backups

  • Monitor service dashboards for status and errors

  • Follow 3-2-1 principle - 3 copies, 2 media types, 1 off-site

A layered backup strategy combining native tools, scripts and services ensures robust protection for Craft databases.

Securing and Storing Craft CMS Database Backups

Encrypting Backup Files

Since database backups contain sensitive information, encryption is strongly recommended. This prevents unauthorized access if the backups are compromised.

Tools like mysqldump allow piping the output through OpenSSL to encrypt with AES256 or similar algorithms. The backup can only be decrypted with the corresponding private key.

GUI tools like phpMyAdmin also have options to encrypt exports with a password. This adds a layer of security for files saved locally.

For third-party backup services, they typically use encryption schemes like SSL/TLS during transfers and at rest. Their dashboards provide options to configure master encryption keys.

Some tips when encrypting Craft database backups:

  • Use strong passwords and industry standard encryption like AES-256.

  • Restrict and rotate encryption keys periodically.

  • Never store keys alongside encrypted backup files.

  • Consider public key infrastructure (PKI) for more complex setups.

Encryption provides vital data security while backups transit networks or sit in storage.

Secure Protocols and Restricted Access

Transmitting and storing backups should rely on secure protocols and restricted user access.

Common protocols include SFTP for transfers, SSL connections for database access, and using HTTPS for downloads/uploads. These encrypt traffic preventing mid-stream interception.

Access to backup systems should require SSH keys or complex rotating credentials. Minimal users should have upload/download privileges. File permissions must be locked down preventing public access.

Some pointers for access control:

  • Use private subnets and firewall rules where possible

  • Require VPN access to reach backup administration interfaces

  • Set up SSH keys for SFTP rather than passwords alone

  • Never leave default credentials unchanged

Following security best practices for backup systems avoids many attack vectors.

Separate and Remote Storage

Ideally, database backups should not be stored on the live production server. Maintaining an air gap minimizes exposure.

Regular local backups are fine for versioning. But older archives should be copied off-server to separate storage. This prevents corruption or deletion if the source server is compromised.

Common remote storage options include cloud storage like S3 buckets, attached storage SANs, backup tapes in secure facilities etc. The 3-2-1 backup principle highlights keeping 3 copies, 2 media types, 1 copy off-site.

Some other tips:

  • Cycle through incremental backups locally but move old ones off-server

  • Test restoration from remote storage periodically

  • Version backups allowing rollback to any point-in-time

Keeping live data separate from backups provides an added layer of protection and redundancy.

A holistic approach combining encryption, strict access control and remote storage keeps Craft CMS database backups secure. This fortifies the last line of defense when restores become critical.

Troubleshooting Issues with Restoring a Craft CMS Database

Reviewing Logs for Errors

If a Craft CMS database restore fails or has issues, the first step is checking the logs.

The Craft logs provide detailed error messages covering different layers - PHP, database queries, http requests etc. Checking file logs like craft.log, phperrors.log and console logs surfaces the potential cause.

Common log errors to watch for:

  • SQL syntax or query errors - could indicate backup corruption

  • "Connection lost" or timeout warnings - database connectivity issue

  • File system errors for missing volumes or assets - sync problem

  • Permission denied errors - user account lacks privileges

  • Plugin not found - backup running older plugin version

  • Craft version mismatch - backing up from different CMS version

Logs provide clues to hone in on misconfigurations, compatibility issues, connectivity problems etc.

Fixing Asset and File Sync Issues

Craft CMS sites often run into asset sync problems following a database restore. This leads to missing or mismatched volumes and files.

If assets rely on external storage like S3, the access credentials may differ between environments. The restored database retains old asset paths which break when retried.

Fixes include:

  • Update asset volume settings to use current credentials

  • Re-save assets forcing them to re-upload to the volumes

  • Synchronize any orphaned assets by re-indexing asset metadata

  • Check file permissions allow Craft to access the configured volumes

  • Clear cache and manually delete any corrupted asset caches

Proper assets sync avoids headaches down the line for editors and customers.

Adjusting Configuration Differences

In some cases, environment differences between the source and target of the restore cause configuration issues.

For example, the database might contain hardcoded external URLs like CDN references which need adjusting post-restore. The new server could have different cache setups, plugin versions and PHP configs.

Typical fixes:

  • Update database values and .env settings for new environment

  • Tweak cached behavior and clear caches

  • Enable/disable plugins if versions are incompatible

  • Switch PHP versions if the new server has discrepancies

  • Regenerate the config to sync any config changes

Tuning the configuration mitigates incompatibilities between the backup environment and new one.

In summary, common issues arising from Craft CMS database restores can be mitigated through careful debugging using logs, configuration tweaks and asset syncs. Patience and methodically ruling out potential causes helps resolve restore problems.

Shape April 2022 HR 202
Andy Golpys
- Author

Andy has scaled multiple businesses and is a big believer in Craft CMS as a tool that benefits both Designer, Developer and Client. 

Show us some love
Email Us
We usually reply within 72 hours
Agency Directory
Submit your agency
Affiliate Partners
Let's chat