Upgrading from a Previous Release

This topic provides instructions on how you can upgrade from WSO2 G-Reg 5.3.0 to WSO2 G-Reg 5.4.0.

Upgrading from an older version

To upgrade from a version older than WSO2 G-Reg 5.3.0, start from the doc that was released immediately after your current release and upgrade incrementally.

• For instructions on upgrading from G-Reg 4.5.3 to 4.6.0, go to Upgrading from a Previous Release.
• For instructions on upgrading from G-Reg 4.6.0 to 5.0.0, go to Upgrading from the Previous Release.
• For instructions on upgrading from G-Reg 5.0.0 to 5.0.1, go to Upgrading from a Previous Release.
• For instructions on upgrading from G-Reg 5.0.1 to 5.1.0, go to Upgrading from a Previous Release.
• For instructions on upgrading from G-Reg 5.1.0 to 5.2.0, go to Upgrading from a Previous Release.
• For instructions on upgrading from G-Reg 5.2.0 to 5.3.0, go to Upgrading from a Previous Release.

Preparing to upgrade

The following are the specific prerequisites you must complete before you upgrade WSO2 G-Reg:

• Stop all the WSO2 products that are connected to the database.

• Copy the <G-REG_HOME_5.3.0> directory in order to backup the product configurations.

• Make a backup of any mounted databases of WSO2 G-Reg 5.3.0.

Limitations

Updating the database

Follow the steps below to update the WSO2 G-Reg database.

1. Download WSO2 Governance Registry 5.4.0. 

2. Stop all running server instances of WSO2 Governance Registry 5.3.0.

3. Make sure that you have taken a backup of all the databases and existing configurations.
4. To connect the new product version, to the database of the previous version, configure the following files:  
   
   1. Configure <G-REG_HOME>/repository/conf/datasources/master-datasources.xml. For more information on how to do this for your database, see Changing the default database. 

   2. Navigate to the <G-REG_HOME>/repository/conf directory, and update the datasource references in user-mgt.xml, registry.xml and api-manager.xml files, to match the updated configurations in the master-datasources.xml file, which you made in the above step. The following are sample configurations if the datasource is jdbc/WSO2CarbonDB.

      registry.xml

      <dbConfig name="wso2registry">
          <dataSource>jdbc/WSO2CarbonDB</dataSource>
      </dbConfig> 

      user-mgt.xml

      <UserManager>
        <Realm>
        <Configuration>
        ...
        <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
        </Configuration>
        ...
        </Realm>
      </UserManager>

      api-manager.xml

      <DataSourceName>jdbc/WSO2CarbonDB</DataSourceName>

5. Follow the below steps to update the database scripts.

   1. Download the migration resources and unzip it to a local directory. This folder is referred to as <MIGRATION_TOOL_HOME>.

      If you are using MySQL 5.7, rename the <MIGRATION_TOOL_HOME>/dbscripts/identity/migration-5.2.0_to_5.3.0/mysql.sql file to mysql_56.sql.

   2. Copy the DB script files in the <MIGRATION_TOOL_HOME>/dbscripts/identity/migration-5.2.0_to_5.3.0 directory to the <G-REG_5.4.0_HOME>/dbscripts/identity/ directory.

   3. Copy the <MIGRATION_TOOL_HOME>/dropins/org.wso2.carbon.is.migrate.client-5.3.0.jar file to the <G-REG_5.4.0_HOME>/components/dropins/ directory.

      Alternatively, if you are using Oracle, either provide the database owner credentials in the datasource configurations (identity and user management databases). Else, pass the identity database owner name with the -DidentityOracleUser command and user management database owner name with ­the -DumOracleUser command.

6. If there are thousands of artifacts in the system, increase the value of the <indexingFrequencyInSeconds> property (e.g. to 10), or reduce the value of the <batchSize> property (e.g. to 10) in the <G-REG_HOME>/repository/conf/registry.xml file as shown below.

   <indexingConfiguration>
   <solrServerUrl>http://192.168.48.220:8983/solr/registry-indexing</solrServerUrl>
   <startingDelayInSeconds>35</startingDelayInSeconds>
   <indexingFrequencyInSeconds>3</indexingFrequencyInSeconds>
   <!--number of resources submit for given indexing thread -->
   <batchSize>50</batchSize>
   <!--number of worker threads for indexing -->
   <indexerPoolSize>50</indexerPoolSize>
   <!-- location storing the time the indexing took place-->
   </indexingConfiguration>

7. Once you are done with the migration tasks, restart the server as follows:

   Execute both commands one after the other.

   For Linux: 

   • sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigratePermissionData
   • sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateIdentityDB

   For Windows: 

   • wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateIdentityDB
   • wso2server.bat -Dmigrate -Dcomponent=identity -DmigratePermissionData

Re-indexing resources

Follow the steps below to re-index the resources after completing the migration.

1. Delete the <G-REG_HOME>/solr/ directory.
2. Change the name  (e.g.  lastaccesstime to lastaccesstime_1)  of the file  in the registry which tracks the last access time of indexing the resources, by changing the value of the  <lastAccessTimeLocation>  property in the  <G-REG_HOME>/repositiry/conf/registry.xml  file as follows.
   <lastAccessTimeLocation>/_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1</lastAccessTimeLocation>
3. Restart the G-Reg server and wait for around 30 minutes. This time duration depends on number of resources that are there in the registry.

Going into production

The following are recommended tests to run on the upgraded 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.