The followings steps describe how you can upgrade data and configurations to upgrade from ESB 4.8.1 to ESB 5.0.0. For more information on release versions, see the Release Matrix.
You cannot roll back the upgrade process. However, it is possible to restore a backup of the previous database so that you can restart the upgrade progress.
Preparing to upgrade
The following prerequisites must be completed before upgrading:
The downtime is limited to the time taken for switching databases in the production environment.
Upgrading the database
The instructions in this section describe how you can perform a data migration to upgrade the 4.8.1 database for use in ESB 5.0.0.
Before you upgrade to ESB 5.0.0, create a new database and restore the backup of the ESB 4.8.1 database in this new database.
You should NOT connect a new version of WSO2 ESB to an older database that has not been upgraded.
mysql.sql script for the upgrade from here and run it on the new database. Running this script will ensure that the new database is upgraded to have the additional tables and schemas that are required for ESB 5.0.0.
You do not need to run the above script when using Oracle. In Oracle database there are no table structure changes that need to be migrated.
If you are using the default H2 database for user management you can use the same database without migrating it by adding the following property to
If you are using a database other than the default H2 database, you will need to upgrade your database. You can do this by selecting the relevant script based on your database type from here and run it on the new database. Running this script will ensure that all the user management related tables are created in the new database.
If you are using Oracle database,
you will need to edit the relevant script and change the value of
databasename to the user management database owner name.
Once you run the migration scripts on the new database, it becomes the upgraded database for ESB 5.0.0.
Migrating the configuration files
Configurations should not be copied directly between servers.
To connect ESB 5.0.0 to the upgraded database, configure the following files:
- Go to the
<ESB_HOME>/repository/conf/datasources directory and update the
master-datasources.xml file . See Configuring master-datasources.xml.
Go to the
<ESB_HOME>/repository/conf directory and update the datasource references in the
registry.xml files to match the updated configurations in the master-datasources.xml file that you made in the above step. See Configuring user-mgt.xml and Configuring registry.xml.
Check for any other configurations that were done for ESB 4.8.1 based on your solution and update the configuration files in ESB 5.0.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.
The following files have changed from ESB 4.8.1 to ESB 5.0.0
- If there are any third party libraries used with ESB 4.8.1 that you want to migrate, copy the following directories as applicable from ESB 4.8.1 to ESB 5.0.0:
- If you have used JMS libraries, JDBC libraries etc, copy
- If you have used OSGi bundles such as SVN kit etc, copy
- Start the ESB 5.0.0 server.
You should manually deploy Composite Application Archive (CAR) files that you have in ESB 4.8.1 to ESB 5.0.0. If you have a mediator packed in a CAR, all the artifacts using that mediator should also be included in the same CAR. See Deploying Composite Applications in the Server in WSO2 Admin Guide for further details.
To migrate deployment artifacts including ESB message flow configurations.
- Copy the required synapse artifacts from the
<ESB_HOME>/repository/deployment/server directory of ESB 4.8.1 to ESB 5.0.0. If you do not have axis2 modules or axis2 services, you can copy the required synapse artifacts from the
<ESB_HOME>/repository/deployment/server/synapse-configs/default directory of ESB 4.8.1 to ESB 5.0.0.
- If multi-tenancy is used, copy the
<ESB_HOME>/repository/tenants directory from ESB 4.8.1 to ESB 5.0.0.
Prior to copying the above folders remove all secured services from the folder.
With the removal of QoS features from ESB management console, enabling security for services hosted in ESB has changed from ESB 4.9.0 onwards. You now need to secure your services using ESB Tooling before you can migrate them to ESB 5.0.0.
See, Applying Security to a Proxy Service for instructions on how to create secured services and deploy them in ESB.
Testing the upgrade
Verify that all the required scenarios are working as expected in ESB 5.0.0. This confirms that the upgrade is successful.