This page takes you through the steps for upgrading from SS 1.0.3 version to SS 1.1.0. For more information on release versions, see the Release Matrix.
Preparing to upgrade
The following are the specific prerequisites you must complete before you upgrade WSO2 SS:
Before you upgrade to the latest version of WSO2 SS, you create a staging database, which is essentially an empty database. Note that you should NOT connect a new version of WSO2 SS to an older database that has not been upgraded.
Make a backup of the database and the <SS_HOME> directory prior to upgrading. The <SS_HOME> directory can simply be copied to the new database.
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 for some database types. 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.sqlcommand in MySQL. Running this script will ensure that the database is upgraded with the additional tables and schemas (relevant to the Carbon platform change between SS 1.0.3 and SS 1.1.0) which are required for the new SS version.There are three migration scripts available:
migration-service-provider.sql,migration-identity.sqlandmigration.sql. However, for all Carbon products except WSO2 IS, only themigration.sqlscript is required to be executed.Download the SS specific database upgrade scripts from here. Open a command prompt and run the scripts from the location of where you saved the downloaded script. This will upgrade the production database with database level changes in SS 1.1.0 version.
Once you run the relevant scripts (given in step 2 and 3) on the production database, copy the data from the production database to the staging database you created. This becomes the new database for your new version of WSO2 SS.
You can now download the new SS version and connect it to your staging database.
Upgrading the configurations
To migrate the configurations to the staging database:
- Configure the following files for the new production server. See the instructions for changing the default RSS configuration for details on how to update these files.
- Go to the
<SS_HOME>/repository/conf/datasources directory and update themaster-datasources.xml file. - Go to the
<SS_HOME>/repository/confdirectory and update datasource references in theuser-mgt.xmlandregistry.xml files. - Go to the
<SS_HOME>/repository/confdirectory and update thepersistence.xmlandrss-config.xmlfiles.
- Go to the
Perform any configurations required for the server, e.g., external user stores, clustering, caching, mounting.
Note that configurations should not be copied directly between servers.
- Start the server.
Recommended checkpoints
The databases should contain the newly added tables, which are namely as follows:UM_DOMAINUM_SYSTEM_USERUM_SYSTEM_ROLEUM_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.