Upgrad­ing from Craft 2 to Craft 3: Update Every­thing on Craft 2

Technically possible? Budget approved? Great. You've made it through the first step (Upgrading from Craft 2 to Craft 3: Should I update?) and you're moving forward. Time to take a few steps so that you’re happier when something goes wrong during the migration.

Create a few folders

As a migration often involves troubleshooting where things were and where things are going, I recommend creating two folders alongside your main website folder so that you have a staging area and can reference your Craft 2 site and Craft 3 site side by side during the migration.

These secondary folders don’t need to be in your repository, they’ll just be temporary until you’ve finished the migration. It is possible to refer to these updates by moving forward and backward in your git history though I find it easier to have the separate folders so I can easily copy files from the old Craft 2 site to the new Craft 3 site and reference anything that I may need to from each install along the way.

Update Everything on Craft 2

You'll start your migration journey with Craft 2 and Craft 2 alone. Time to spend your last days together, reminisce on the good times, and say goodbye. During this final hurrah, you’ll want to get the codebase updated and cleaned up as best you can on your Craft 2 install so you are less likely to have to deal with outlier scenarios once you begin updating to Craft 3.

• Update your Craft 2 site to the latest version of Craft
• Uninstall any plugins that you don’t plan to be using in Craft 3 (do this from the control panel so they also take any steps they are designed to take to clean up the database when they are uninstalled)
• Upgrade all plugins that you do plan to upgrade to their latest versions
• Clear all caches (clearing Template Caches removes the related rows from the db which is one more detail that can make your database smaller)
• Remove any content or anything else in Craft that you don’t wish to migrate.

Read plugin documentation

If you are upgrading larger plugins or if your Craft or plugin updates require upgrading over major versions (e.g. from 1.x of a plugin to 3.x) be sure to refer to the respective documentation in case there are additional steps you need to take during the updates.

Version control

I recommend making atomic commits after any file changes as you upgrade the Craft 2 site below and exporting database backups after any key database migrations. You want to have the ability to roll back to key points in the upgrade process if you need to troubleshoot anything unexpected that you discover later.

Whether you prefer to track your vendor folder or not once you get updated to Craft 3, I find that during migrations, it often is helpful to create a branch where you can commit your vendor folder and easily track changes in the repository. This makes it a lot easier to focus on the migration and move backward and forward to specific commits without having to re-run composer each time you want to recreate the instance of the site you want to be working with.

Craft runs a database backup before performing each update. I prefer to disable this setting in the general.php config (disableDbBackups) and backup the database manually. This lets me label it as it relates to where I am in the migration process and the upgrades themselves run a lot quicker so it’s easier to rollback and re-run an update multiple times if you are troubleshooting a problem.

This comes in handy in several scenarios including if you need to re-run the migration during a scheduled content freeze. You can now pull down the latest database, revert to the last commit where you still had Craft 2 installed, trigger the Craft 2 updates on the latest database, move forward and checkout the commit where you updated the app structure to Craft 3, and trigger the Craft 3 updates to the database. You can trigger these updates all at once or step through your commits to trigger specific Craft or Plugin updates one by one.

Database cleanup

While the upgrades should make most of the necessary database changes you need, I like to take this opportunity during the transition to review the database for anything I may no longer need that I've been avoiding to clean up.

Out of respect for the next developer (and yourself in a few months), make sure the settings and content you have in the database are necessary so that someone else doesn't have to figure out why a bunch of extraneous things are not relevant at some later time.

Review your site for unused sections, settings that have URLs enabled that don't need to have URLs enabled, unused Fields, Asset Sources and Routes, and whatever else your particular site might have to consider.

Depending on your comfort level and familiarity with the data structure of the plugins you are using, at this point, you may also want to review your database directly. If you're not comfortable with database management, just skip to the next section.

There are several scenarios where you can end up with unused database tables or rows or columns in your database. In most cases, they will not cause issues and in some cases, Craft's decision to leave certain things in the db is a feature, not a bug.

Extraneous tables can be left in your database if you delete a plugin's files from the repository before uninstalling it from the control panel or even when you uninstall a plugin from the control panel, as it is a plugin's responsibility (not Craft's) to decide how to clean up any custom schema when it is uninstalled.

At the very least, I typically look through the database manually and make sure that any tables that related to plugins that were uninstalled have also been removed and ensure that the rows in the craft_plugins table reflect only the plugins that are installed.

Template cleanup

You can also take this opportunity to clean up your templates directory. Remove unused files like demo templates or anything else that's been there a while that you really don't need any longer but you've been too lazy to clean up.

Finally, review and resolve any outstanding Deprecation Warnings. This is the only time these warnings really matter as you're preparing for a major version upgrade. Any items listed here that may still be working on your Craft 2 site are scheduled to break in Craft 3, so review them and get them cleaned up before you hit that upgrade button.

Craft 2 looking good? Time to upgrade to Craft 3: A Fresh Craft 3 Install

This article is part of a series:

1. Evaluation, Setup, and Planning
2. Update Everything on Craft 2
3. A Fresh Craft 3 Install
4. Database Migration (coming soon)
5. Template Migration (coming soon)
6. Custom Plugins & Modules (coming soon)
7. Deploy & Maintain (coming soon)