Upgrading from 3.a.b to 3.x.y

This section describes how to upgrade your existing eZ Publish 3.a.b installation to version 3.x.y. In order to benefit from the latest security and bug fixes, choose the latest stable release in the desired branch.

If version 3.a.b is a few branches older than version 3.x.y, split the upgrade process into several stages. This means that you should upgrade directly to the next stable release branch, and then to the next one, etc. until you reach the desired version. While the last direct upgrade in the chain should be done to version 3.x.y, there are two different rules about which intermediary 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. Refer to the "How to proceed" section for more information and examples.

The following text explains how to do a direct upgrade to the next stable release branch. In addition, the instructions below can be used to upgrade directly from eZ Publish 3.6 to version 3.8.

The procedure for directly upgrading from version 3.a.b to 3.x.y consists of the following steps:

1. Upgrading the distribution files to version 3.x.y.
2. Upgrading the database schema to version 3.x.y.
3. Running the system upgrade scripts for versions from 3.a.b to 3.x.y.
4. Updating the system configuration for compatibility with all the changes made from version 3.a.b to 3.x.y.
5. Clearing the caches.

Make sure that you have a working backup of the site before you do the actual upgrade.

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 3.x.y to a separate directory and then copy the directories that contain site-specific files from the existing installation. Make sure that you copy the following directories:

• design/example
• design/example_admin
• var
• settings/siteaccess
• settings/override

Replace "example" and "example_admin" with the actual names of your siteaccesses. (If you have more than two siteaccesses, copy the design subdirectories for the others as well.)

Custom extensions

If you are using custom extensions, the subdirectories inside the "extension" directory will also have to be copied. However, make sure that you do not overwrite any extensions that come with eZ Publish (for example the "PayPal" extension).

Version specific notes

There may be some additional notes about upgrading the distribution files for each particular version of eZ Publish. For example, you may need to upgrade some extensions for compatibility with eZ Publish 3.x.y or download additional files. Read the first step of the upgrade manuals for the target branch and make sure you do not miss anything important.

For example, when upgrading from 3.6 to 3.8.10, you need to quickly skim through the first step of the "Upgrading from 3.6.x or 3.7.x to 3.8.0" and "Upgrading from 3.8.x to 3.8.y" manuals. You will see that the latter one contains an important note about downloading an additional file in order to make your user registration mechanism work properly in 3.8.10.

Step 2: Upgrading the database

New eZ Publish releases usually include database changes. This means that the old database needs to be converted. To upgrade an eZ Publish database from version 3.a.b to 3.x.y, navigate into the eZ Publish 3.x.y directory and run the database upgrade scripts one after another following the official upgrade path. The upgrade scripts are located under the "update/database/mysql" directory (or "update/database/postgresql" if you are using PostgreSQL).

The following table shows examples for upgrading an eZ Publish database to different versions. Note that some scripts can be skipped since they do not do anything except update the version number (these are encapsulated by square brackets in the table).

MySQL

A database upgrade script can be launched using the following shell command:

mysql -uUSERNAME -p[PASSWORD] DATABASE < update/database/mysql/BRANCH/dbupdate-VERSION1-to-VERSION2.sql

for example:

mysql -umyuser -pmypass mydatabase < update/database/mysql/3.5/dbupdate-3.4.4-to-3.5.0.sql

Note that the CREATE TABLE statements in the database upgrade scripts for eZ Publish 3 do not specify which storage engine to use (no ENGINE or TYPE option), and thus the default storage engine will be used. Normally, it is MyISAM (starting from MySQL v.3.23). If you are using InnoDB, make sure the default storage engine is set to InnoDB before you run the database upgrade scripts (refer to the MySQL documentation for information about how to set the default engine). If you were not able to change the MySQL configuration on your server, and the upgrade left you with a mix of table types, you can use the "bin/php/ezconvertmysqltabletype.php" script for database conversion. The script is available in eZ Publish 3.6.0 and later versions.

It is also possible to convert the newly created tables to InnoDB using ALTER TABLE statements as shown in the following example:

ALTER TABLE table_name1 TYPE = innodb;
ALTER TABLE table_name2 TYPE = innodb;
...

