This section describes how to upgrade your existing eZ Publish installation to a newer version.

If you are running one of the supported versions, it is recommended to upgrade your installation when the next stable release within that branch is out. The instructions for upgrading within the same stable release branch can be found in the upgrade manuals of that branch.

If you are running a version which is no longer supported, it is highly recommended to switch to a supported one. For example, if you are running eZ Publish 4.1, consider upgrading to version 4.5 or later. In order to benefit from the latest security and bug fixes, choose the latest stable release in the desired branch. You can either upgrade directly or split the upgrade process into several stages (depending on the number of stable release branches between your current version and the desired one).

Direct upgrade

If you want to upgrade directly from version X to version Y, the upgrade procedure consists of the following steps:

1. Upgrading the distribution files to version Y.
2. Upgrading the database schema to version Y following the official upgrade path.
3. Running the system upgrade scripts for versions between X and Y.
4. Updating the system configuration for compatibility with all the changes made from version X to Y.
5. Clearing the caches.

This procedure is only applicable when upgrading to the next stable release branch. Skipping a branch is not recommended, since some of the system upgrade scripts might not be present (or not work correctly) in later versions. The only exception is that you can upgrade directly from eZ Publish 3.6 to version 3.8.

The instructions for direct upgrading from version 3.a.b to 3.x.y can be found here. In order to upgrade from version 3.10 to 4.0, refer to the eZ Publish 4.0 upgrade manuals.

Two upgrades

If a lot of changes were made between versions X and Y, you can do the following:

1. Upgrade from version X to some intermediate version Z.
2. Make sure that your site is working correctly.
3. Upgrade from version Z to version Y.

Example 1

If you are running eZ Publish 3.8.x, you cannot upgrade directly to 3.10.y, because the system upgrade scripts needed for eZ Publish 3.9 might not work correctly in 3.10. However, you can upgrade to some intermediate version 3.9.z first and then upgrade to version 3.10.y.

Example 2

It is not possible to upgrade directly from eZ Publish 3.9 to version 4.0, and the 4.0 distribution does not contain upgrade scripts for this. The solution is to upgrade to 3.10 first, and then upgrade to 4.0.

Multiple upgrades

It is also possible to split the upgrade process into three or more stages. Since each branch introduces a set of new features, you have to do one upgrade for each stable release branch between versions X and Y. For example, if you are running eZ Publish 3.7 and want to run 3.10, you have to upgrade to 3.8 first, then to 3.9 and then finally to 3.10.

While the last direct upgrade in the chain should be done to the latest stable release in the desired branch, there are two different rules about which versions to choose for preceding upgrades. You can either follow the official upgrade path for database schema changes or select the latest stable release in each branch. The following text describes the advantages and disadvantages of both approaches.

The "database upgrade path" approach

This approach makes it possible to minimize the number of database upgrade scripts involved and avoid situations where you need to skip some parts in the ".sql" files when upgrading the database. In the example above, the official upgrade path for database changes looks like this:

3.7 -> 3.8.0 -> 3.9.0 -> 3.10

This means that you should upgrade to 3.8.0 first, then to 3.9.0 and then finally to 3.10.

The disadvantage of this approach is that you upgrade to early versions in each branch, which may contain bugs that were fixed in later releases. (Important bugs are mentioned in the upgrade instructions for certain versions of eZ Publish. In addition, changelogs provide information about all issues that were fixed in the latest releases.)

If an early version contains a bug that may corrupt your data, you can either fix the problem yourself (if possible) or upgrade to a later release where this issue was fixed. For example, when upgrading from 3.8 to 3.9 you need to run the "correctxmltext.php" upgrade script. If you run this script when upgrading to 3.9.0, it will crash due to a bug. To make it work, you need to edit the script file manually as described here. Another option is to skip version 3.9.0 and upgrade directly to version 3.9.1 or a later 3.9.x release where the updated version of the script is available.

The "latest stable release" approach

Upgrading directly to the latest stable release in every branch between X and Y allows you to avoid dealing with possible bugs that might be present in earlier versions. With this approach, the path for upgrading from eZ Publish 3.7 to version 3.10 would look like this:

3.7 -> 3.8.10 -> 3.9.4 -> 3.10

This means that you should upgrade to 3.8.10 first, then to 3.9.4 (the latest stable release in the 3.9.x branch at the time of writing) and then finally to 3.10.

Generally, this approach requires running more database upgrade scripts than the previous one (since there is usually one database upgrade script for each stable release). However, you can reduce the number of database upgrade scripts to run by skipping all version-focused scripts for intermediary versions.

The disadvantage of the "latest stable release" approach is that you might have to skip some parts of the database upgrade scripts if the database schema was changed from previous stable releases within the same branch. This is because the upgrade scripts between branches contain all of the necessary schema changes from the first stable release in the older branch to the first stable release in the newer branch. (Refer to "Notes about database changes" for more information about the database schema changes within stable release branches.)

For example, in eZ Publish 3.8.5, some database schema changes were introduced as a bug fix for missing indexes in database tables. The fix was added to both eZ Publish 3.8.5 and 3.9.0 beta1 and included in the following database upgrade scripts:

• .../3.8/dbupdate-3.8.4-to-3.8.5.sql
• .../3.9/unstable/dbupdate-3.9.0alpha1-to-3.9.0beta1.sql
• .../3.9/dbupdate-3.8.0-to-3.9.0.sql

If you are upgrading to eZ Publish 3.9 from version 3.8.5 or later, running the "dbupdate-3.8.0-to-3.9.0.sql" upgrade script will produce an error, because your 3.8.5 database already contains some of the database schema changes included in this ".sql" file. The solution is to skip the part marked with "from 3.8.5" comments in this file.