The instructions on this page takes you through the steps for upgrading from MB 2.2.0 to MB 3.0.0. Note that you cannot rollback the upgrade process. However, it is possible to restore a backup of the previous database and restart the upgrade progress.
Preparing to upgrade
The following prerequisites must be completed before upgrading:
Make a backup of the databases used for MB 2.2.0.
Also, copy the
<MB_HOME_2.2.0>directory in order to backup the product configurations.
Download WSO2 Message Broker 3.0.0 from http://wso2.com/products/message-broker/.
NOTE: The downtime is limited to the time taken for switching databases when in the production environment.
Step 1: Setting up new databases
In a typical setup for WSO2 MB, you will have at least two DBMSs configured: One for user management and registry data (Carbon database) and another for MB-specific data. Follow the steps given below.
- First create a new database for user management and registry data in MB 3.0.0. See the section on setting up the Carbon database for more information.
- Restore the old user management and registry data in the new database.
- Create another new database for MB-specific data in MB 3.0.0. See the section on setting up the MB-specific database for more information.
- Restore the old MB-specific data in the new database.
You will now have two new databases for MB 3.0.0 with the old data that existed for MB 2.2.0.
If there are multiple databases set up for MB 2.2.0, such as separate databases for multiple user stores etc., you need to create new databases for each of them.
Step 2: Updating the configurations
Once you have updated the databases as explained in step 1, you must update the configuration files in MB 3.0.0 to point to the new databases. The following are the updates that need to be done to the configuration files:
Note that configuration files should not be copied directly between servers.
- To connect MB 3.0.0 to the new database for user management and registry data, update the following configuration files:
<MB_HOME_3.0.0>/repository/conf/datasources/masterdatasources.xmlfile. This configuration should point to the new database that you set up in the previous section. See the following example:
Go to the
<MB_HOME_3.0.0>/repository/conf/directory and update the datasource references in the
registry.xmlfiles to match the updated configurations in the
masterdatasources.xmlfile. The following are sample configurations with the datasource set to “jdbc/WSO2CarbonDB”:
- To connect MB 3.0.0 to the new database for MB-specific data, configure the following files:
<MB_HOME_3.0.0>/repository/conf/datasources/masterdatasources.xmlfile. This configuration should point to the MB-specific database that you set up in the previous section. See the following example:
Go to the
broker.xmlfile (stored in the
<MB_HOME_3.0.0>/repository/conffolder) and update the persistence information related to MB-specific data. See the following example:
- Check for any other configurations that were done for MB 2.2.0 (based on your solutions), and update the configuration files in MB 3.0.0 accordingly. For example, external user stores, caching, mounting, etc.
The following configuration is introduced with the Carbon 4.4.2 version and is applicable to all WSO2 products that are based on Carbon 4.4.2:
Configuration File The
user-mgt.xmlfile stored in the
<isCascadeDeleteEnabled>property enables cascade delete for records entered in the UM_USER_PERMISSION and UM_ROLE_PERMISSION tables of the database used for storing user permissions.
- The following configuration files are new in MB 3.0.0:
broker.xmlfile (stored in the
metrics.xmlfile (stored in the
metrics.propertiesfile (stored in the
metrics-datasources.xmlfile (stored in the
Step 3: Start the new server and create new Topics and Queues
You now have your new MB 3.0.0 set up and configured.
- Proceed to start the server.
- Log in to the Management Console of MB 3.0.0.
- Manually create all the Topics and Queues that were there in MB 2.2.0. See the sections on managing Queues and managing Topics for detailed instructions on how to add Topics and Queues.
Step 4: Migrating the messages from Topics and Queues
Once you have configured the new MB 3.0.0 server as explained in the previous steps, you have to move all the Topics and Queues stored in the MB 2.2.0 instance to the new MB 3.0.0 instance. This data can be migrated by using a separate JMS client. This new JMS client will subscribe to the Queues and Topics in MB 2.2.0 and publish all the messages from those Queues and Topics to MB 3.0.0. The following diagram illustrates this process:
Given below is a sample JMS client that can be used for the above purpose. Click on the relevant tab to see how the subscriber and publisher classes are implemented in this sample JMS client. When you develop your own JMS client, you will have to modify the implementation given in this sample as applicable to your system. For example,
Subscriber.java class should be modified as follows:
- The connection details of your MB 2.2.0 installation should be specified.
- Details of the Queues and Topics you have in MB 2.2.0 should be specified.
Publisher.java class should be modified as follows:
- The connection details of your MB 3.0.0 installation should be specified.
- Details of the Queues and Topics to which messages will be published should be appropriately specified.
This is the sample implementation of a Subscriber client, which will subscribe to Queues and Topics in an MB 2.2.0 installation.
This is the sample implementation of a publisher client, which will publish to the Queues and Topics in an MB 3.0.0 installation.
Follow the steps given below.
Before you begin:
- Make sure that the publishers to MB 2.2.0 are stopped before data migration starts.
- Make sure that all the configuration files are updated in MB 3.0.0.
- Data migration should only take place after all the users, roles, queues, topics etc. are created in MB 3.0.0.
Both MB 2.2.0 and MB 3.0.0 should be started.
Be sure to use a port offset for one of the two product installations using the
carbon.xmlfile (stored in the
- Start the JMS Client. The following events will be executed:
- The JMS Subscriber will receive all the messages from the Queues and Topics in MB 2.2.0.
- The JMS Publisher will publish the messages (that were received from MB 2.2.0) to MB 3.0.0.
This concludes the upgrade from MB 2.2.0 to MB 3.0.0.
Step 5: Testing the upgrade
- Verify that all the required scenarios are working as expected as shown below. This confirms that the upgrade is successful.
Make sure that the server starts up fine without any errors.
Verify that the Users and Roles are picked up:
Navigate to Configure -> Accounts & Credentials -> Users and Roles
Verify that the list of users and roles are shown correctly.
- View the permissions of a chosen role, and make sure that the permissions are correct.
- Verify that all the messages to the Queues and Topics have been successfully published in the MB 3.0.0 instance.
- Run some of the samples to see that the system is working fine.