Upgrading from a Previous Release

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:

Configure the <MB_HOME_3.0.0>/repository/conf/datasources/masterdatasources.xml file. This configuration should point to the new database that you set up in the previous section. See the following example:

<datasource>
user manager</description>
<name>WSO2_CARBON_DB</name>
<description>The datasource used for registry and
<jndiConfig>
<name>jdbc/WSO2CarbonDB</name>
</jndiConfig>
<definition type="RDBMS">
<configuration>
<url>jdbc:mysql://localhost:3306/<new_database></url>
<username>username</username>
<password>password</password>
<driverClassName>com.mysql.jdbc.Driver</driverClassName>
<maxActive>80</maxActive>
<maxWait>60000</maxWait>
<minIdle>5</minIdle>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT1</validationQuery>
<validationInterval>30000</validationInterval>
</configuration>
</definition>
</datasource>

Go to the <MB_HOME_3.0.0>/repository/conf/ directory and update the datasource references in the user-mgt.xml and registry.xml files to match the updated configurations in the masterdatasources.xml file. The following are sample configurations with the datasource set to “jdbc/WSO2CarbonDB”:

registry.xml
```
<dbConfig name="wso2registry">
<dataSource>jdbc/WSO2CarbonDB</dataSource>
</dbConfig>
```
usermgt.xml
```
<UserManager>
<Realm>
<Configuration>
...
<Property
name="dataSource">jdbc/WSO2CarbonDB</Property>
</Configuration>
...
</Realm>
</UserManager>
```

To connect MB 3.0.0 to the new database for MB-specific data, configure the following files:

Configure the <MB_HOME_3.0.0>/repository/conf/datasources/masterdatasources.xml file. This configuration should point to the MB-specific database that you set up in the previous section. See the following example:

<datasource>
  <name>WSO2_MB_STORE_DB</name>
  <jndiConfig>
     <name>WSO2MBStoreDB</name>
  </jndiConfig>
     <definition type="RDBMS">
         <configuration>
            <driverClassName>com.mysql.jdbc.Driver</driverClassName>
            <url>jdbc:mysql://localhost/wso2_mb</url>
            <username>root</username>
            <password>root</password>
            <maxActive>50</maxActive>
            <maxWait>60000</maxWait>
            <minIdle>5</minIdle>
            <testOnBorrow>true</testOnBorrow>
            <validationQuery>SELECT 1</validationQuery>
            <validationInterval>30000</validationInterval>
            <defaultAutoCommit>false</defaultAutoCommit>
         </configuration>
      </definition>
</datasource>

Go to the broker.xml file (stored in the <MB_HOME_3.0.0>/repository/conf folder) and update the persistence information related to MB-specific data. See the following example:

<messageStore class="org.wso2.andes.store.rdbms.RDBMSMessageStoreImpl">
    <property name="dataSource">WSO2MBStoreDB</property>
    <property name="storeUnavailableSQLStateClasses">08</property>
    <property name="integrityViolationSQLStateClasses">23,27,44</property>
    <property name="dataErrorSQLStateClasses">21,22</property>
    <property name="transactionRollbackSQLStateClasses">40</property>
</messageStore>
<contextStore class="org.wso2.andes.store.rdbms.RDBMSAndesContextStoreImpl">
    <property name="dataSource">WSO2MBStoreDB</property>
    <property name="storeUnavailableSQLStateClasses">08</property>
    <property name="integrityViolationSQLStateClasses">23,27,44</property>
    <property name="dataErrorSQLStateClasses">21,22</property>
    <property name="transactionRollbackSQLStateClasses">40</property>
</contextStore>

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.xml` file stored in the `<PRODUCT_HOME>/repository/conf` directory.	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.xml file (stored in the <MB_HOME_3.0.0>/repository/conf folder)
- metrics.xml file (stored in the <MB_HOME_3.0.0>/repository/conf folder)
- metrics.properties file (stored in the <MB_HOME_3.0.0>/repository/conf folder)
- metrics-datasources.xml file (stored in the <MB_HOME_3.0.0>/repository/conf/datasources folder)

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:
JMS client for data migration

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,

The 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.

The 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.

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.xml file (stored in the <MB_HOME>/repository/conf folder).
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.
1. Make sure that the server starts up fine without any errors.
2. Verify that the Users and Roles are picked up:
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.