This section describes how to upgrade your existing eZ Publish 2.9-7 installation to version 3.0-1. If you are upgrading from a version prior to eZ Publish 2.9-7, you need to first upgrade to 2.9-7 before you can upgrade to 3.0-1.

Please make sure that you have a working backup of the site before you do the actual upgrade. The upgrade procedure consists of the following steps:

1. Upgrading the distribution files to 3.0-1
2. Upgrading the database to 3.0-1
3. Running the 3.0-1 upgrade scripts
4. Updating the system configuration
5. Clearing the caches

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 3.0-1 to a 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 actual names used by your siteaccesses.

Custom extensions

If you are using custom extensions then 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).

Step 2: Upgrading the database

The following text describes how a 2.9-7 database can be upgraded to 3.0-1.

MySQL

1. Navigate into the eZ Publish 3.0-1 directory.
2. Run the database upgrade script:

   mysql -u<username> -p<password> <database> < update/database/mysql/3.0/dbupdate-2.9-7-to-3.0-1.sql
   

PostgreSQL

1. Navigate into the eZ Publish 3.0-1 directory.
2. Run the database upgrade script:

   psql -d <database> -U <dbowner> < update/database/postgresql/3.0/dbupdate-2.9-7-to-3.0-1.sql
   

Step 3: Running the 3.0-1 upgrade scripts

The 3.0-1 version of eZ Publish introduces a couple of new features. In order to make sure that your site is compatible with these feature, you'll have to run a couple of upgrade scripts.

Updating nice URLs

In eZ Publish 3.0, the virtual URLs (nice URLs, URL aliases) are automatically generated and maintained for all nodes. The generated URL for a node is based on the node's location in the tree and the actual name of the object that the node encapsulates. In order to be compatible with this feature, you will need to run the "updateniceurls.php" script:

1. Navigate into the eZ Publish 3.0-1 directory.
2. Run the script using the following shell command:

   php update/common/scripts/updateniceurls.php
   

The script will generate virtual URLs for all your content nodes.

Updating XML fields

In eZ Publish 3.0-1, the "ezxmltext" datatype has been changed in order to store an XML code using UTF-8 encoding (see the 3.0-1 changelog for more information). In order to be compatible with this feature, you will need to run the "updatexmltext.php" script:

1. Navigate into the eZ Publish 3.0-1 directory.
2. Run the script using the following shell command:

   php update/common/scripts/updatexmltext.php
   

The script will automatically convert your XML fields to new format. It is recommended to create a database backup before using this script.

Updating the search index data

In eZ Publish 3.0-1, the built-in search engine has been improved (see the 3.0-1 changelog for more information) and thus you will need to update the search index of your site when upgrading. To do this, clear the search index tables in your database (these are called "ezsearch_word" and "ezsearch_object_word_link") and run the "updatesearchindex.php" script:

1. Navigate into the eZ Publish 3.0-1 directory.
2. Run the script using the following shell command:

   php update/common/scripts/updatesearchindex.php
   

Step 4: Updating the system configuration

You are not required to do any configuration changes when upgrading from 2.9-7 to 3.0-1.

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.0-1 directory.
2. Run the clear cache script:

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

Please make sure that all caches are cleared. 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.