Replace "table_name1", "table_name2" with the actual names of the tables that need to be converted.

PostgreSQL

A database upgrade script can be launched using the following shell command:

psql -d DATABASE -U DBOWNER < update/database/postgresql/BRANCH/dbupdate-VERSION1-to-VERSION2.sql

for example:

psql -d mydatabase -U myuser < update/database/postgresql/3.5/dbupdate-3.4.4-to-3.5.0.sql

Step 3: Running the system upgrade scripts

A new release often introduces some new functionality that requires your existing data (like content classes, objects, nodes, search index etc.) to be updated. When upgrading, you may need to run some upgrade scripts in order to make your site compatible with the new features added between 3.a.b and 3.x.y. You will find most of the system upgrade scripts in the "update/common/scripts" subdirectory of the eZ Publish 3.x.y directory. To find out which scripts need to be run, view the list of the system upgrade scripts.

The following table contains examples showing which system upgrade scripts to run when upgrading to the different versions.

How to run the system upgrade scripts

All the scripts must be run from the root directory of your eZ Publish installation. Read the information indicated in the list of the system upgrade scripts for the script before running it. Note that sometimes a specific configuration change needs to be done before running a particular upgrade script. For more detailed information about how to run each script, refer to the third step in the upgrading instructions for the version of eZ Publish in which this script was added. You can also find a few general recommendations below.

In most cases, the only thing that an upgrade script does is modify some data in the database. Such scripts should be run once for each database, specifying one siteaccess per database. If you only have a public and an administration siteaccess that share the same database (which is the most typical/usual case), you only need to run the script for one of the siteaccesses.

1. Navigate into the eZ Publish 3.x.y directory.
2. Run the script (replace <script> with the actual name of the script and <siteaccess> with the name of your siteaccess(es)):

   php update/common/scripts/<script>.php -s<siteaccess>
   

This requires that you have PHP CLI enabled. Note that sometimes it is also possible (but not recommended since it might cause problems) to use the CGI version, which supports the CLI behavior by means of the -C switch when run from the command line:

php -C update/common/scripts/<script>.php -s<siteaccess>

In eZ Publish 3.0-2 and later versions, the system upgrade scripts are executable so that they can be run as normal shell scripts on a Linux/UNIX based system:

update/common/scripts/<script>.php -s<siteaccess>

Use "--help" or "-h" to output the information about the script and its parameters:

php update/common/scripts/<script>.php --help
php update/common/scripts/<script>.php -h

Step 4: Updating the system configuration

After running the upgrade scripts above you may need to review some of your configuration settings in order to be compatible with the changes that have been added. Read the fourth step of the upgrading instructions for each particular version of eZ Publish that is between 3.a.b and 3.x.y.

For example, when upgrading directly from 3.5.11 to 3.6.11, you should read the fourth step of the instructions in the "Upgrading from 3.5.2 to 3.6.0" and "Upgrading from 3.6.x to 3.6.y" manuals. According to these instructions, you may need to do the following:

• Enable new toolbars in the administration interface.
• Configure the system to show hidden nodes in the administration interface.
• Create custom classes for the newly added "embed" XML tag, and add a new template for rendering the content of this tag.
• Enable database transaction support.
• Review configuration settings for the "literal" XML tag.

Step 5: Clearing the caches

Whenever an eZ Publish solution is upgraded, all caches must be cleared in a proper way. This should be done from within a system shell:

1. Navigate into the eZ Publish 3.x.y directory.
2. Run the clear cache script:

   bin/shell/clearcache.sh --clear-all
   

   
   If you have PHP CLI installed, you can also do the following (this script should also work on Windows):
   

   php bin/php/ezcache.php --clear-all --purge
   

   
   From 3.10, the "clearcache.sh" script has been disabled. This means that the file is still present but the code inside is removed. It outputs a message telling the user to use "bin/php/ezcache.php". In other words, you have to use "ezcache.php" instead.

Sometimes the script is unable to clear caches because of restrictive file/directory permission settings. Make sure that all caches have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are caches left, you need to remove them manually.