Notes about database changes

This section explains which database upgrade scripts can be skipped when upgrading an eZ Publish database to a newer version. In addition, it provides an overview of the database schema changes within stable release branches of eZ Publish.

Version-focused database upgrade scripts

When upgrading an eZ Publish database from version X to version Y, you have to run a set of the database upgrade scripts following the official upgrade path. This basically means that you need to run one database upgrade script for each stable release between X and Y. However, it often happens that a ".sql" file of the script only contains one or two lines with something like this:

UPDATE ezsite_data SET value='Z' WHERE name='ezpublish-version';
UPDATE ezsite_data SET value='N' WHERE name='ezpublish-release';

In this case, a database upgrade script is called "version-focused", since it does not do anything except update the current version number, which is stored internally in the system. When upgrading an eZ Publish database, you can skip all version-focused scripts for intermediary versions, as shown in the example below.

Example

In order to upgrade an eZ Publish database from version 3.6.0 to 3.8.10, you should run eleven database upgrade scripts:

• dbupdate-3.6.0-to-3.8.0.sql
• dbupdate-3.8.0-to-3.8.1.sql
• dbupdate-3.8.1-to-3.8.2.sql
• dbupdate-3.8.2-to-3.8.3.sql
• ...
• dbupdate-3.8.9-to-3.8.10.sql

There are seven version-focused upgrade scripts, meaning that seven of the scripts in the list contain only two lines (that simply update the version number) and can be skipped. Therefore, the list of scripts to run contains four items instead of eleven:

• dbupdate-3.6.0-to-3.8.0.sql
• dbupdate-3.8.0-to-3.8.1.sql
• dbupdate-3.8.4-to-3.8.5.sql
• dbupdate-3.8.9-to-3.8.10.sql

Running these four scripts is equivalent to running all the eleven scripts mentioned above.

Database schema changes

If a database upgrade script is not version-focused (contains more than two lines), this usually means that the database structure was changed since the previous release. This is very typical for the first stable release in a branch, since there are usually some database schema changes as compared to the previous branch.

Within stable release branches, database schemas are generally not changed. In other words, once the first stable release in a branch is out, the database schema should remain unchanged. However, exceptions are made for changes that are needed for important bugs and enhancements. When the next stable release in the current branch is out, the change will be present in the database upgrade script for it. In addition, such a bug fix also gets included in the next / upcoming branch for which there are no stable releases yet; the fix will be present in the database upgrade script for the first stable release in this branch (these are mentioned as 3.x.0 versions in the table below).

The following table provides an overview of the database changes within stable release branches of eZ Publish, starting from version 3.6.

UPDATE ezpolicy SET function_name='administrate' WHERE module_name='shop' AND function_name='adminstrate';

ALTER TABLE ezcontentclass CHANGE COLUMN serialized_name_list serialized_name_list longtext default NULL;
ALTER TABLE ezcontentclass_attribute CHANGE COLUMN serialized_name_list serialized_name_list longtext NOT NULL;

ALTER TABLE ezvatrule CHANGE country country_code varchar(255) DEFAULT '' NOT NULL;