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.6 to v3.8

Introduction

This guide will help you upgrade an existing MySource Matrix version 3.6 installation to version 3.8.

This upgrade requires you to have access to:

  • update the MySource Matrix source code
  • run database queries on the MySource Matrix database
  • upgrade 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.

If your system contains the commercial or premium 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.

Upgrading from v3.6 to v3.8 will remove all existing search weighting settings, including individual and global asset weights. These will need to be recreated using the new indexing and weightings systems in v3.8.

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.

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 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.

Getting the New Source Code

The first thing you need to do is 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 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-6
$ tar -xzvf new_source.tar.gz
$ cd mysource_matrix
$ cp -r /home/websites/mysource_matrix_3-6/data .

Lexicon Package Removal

In 3.6, the Lexicon package was part of the commercial module set. In 3.8, the Lexicon assets are now part of the core open source package.

If you currently have the Lexicon package installed in the packages directory, you must remove the old Lexicon files so that the new versions can be installed into the core.

$ cd /home/websites/mysource_matrix
$ rm -rf packages/lexicon

New Database Connection String

Version 3.8 includes a third database connection string to add support for PostgreSQL database replication. You must update your main.inc configuration file to add the third connection string and modify the current value of the second connection string, no matter what database you are using.

The main.inc configuration file is located at /home/websites/mysource_matrix/data/private/conf/main.inc

If you database connection settings current look like this:

define('SQ_CONF_DB_DSN',  'pgsql://user1@db_hostname/matrix');
define('SQ_CONF_DB2_DSN', 'pgsql://user2@db_hostname/matrix');

Change them to look like this:

define('SQ_CONF_DB_DSN',  'pgsql://user1@db_hostname/matrix');
define('SQ_CONF_DB2_DSN', 'pgsql://user1@db_hostname/matrix');
define('SQ_CONF_DB3_DSN', 'pgsql://user2@db_hostname/matrix');

Notice that we have made the first and second connection strings identical and used our second user account for the third connection string.

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.

Update Database Schema

The database schema has changed between 3.6 and 3.8. The step_02.php installation script is able to make some changes to the schema, but other must be run manually.

If you ran the step_02.php installation script to disable rollback, you do not need to run it again for this upgrade step.

To update the schema, first run the step_02.php installation script.

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

If you are using a PostgreSQL database, run the following queries.

ALTER TABLE sq_ast_attr ADD is_admin char(1);
ALTER TABLE sq_ast_attr ALTER COLUMN is_admin SET DEFAULT 1;
UPDATE sq_ast_attr SET is_admin = 1;
ALTER TABLE sq_ast_lnk_tree DROP CONSTRAINT sq_ast_lnk_tree_pkey;
ALTER TABLE sq_ast_lnk_tree RENAME COLUMN treeid TO old_treeid;
ALTER TABLE sq_ast_lnk_tree ADD COLUMN treeid bytea;
ALTER TABLE sq_ast_lnk_tree ALTER COLUMN old_treeid DROP NOT NULL;
ALTER TABLE sq_rb_ast_lnk_tree DROP CONSTRAINT sq_rb_ast_lnk_tree_pkey;
ALTER TABLE sq_rb_ast_lnk_tree RENAME COLUMN treeid TO old_treeid;
ALTER TABLE sq_rb_ast_lnk_tree ALTER COLUMN old_treeid DROP NOT NULL;
ALTER TABLE sq_rb_ast_lnk_tree ADD COLUMN treeid bytea;

If you are using an Oracle database, run the following queries.

ALTER TABLE sq_ast_attr ADD is_admin char(1);
ALTER TABLE sq_ast_attr MODIFY is_admin DEFAULT 1;
UPDATE sq_ast_attr SET is_admin = 1;

begin
for rec in (select constraint_name FROM user_constraints WHERE table_name='SQ_AST_LNK_TREE' AND constraint_type='P') loop
execute immediate 'alter table sq_ast_lnk_tree drop constraint ' || rec.constraint_name;
end loop;
end;
/

ALTER TABLE sq_ast_lnk_tree RENAME COLUMN treeid TO old_treeid;
ALTER TABLE sq_ast_lnk_tree ADD treeid VARCHAR(2000);
ALTER TABLE sq_ast_lnk_tree MODIFY old_treeid NULL;

begin
for rec in (select constraint_name FROM user_constraints WHERE table_name='SQ_RB_AST_LNK_TREE' AND constraint_type='P') loop
execute immediate 'alter table sq_rb_ast_lnk_tree drop constraint ' || rec.constraint_name;
end loop;
end;
/

ALTER TABLE sq_rb_ast_lnk_tree RENAME COLUMN treeid TO old_treeid;
ALTER TABLE sq_rb_ast_lnk_tree MODIFY old_treeid NULL;
ALTER TABLE sq_rb_ast_lnk_tree ADD treeid VARCHAR(2000);
Search Package

If you have the Search package installed, you need to make some minor changes to the search database schema.

If you are using a PostgreSQL database, run the following queries.

TRUNCATE TABLE sq_sch_idx;
ALTER TABLE sq_sch_idx ADD COLUMN assetid_tmp VARCHAR(255);
UPDATE sq_sch_idx SET assetid_tmp = CAST(assetid AS VARCHAR(255));
ALTER TABLE sq_sch_idx DROP COLUMN assetid;
ALTER TABLE sq_sch_idx RENAME COLUMN assetid_tmp TO assetid;
ALTER TABLE sq_sch_idx ALTER COLUMN assetid SET NOT NULL; 
ALTER TABLE sq_sch_idx ADD type_code VARCHAR(100);
ALTER TABLE sq_sch_idx ALTER COLUMN type_code SET NOT NULL;

