This guide takes you through the steps for migrating few of the most used products from their older version to newer versions. E.g., Product versions based on Carbon 4.0.0 to newer versions based on Carbon 4.1.0 or 4.2.0.The followings steps describe how to upgrade from ESB 4.6.0 to ESB 4.7.0. For more information on release versions, see the Release Matrix.
Preparing to Upgrade
Before starting the migration, the following prerequisites must be followed on the database.
- A separate staging database should run as the production database server. As a result, once the migration process is completed, the database server should have the configurations required for a production server.
- Take backups of the database and system prior to migrating the database. The system backup can be taken by copying the Carbon server home folder.
- Shut down all the Carbon servers connected to the database before running the migration scripts.
- Since a separate database (staging database) is used for the migration instead of the actual production database, the data that is collected in the actual production system while the migration is in progress should later be added to the migrated database using a script.
- The database administrator should collect the data portion that is added to the production database, while the migration is in progress. Generally, the WSO2 support team will provide help in these types of situations.
If any files/folders are changing in the product pack to which you are migrating, you need to make a backup of the relevant files/folders prior to changes.
Note New product (e.g. IS 4.5.0) must not be connected to the old database (e.g. IS 4.0.0) without executing the migration script provided in the old database.
Limitations
Following are the limitations of data migration:
- This migration 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 rollback migration. It is impossible to restore a backup of the previous server and retry the migration progress.
Downtime
The downtime is limited to the time taken for switching databases when the migrating environment is connected to the production.
Upgrade Procedure
Follow the instructions below to upgrade the system:
...
| Table of Contents | ||||
|---|---|---|---|---|
|
Upgrade procedure
Follow the instructions below to upgrade the system.
| Note |
|---|
The upgrade should be done when there is low traffic on the system. |
Stop the current server.
- To migrate deployment artifacts (including ESB message flow configurations):
Copy the
<ESB_HOME>/repository/deployment/serverdirectory from ESB 4.6.0 to ESB 4.7.0.Info If you do not have axis2 modules or axis2 services, you can copy the
<ESB_HOME>/repository/deployment/server/synapse-
...
cofigs/default
...
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 - Recommended tests
...
directory instead of all the contents in the
<ESB_HOME>/repository/deployment/serverdirectory.Perform any configurations required for the server, e.g., external user stores, clustering, mounting.
| Note |
|---|
Note that configurations should not be copied directly between servers. |
...
- If there are any external applications used with ESB 4.6.0 that you want to migrate, copy the following directories from ESB 4.6.0 to ESB 4.7.0:
ESB_HOME/repository/components/libESB_HOME/repository/components/dropins
- If you have multiple tenants defined in ESB 4.6.0, copy the
ESB_HOME/repository/tenantsdirectory from ESB 4.6.0 to ESB 4.7.0. - If you have not mounted the registry space to an external database you should manually copy the registry entries in ESB 4.6.0 to ESB 4.7.0. However. note that it is recommended to mount the registry entries to an external database. See Sharing Registry Space Among Multiple Products.
- Start the server.
Going into production
The following are a few recommended tests you may carry out to test whether the upgrade has been successfully performed.
If you can open the management console:
- 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.
...
- Check whether the list of proxy services, REST APIs, sequences, endpoints, message processors, message executors and priority executors you could view when running ESB 4.6.0 management console could also be viewed when you run ESB 4.7.0.
Test the integrations with other products e.g., see 2-legged OAuth for Securing a RESTful Service.
The following tests can be performed even if you operate as a worker in a worker-manager cluster and you cannot access a management console:
- Send a request to a proxy service you migrated and check whether you get a valid response.
- Send a request to a REST API and check whether you get a valid response.
Once the above tests are run successfully, it is safe to consider that the upgrade is ready for production. However,
...
you should also test any features that are being used in production.
Downtime
The downtime is limited to the time taken for switching databases.