Upgrading from a Previous Release

This page takes you through the steps for upgrading from AS 5.1.0 version to AS 5.2.0. For more information on release versions, see the Release Matrix.

If you want to migrate your Application Server configurations from one instance to another (such as when promoting your instance from test to production) using the same Application Server release, see Migrating AS.

Preparing to upgrade

Following are the specific prerequisites you must complete before you upgrade WSO2 AS:

Before you upgrade to the latest version of WSO2 AS, you create a staging database, which is essentially an empty database. Note that you should NOT connect a new version of WSO2 AS to an older database that has not been upgraded.
Make a backup of the database and the <AS_HOME> directory prior to upgrading. The <AS_HOME> directory can simply be copied to a separate location.
Be sure that you 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 database:

Stop the current server.
Copy the data from the production database to the staging database you created. This staging database becomes the new database for your new version of WSO2 AS.
Select the relevant script for the upgrade from here and run it on the staging 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 AS version.

There are three migration scripts available: migration-service-provider.sql, migration-identity.sql and migration.sql. However, note that only the migration.sql script is required to be executed for this upgrade.
Download the new AS 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:
- Go to the <AS_HOME>/repository/conf/datasources/ directory and update the master-datasources.xml file . See configuring master-datasources.xml.
- Go to the <AS_HOME>/repository/conf/ directory and update datasource references in the user-mgt.xml and registry.xml files. See configuring user-mgt.xml and configuring registry.xml.
Copy the following directories from the old database to the staging database.
- To migrate the super tenant settings, copy the <AS_HOME>/repository/deployment/server/ directory.
- If multitenancy is used, copy the <AS_HOME>/repository/tenants/ directory.
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

When the database upgrade scripts are executed, the following new tables will be created in the database:

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.