MySource Matrix Resources

MySource Matrix has been superseded by Squiz Matrix. This site will remain available for archival purposes only; it is not intended as a current source of Matrix information. For all the latest on Matrix, including documentation and release information, visit the Squiz Matrix site.

Content Tools

Main Content

Upgrading MySource Matrix from v3.22 to v3.24

Introduction

This guide will help you upgrade an existing MySource Matrix version 3.22 installation to version 3.24.

This upgrade requires you to have access to:

  • update the MySource Matrix source code
  • run database queries on the MySource Matrix database
  • edit the MySource Matrix configuration files

This guide assumes that your MySource Matrix installation is located at /home/websites/mysource_matrix. Please change any commands to the appropriate location if your installation is located elsewhere.

This upgrade guide is based upon upgrading from the stable version just before the first 3.24 stable release - that is, from version 3.22.3 to 3.24.0. For upgrading earlier versions of Matrix, it is recommended that you upgrade to at least version 3.22.3 before upgrading to 3.24.0.

This upgrade guide assumes that the server requirements will be upgraded in-place, meaning the MySource Matrix system will remain in the same location.

If your system contains the Squiz Supported Version (SSV) modules, please contact Squiz for updated versions of the modules before proceeding with the upgrade.

The modules must be upgraded at the same time as the core system.

Major version upgrades require you to delete all previous rollback data from your system. Rollback data is incompatible between major versions.

Ensure that you have a current backup of your existing system and rollback data before upgrading.

Stop Editing

No editing should be taking place during a major version upgrade. Before starting the upgrade, first ensure that all editors are logged out of the system.

System administrators can see if there are any active locks on content in the system by clicking on the Automated Patching System icon at the top of the screen, then switching to the Active Locks screen.

Backup

Before starting any upgrade, always backup your MySource Matrix installation. See the MySource Matrix backup management guide for information on how to backup your MySource Matrix system.

Delete Stale HIPO Jobs

During a major version upgrade, stale HIPO jobs should be removed from the system. Log into the MySource Matrix administration interface as root user and go to the HIPO Herder screen. Lock this screen and delete all HIPO jobs that are listed. Note that there may not be any stale HIPO jobs in the system.

Disable Search Indexing

You will need to disable searching from the Search Manager before you undertake this upgrade.

Disable Rollback

At this point, you need to ensure that rollback is disabled before continuing. For help with disabling rollback, see the MySource Matrix rollback management guide.

Disable Cron Run script in Crontab

If you use the Cron system, you will have set up an entry in a Crontab file. It is most likely that it would have been set up for the user Apache runs as, however this depends on your system configuration.

As the user the Crontab entry was installed to, run the following command:

$ crontab -e

Find the entry for Matrix, and add a hash ("#") to the front of the entry to comment it out:

# */15 * * * * php /home/websites/mysource_matrix/core/cron/run.php /home/websites/mysource_matrix

Get the New Source Code

Now, you need to update the MySource Matrix source code. You can find out how to download the latest stable version of MySource Matrix on the installation page.

Once you have downloaded the source code, you need to replace the existing code with the newer version. This will not reset any configuration options or remove any content from your system.

These steps assume MySource Matrix is installed at /home/websites/mysource_matrix and that a tar.gz archive with the new source code exists within /home/websites 
$ cd /home/websites
$ mv mysource_matrix mysource_matrix_3-22-x
$ tar -xzvf new_source.tar.gz
$ cd mysource_matrix
$ cp -pr /home/websites/mysource_matrix_3-22-x/data .
$ cp -pr /home/websites/mysource_matrix_3-22-x/core/lib/DAL/Oven core/lib/DAL
$ cp -pr /home/websites/mysource_matrix_3-22-x/core/lib/DAL/QueryStore core/lib/DAL

Step for Log to System Log support

The step_01 installation script must be run before further steps in order to initialise default configuration values for the "Log to System Log" functionality. This will not affect other existing configuration values. Please run this script from the Matrix root directory as follows: 

$ php install/step_01.php /home/websites/mysource_matrix

Multi-Lingual Support

Please run the following queries which set the structure for Multi-Lingual Support. Some queries below are applicable Oracle and PostGres and a list further below is applicable to both. Please note that the "sq_rb" rollback queries must be run regardless of the previous Rollback state. Rollback should at this point be disabled as per the instructions above.

PostGres 
ALTER TABLE sq_ast_attr_val DROP CONSTRAINT ast_attr_val_pk;
ALTER TABLE sq_ast_attr_uniq_val DROP CONSTRAINT ast_attr_uniq_val_pk;
ALTER TABLE sq_rb_ast_attr_val DROP CONSTRAINT rb_ast_attr_val_pk;
ALTER TABLE sq_rb_ast_attr_uniq_val DROP CONSTRAINT rb_ast_attr_uniq_val_pk;