If you are using an Oracle database, run the following queries.

TRUNCATE TABLE sq_sch_idx;
ALTER TABLE sq_sch_idx MODIFY assetid VARCHAR(255);
ALTER TABLE sq_sch_idx ADD type_code VARCHAR(100);
ALTER TABLE sq_sch_idx MODIFY type_code NOT NULL;

Link Tree Upgrade

The link tree is a lookup table MySource Matrix uses to support multiple linking of assets. The link tree's database schema received an upgrade in 3.8 for wider database support.

Recreate the Link Tree

The link tree must be recreated to support its new database schema. You can use a script to do this for you.

$ php scripts/recreate_link_tree.php /home/websites/mysource_matrix > link_tree_entries.sql

Then, if you are using a PostgreSQL database

$ psql -U user database < link_tree_entries.sql

or if you are using an Oracle database

$ sqlplus user/password@SID @link_tree_entries.sql
Database Schema Changes

If you are using a PostgreSQL database, run the following queries.

DELETE FROM sq_ast_lnk_tree WHERE treeid IS NULL;
ALTER TABLE sq_ast_lnk_tree ALTER COLUMN treeid SET NOT NULL;
ALTER TABLE sq_ast_lnk_tree ALTER COLUMN treeid SET DEFAULT ''::bytea;
ALTER TABLE sq_ast_lnk_tree ADD PRIMARY KEY (treeid);
ALTER TABLE sq_ast_lnk_tree DROP COLUMN old_treeid;
DELETE FROM sq_rb_ast_lnk_tree WHERE treeid IS NULL;
ALTER TABLE sq_rb_ast_lnk_tree ALTER COLUMN treeid SET NOT NULL;
ALTER TABLE sq_rb_ast_lnk_tree ALTER COLUMN treeid SET DEFAULT ''::bytea;
ALTER TABLE sq_rb_ast_lnk_tree ADD PRIMARY KEY (sq_eff_from, treeid);
ALTER TABLE sq_rb_ast_lnk_tree DROP COLUMN old_treeid;
DROP FUNCTION sq_get_parent_treeids(VARCHAR, INT);
DROP FUNCTION sq_rb_get_parent_treeids(VARCHAR, INT);

If you are using an Oracle database, run the following queries.

ALTER TABLE sq_ast_lnk_tree MODIFY treeid DEFAULT '';
ALTER TABLE sq_ast_lnk_tree ADD PRIMARY KEY (treeid);
ALTER TABLE sq_ast_lnk_tree DROP COLUMN old_treeid;
DELETE FROM sq_rb_ast_lnk_tree WHERE treeid IS NULL;
ALTER TABLE sq_rb_ast_lnk_tree MODIFY treeid NOT NULL;
ALTER TABLE sq_rb_ast_lnk_tree MODIFY treeid DEFAULT '';
ALTER TABLE sq_rb_ast_lnk_tree ADD PRIMARY KEY (sq_eff_from, treeid);
ALTER TABLE sq_rb_ast_lnk_tree DROP COLUMN old_treeid;
DROP FUNCTION sq_get_parent_treeids;
DROP FUNCTION sq_rb_get_parent_treeids;

Upgrade Access Restrictions

By default, all users are granted unrestricted access to asset screens in 3.8. In 3.6, unrestricted access had to be granted for each user group to allow editors to view asset screens.

The following database query upgrades the access restrictions system.

DELETE FROM sq_ast_edit_access WHERE type_code = 0 AND screen = 0 AND section = 0;

Upgrade the Core Asset Types

The core assets types must be upgraded before the packages, so the step_03.php installation script must be told to only upgrade the core asset package.

$ php install/step_03.php /home/websites/mysource_matrix --package=core

Calendar Package Upgrade

If you have the Calendar package installed, you need to upgrade it before the other package upgrades are run. Again, we tell the step_03.php installation script to upgrade a single package only.

$ php install/step_03.php /home/websites/mysource_matrix --package=calendar

Lexicon Package Upgrade

If you have the Lexicon package installed, you need to upgrade your existing thesaurus assets as the XML file format and database schema has been changed.

$ php scripts/upgrade_thesaurus_db.php /home/websites/mysource_matrix

If you use the synonym searching feature of the search package with a thesaurus, change your synonyms relation name to synonym.

Full System Upgrade

We can now run an upgrade on all installed packages. We use the step_03.php installation script to install new asset types and upgrade old ones, and then the compile_locale.php script to ensure our language translations are up to date

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

Reindex Search Data

If you have the Search package installed, you need to reindex your entire system. The upgrade removed all existing index data, so this must be recreated.

Log into the MySource Matrix administration interface as the root user and go to the details screen of the Search Manager. You can reindex the whole system from here.

Before doing the reindex, you should configure your indexing and weightings rules. The indexing and weightings systems are significantly improved in version 3.8 and offer much finer control over the search index. All weightings are now controlled from the Search Manager.

Reset Rollback Data

If you use the rollback feature of MySource Matrix, you can re-enable it at this time. You must use the --reset-rollback option when running the rollback management script to ensure all rollback data is deleted before rollback is started.

For help with resetting rollback, see the MySource Matrix rollback management guide.