This article is intended to be a companion to my how-to on upgrading a concrete5 site manually. It's easy to get mixed up when working with multiple backups of a site, etc. If some part of the process doesn't seem like it's working correctly, it's probably a good time to stop and check to make sure you're trying to mate the correct versions of code and data.
Core version vs. database schema version
Often when an upgrade fails and the resulting site exhibits odd behavior (MySQL errors, broken editing interface, etc), the problem is that some of the components that make up your site were upgraded while others weren't.
You can think about a concrete5 site's anatomy, on a very simple level, as consisting of three parts:
The concrete5 core. These are the replaceable files located in (your_site_root)/concrete, or if you've upgraded in the past, (your_site_root)/updates/concrete5.x.x.x
Your MySQL database that contains your data. This is set up with a an organizational structure, or schema, that describes your pages, content, etc in a way that a certain version of the core can understand.
Your files, packages, overrides and local config info. These are unique to your site and aren't terribly relevant to the concrete5 upgrade process. We can probably ignore these for now, but FYI, these would be located in root of your site, under the files, packages, blocks, controllers, and other directories.
The takeaway from all this? Your database version needs to match your active core version. If these are mis-matched, you'll encounter trouble. We run the upgrade script (from the dashboard, or from the direct tools url) to make an "old version" database agree with the "new version" core.
Keep in mind that if you're juggling backups, swapping in an old core to try to fix something, or similar, you'll want to keep this stuff straight. Know that there really isn't an easy way to revert a database backwards, to work with an earlier version of the core. So it's important to back your site's database up, fully, before attempting a core upgrade. Do that and you'll never be stuck with such a problem.
So how can I conclusively determine what version of concrete5 I'm running?
Perhaps your site's Dashboard is inaccessible. Given our two important site components (our database, and our active concrete5 core), we can look in a couple specific places to find out which version is needed by each.
To see what version of concrete5 the database matches, check out the Config table. I'm using the command-line MySQL interface, but you could always use a utility like phpMyAdmin as well. The query you'd want is:
select * from Config;
This prints everything in the Config table. In the cfKey column we'll see an entry for SITE_APP_VERSION and a value in the cfValue column that matches. In this screenshot, we see that my database matches a version 22.214.171.124 core:
Interesting side note: if APP_LATEST_VERSION contains a higher number than SITE_APP_VERSION, that means your site was notified that a new core upgrade had become available, at some point.
Your core files
First we'll need to figure out where concrete5 is looking for your core files. In concrete5, there are essentially two options-- the default location, or the subfolder in the updates directory. So let's check the site's config file for such a reference. Open (your_site_root)/config/site.php and look for a line similar to this:
If config.php includes this line, concrete5 is looking for a concrete5 core located in (your_site_root)/updates/concrete126.96.36.199/concrete.
If config.php does not have a line that defines DIRNAME_APP_UPDATED, your site is looking for its core at the default location, (your_site_root)/concrete.
That should tell you where to look next. Go to the concrete/ folder your site is using and check out concrete/config/version.php:
Opening this file in a text editor reveals that it's just a couple lines. The code checks to see if the concrete5 environment is loaded (a quick access check to prevent this file from being loaded directly), then it contains a line like so:
$APP_VERSION = '188.8.131.52';
This defines the version of the core.
So what if the database version and the core version don't match?
You're likely to run into problems, if you haven't already, because the core is trying to reference stuff that may not exist in your old database, or vice versa.
Scenario #1: Core is newer than the database (and you want finish the upgrade)
In this case, you can run the upgrade script directly from its url in your tools directory:
If all goes well, this will update the database schema to match the core. It's a good idea to make sure you have a copy of the unaltered database hanging around in case something doesn't work.
Scenario #2: Core is older than the database (and you want finish the upgrade)
In this case, you'll need to get a new version of the core from our downloads page.
The easiest method is to extract it to your updates/ folder, as described above, then add a line to config.php (or update an existing line) telling concrete5 to use the new core:
Keep in mind that this should be inside the php tags, just like all the other constants set up in there.
An alternate approach is to set the old concrete/ directory aside, then replace it with a new version that you've downloaded. This is generally only recommended in certain special situations. See this article for more info.
Finishing Up One of the two methods above should get your site's database and core to agree. This is often a simple thing to fix, but's it's not uncommon for folks to miss a step or try an outdated approach they read about in an old discussion thread.
Of course, it's always a good idea to clear your cache once you've tested your site to make sure it's running properly.