servd

Documentation

Documentation > Cookbook >

Upgrading to Craft 5

Here are a few recommended steps to guide you through the process of upgrading to Craft 5:

Database Upgrade #

For a long time, all project databases on Servd ran on MariaDB. But after it was announced Craft 5 was dropping support for it, we've switched the default database driver for all new projects to MySQL 8.

If your project was created before May 2024, then it will likely be running MariaDB and require upgrading to MySQL. Please follow these steps to perform the upgrade.

To confirm whether your project requires upgrading, navigate to your project's Build & Deploy page and check for the "Database Upgrade Available" section. If that is present, then your project is running MariaDB and will require upgrading to MySQL 8.

Upgrade Steps #

Once you're running MySQL 8, here are the next upgrade steps you'll need to take:

  1. Follow Craft's upgrade guide to get everything upgraded and working on your local machine.

  2. Commit and push all code and project config changes made as part of the upgrade to your git repository.

  3. Craft 5 requires a minimum PHP version of 8.2, so if you've had to increase your local PHP version during the upgrade, tweak the PHP version of your project in Servd.

    Note: this won't change the PHP version of your existing bundles, or immediately update the PHP version running in any of your environments. It just changes the version that's used for new bundles.

  4. Create a bundle from your commit.

  5. Check your post-deploy tasks contain the "./craft migrate/all --interactive=0" and "./craft project-config/sync --interactive=0" craft commands.

    If they don't, either add them, or manually run the commands via SSH or the dashboard once the bundle is synced.

  6. Once built, select and sync the new bundle to your staging or development environment.

  7. Give your staging/development environment a thorough test to make sure it's working as you expect.

  8. Select and sync the bundle to your production environment.

  9. Give your production environment a test.

  10. You're now running on Craft 5! 🎉

For Larger And More Complex Upgrades #

Sometimes for larger projects, and for upgrades that require data to "massaged" a little, it can be a good idea to use Servd's environment clone tools to prepare an upgraded version of the site on staging, then clone the site up to production. Here are a few steps for doing this:

  1. Go to your staging's Import page and clone production's assets, currently deployed bundle and database.

  2. Once complete, create a bundle containing all your Craft 5 changes.

  3. Deploy the upgraded bundle to staging.

  4. Once it is deployed and post-deploy tasks have completed, perform any manual modifications to the data in the staging database as required.

  5. Go to your production Import page and trigger an import into production from staging that includes the database and deployed bundle. If any assets have changes or new environment variables have been introduced, you may want to enable those options as well.

    It's a good idea to enable Atomic Database Imports for this step, as we've found Craft sometimes tries to populate plugin data into the database if it discovers that the table is empty. This can result in the correct plugin info not being populated correctly during the upgrade process.

Note: this solution isn't as suited for projects that are regularly storing user data and orders (e.g. e-commerce sites) as it will lose data that is created on production in the interim. In these scenarios, you may consider turning on Craft's maintenance mode during the upgrade to prevent users from submitting data.