Oracle 

ALTER TABLE sq_ast_attr_val DROP PRIMARY KEY;
ALTER TABLE sq_ast_attr_uniq_val DROP PRIMARY KEY;
ALTER TABLE sq_rb_ast_attr_val DROP PRIMARY KEY;
ALTER TABLE sq_rb_ast_attr_uniq_val DROP PRIMARY KEY;

Both 

ALTER TABLE sq_ast_attr ADD is_contextable CHAR(1) DEFAULT '0';
ALTER TABLE sq_ast_attr_val ADD contextid INT DEFAULT 0;
ALTER TABLE sq_ast_attr_val ADD use_default CHAR(1) DEFAULT '1';
ALTER TABLE sq_ast_attr_val ADD PRIMARY KEY (assetid, attrid, contextid);
ALTER TABLE sq_ast_attr_uniq_val ADD contextid INT DEFAULT 0;
ALTER TABLE sq_ast_attr_uniq_val ADD use_default CHAR(1) DEFAULT '1';
ALTER TABLE sq_ast_attr_uniq_val ADD PRIMARY KEY (owning_attrid, contextid, custom_val);

ALTER TABLE sq_rb_ast_attr_val ADD contextid INT DEFAULT 0;
ALTER TABLE sq_rb_ast_attr_val ADD use_default CHAR(1) DEFAULT '1';
ALTER TABLE sq_rb_ast_attr_val ADD PRIMARY KEY (sq_eff_from, assetid, attrid, contextid);
ALTER TABLE sq_rb_ast_attr_uniq_val ADD contextid INT DEFAULT 0;
ALTER TABLE sq_rb_ast_attr_uniq_val ADD use_default CHAR(1) DEFAULT '1';
ALTER TABLE sq_rb_ast_attr_uniq_val ADD PRIMARY KEY (sq_eff_from, owning_attrid, contextid, custom_val);

Search Manager: Multi-Context Searching

The following queries are to be executed before running the standard upgrade steps:

All databases: 

ALTER TABLE sq_sch_idx ADD contextid VARCHAR(11) DEFAULT 'default' NOT NULL;
ALTER TABLE sq_sch_idx ADD use_default CHAR(1) DEFAULT '1' NOT NULL;

then...

Postgres: 

ALTER TABLE sq_sch_idx DROP CONSTRAINT sch_idx_pk;
ALTER TABLE sq_sch_idx ADD PRIMARY KEY (value, assetid, component, contextid);

Oracle: 

ALTER TABLE sq_sch_idx DROP PRIMARY KEY;
ALTER TABLE sq_sch_idx ADD PRIMARY KEY (assetid, component, contextid);

Query to clean up unused Shadow Link entries

An issue has been found recently - reported as Bug #3828 ("Online Poll vote linked to Shadow Asset Link Table and not removed"). The result of this bug caused unnecessary database entries related to shadow asset links, for which the parent asset was no longer present in the system.

This issue has been resolved in this release, however it is recommended to clean up existing redundant links in this table for potential performance improvements when searching for shadow asset links.

The query below is valid for both PostGres and Oracle databases: 

DELETE FROM sq_shdw_ast_lnk WHERE majorid NOT IN (SELECT assetid FROM sq_ast);

Query Rebake

A query rebake is required after running the above queries and before running the standard upgrade steps. This is due to structural changes relating to Multi-Lingual / Context support. To rebake system queries please run the following from the Matrix System root directory:

$ php scripts/dev/rebake.php `pwd`

Full System Upgrade

Now, the system's installation scripts should be run to ensure the asset types and language translations are up to date.

$ php install/step_02.php /home/websites/mysource_matrix
$ php install/compile_locale.php /home/websites/mysource_matrix
$ php install/step_03.php /home/websites/mysource_matrix
$ php install/compile_locale.php /home/websites/mysource_matrix

Reset Rollback

Only run this step if your system has rollback enabled. If your system does not use rollback, you can safely skip this step.

Rollback entries should be reset between major versions. For instructions on how to reset rollback, see the MySource Matrix rollback management guide.

Re-enable Cron Run script in Crontab

You can now re-enable your MySource Matrix system's entry in the Crontab in the reverse manner as you did to disable it: by editing the Crontab file and removing the comment (#) from the front of the entry.

Re-enable Rollback

If you needed to disable rollback at the beginning of this upgrade, you may now re-enable it. For help with enabling rollback, see the MySource Matrix rollback management guide.

Re-enable Search Indexing

You can now re-enable indexing of your system. This can be done from the Search Manager.

Upgrade Complete

The upgrade of your MySource Matrix system from version 3.22 to 3.24 is now complete.