Database Upgrade Guide

This page takes you through the general steps for upgrading product versions based on Carbon 4.0.0 to Carbon 4.2.0. For example, upgrading IS 4.0.0 (based on Carbon 4.0.0) to IS 4.5.0/4.6.0 (based on Carbon 4.2.0). For more information on release versions, see the Release Matrix.

Preparing to Upgrade

The following are the specific prerequisites you must complete before an upgrade:

Before you upgrade to the latest version of a product, you create a staging database, which is essentially an empty database. Note that you should NOT connect a new product version to an older database that has not been upgraded.

When migrating a system, a replica of the production system is first simulated in the staging server, which is then migrated. This staging system can run parallel to the production system for a period of time to test if everything runs smoothly. After that, the staging system is connected as the production system by switching the DNS and domain names.
Make a backup of the database and the <PRODUCT_HOME> directory prior to upgrading. The <PRODUCT_HOME> directory can simply be copied to the new directory.
Stop all the Carbon servers connected to the database before running the migration scripts.

Note that the upgrade should be done during a period when there is low traffic on the system.

Limitations

This upgrade can only be done if the database type is the same. For example, if you are using MySQL currently and you need to migrate to Oracle in the new version, these scripts will not work.
You cannot roll back an upgrade. It is impossible to restore a backup of the previous server and retry the upgrade process.

Downtime

The downtime is limited to the time taken for switching databases when the staging database is promoted to the actual production status.

Upgrading the database

To upgrade the existing production database:

Stop the current server.
Select the relevant script for the upgrade from here on the production database. The script you use will depend on the type of database you are using, for instance, if your database is MySQL, you need to run the execute mysql-migration.sql command in MySQL. Running this script will ensure that the database is upgraded with the additional tables and schemas which are required for the new product version.

There are three migration scripts available: migration-service-provider.sql, migration-identity.sql and migration.sql. However, for all Carbon products except WSO2 IS, only the migration.sql script is required to be executed.
Once you run the migration script on the production database, copy the data to the staging database you created. This becomes the new database for your new product version.

Since the system was shut down for a period during the migration, you may have to manage the data that was collected in the production system during that period. In such situations, the database administrator should collect the data portion, which is added to the production database while the migration is happening. This data can then be inserted into the migrated database using a script. WSO2 support team will be there to help in these types of situations.
Download the new product version and connect it to your staging database.

Recommended checkpoints

The databases should contain the newly added tables, which are namely as follows:

UM_DOMAIN
UM_SYSTEM_USER
UM_SYSTEM_ROLE
UM_SYSTEM_USER_ROLE

Going into production

The following are recommended tests to run on the staging system.

Create multiple user stores and try adding users to different user stores.
Create multiple tenants and add different user stores to the different tenants. Thereafter, add users to the various user stores.

Once the above tests are run successfully, it is safe to consider that the upgrade is ready for production. However, it is advised to test any features that are being used in production.