Backup

Before you do anything else, you should make sure that the current solution is properly backed up. In other words, you should create a copy of the entire eZ Publish directory and the database. The following example shows how this can be done on a Linux/UNIX based system where eZ Publish is using a MySQL database called "example". Note that the system should be closed for access during backups and upgrades.

1.  Navigate into the eZ Publish directory:

   $ cd /path/to/ez_publish
   

2.  Clear all caches:

   $ 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):

   $ ./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. After running the script, make sure that all cache files have been cleared by inspecting the contents of the various cache sub-directories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, remove them manually.

3.  Create a dump of the database:

   $ mysqldump -u root --add-drop-table example > db_backup.sql
   

4.  Go to the parent directory:

   $ cd ..
   

5.  Create a tape archive of the files (including the DB dump) using the "tar" command:

   $ tar cfz backup_of_ez_publish.tar.gz ez_publish
   

    At this point, the file "backup_of_ez_publish.tar.gz" should contain a backup of everything (both files and DB).

Consistency checks

The administration interface makes it possible to quickly check whether the current installation is in a consistent state or not. This can be done using the "Upgrade check" section of the "Setup" part. There are two checks that can be run:

•  File consistency check
•  Database consistency check

File consistency check

The file consistency tool checks if you have altered any of the files that came with the current installation. If this is the case, then the altered files should be backed up before the system is upgraded because they will most likely be overwritten by new versions. Make sure that you backup and then merge in your custom changes into the new versions of the files.

Database consistency check

The database consistency feature checks if the current database is consistent with the database schema that came with the eZ Publish distribution that is currently running. If there are any inconsistencies, the system will suggest the necessary SQL statements that should be ran in order to bring the database into a consistent state. Make sure that the database is backed up and run the suggested SQL statements before upgrading.

Note: If your installation does not have the eZ Network installed, you will get an error message about database inconsistency. This is to be expected and the error message will disappear as soon as the eZ Network is installed. This applies to eZ Publish 4.5 and above.
Note2: If using cluster with the same database as eZ Publish then you will get error message about database inconsistency (specifically: ezdbfile* or ezdfsfile tables). This is a known issue with database inconsistency check combined with clustering, and can safely be ignored. To avoid this you can install cluster tables in a separate database, and make sure this is reflected in config.php and file.ini settings, see "Features > Clustering" for generic information about how to install cluster.

The actual upgrade process

An actual eZ Publish upgrade process is usually carried out in a few steps. First, the current eZ Publish files must be replaced with the files from the new distribution. Secondly, a couple of scripts must be run in order to bring the database (and possibly other things) into a state that is compatible with the upgraded files. In addition, it might be needed to change the system configuration (review some INI settings, add templates, etc.). Refer to the "How to proceed" section for general information about these steps.