Upgrading from the Previous Release

To upgrade WSO2 Governance Registry, the user store database should be upgraded. Note that there are no registry schema changes between versions. This topic provides instructions on how you can upgrade (the data and configurations) from WSO2 G-Reg 4.6.0 to WSO2 G-Reg 5.0.0.

If you want to migrate your Governance Registry configurations from one instance to another (such as when promoting your instance from test to production) using the same Governance Registry release, see Migrating the Governance Registry.

Prerequisites

To upgrade from a version older than WSO2 G-Reg 4.6.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 the 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.
Make a backup of the WSO2 Governance Registry 4.6.0 database and copy the <G-REG_HOME_4.6.0> directory in order to to backup the product configurations.

Limitations

The following are the limitations of upgrading.

This upgrading process can only be done for the same database types. For example, if you are using MySQL currently and you wish to use Oracle in the new version of G-REG, these scripts will not work.
You cannot roll back the upgrading process. However, it is possible to restore a backup of the previous database and restart the upgrading progress.

Downtime

The downtime is limited to the time taken for switching databases when in the production environment.

Upgrading the product

Download WSO2 Governance Registry 5.0.0.
Log in to the WSO2 G-Reg Management Console and create the /_system/governance/trunk/endpoints collection. For instructions, see Adding a Collection.

The endpoints RXT is introduced in WSO2 G-Reg 5.0.0. Therefore, since the migration client might try to migrate data from "/_system/governance/trunk/endpoints", which is not available in WSO2 G-Reg versions below 5.0.0, you need to manually create this endpoint collection before upgrading.
Stop all running server instances of WSO2 Governance Registry 4.6.0.
Make sure that you have taken a backup of all the databases and existing configurations.
Follow the steps below to configure the database (in the master-datasources.xml file) and the datasource property values (in the registry.xml, user-mgt.xml and api-manager.xml files) of the new WSO2 G-Reg version, similar to the previous G-REG version.
1. Configure <G-REG_5.0.0__HOME>/repository/conf/datasources/master-datasources.xml. For more information on how to do this for your database, see Working with Databases.
2. Go to the <G-REG_5.0.0__HOME>/repository/conf directory and update the datasource references in user-mgt.xml, registry.xml and api-manager.xml 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>
```

If there are several 1000s 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_5.0.0__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>

Download the org.wso2.carbon.greg.migrate.client-5.0.0.jar file and copy it to the <G-REG_5.0.0__HOME>/repository/components/dropins directory. If you use a clustered/distributed setup, copy the JAR file to the master nodes.
Start the WSO2 Governance Registry 5.0.0 with the following command options to migrate the registry configurations. If you have a clustered/distributed setup, run the following command options in master node only.
```
-Dmigrate=5.0.0 -DmigrateReg=true
```
For example,

Linux: sh wso2server.sh -Dmigrate=5.0.0 -DmigrateReg=true
Windows: wso2server.bat -Dmigrate=5.0.0 -DmigrateReg=true
It is recommended to restart all the WSO2 Governance Registry 5.0.0 instances. Check for any other configurations that were done for WSO2 Governance Registry 4.6.0 (based on your solutions), and update the configuration files in WSO2 Governance Registry 5.0.0 accordingly. For example, external user stores, caching, mounting.

Re-indexing resources

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

Delete the 'solr' directory of the file system.
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_5.0.0__HOME>/repositiry/conf/registry.xml file as follows.
<lastAccessTimeLocation>/_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1</lastAccessTimeLocation>
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.