Upgrading from a Previous Release

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

There are no Registry schema changes between versions.

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.

Upgrading from an older version

To upgrade from a version older than WSO2 G-Reg 5.1.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.

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.1.0> directory in order to backup the product configurations.
Make a backup of any mounted databases of WSO2 G-Reg 5.1.0.

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 redo the upgrading progress.

Downtime

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

Upgrading the product

You need to carry out the following types of migrations to upgrade WSO2 G-Reg.

Updating the database

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

Download WSO2 Governance Registry 5.2.0 from http://wso2.com/products/governance-registry/.
Stop all running server instances of WSO2 Governance Registry 5.1.0.
Make sure that you have taken a backup of all the databases and existing configurations.
Download the migration_client_greg5.1.0_to_5.2.0.zip file, and unzip it.

This is referred as <MIGRATION_CLIENT_HOME> in this guide.
Add the <MIGRATION_CLIENT_HOME>/org.wso2.carbon.is.migrate.client-5.1.0.jar file to the <G-REG_HOME>/repository/components/dropins/ directory.
Add the <MIGRATION_CLIENT_HOME>/migration-identity-4.5.6_to_5.0.8/ and <MIGRATION_CLIENT_HOME>/migration-um-4.5.6_to_5.0.8/ directoriess to the following directories.

<G-REG_HOME>/dbscripts/identity/migration-identity-4.5.6_to_5.0.8/
<G-REG_HOME>/dbscripts/migration-um-4.5.6_to_5.0.8/

Navigate to the <G-REG_HOME>/bin/ directory using your Command Line Interface, and start the WSO2 Governance Registry 5.2.0, by executing the following command options, to execute the migration client.

Linux: sh wso2server.sh -Dmigrate -DmigrateIdentity=true -Dcomponent=identity
Windows: wso2server.bat -Dmigrate -DmigrateIdentity=true -Dcomponent=identity

Stop the server by pressing CTRL+C keys, and re-start the WSO2 Governance Registry 5.2.0, by executing the following command options:
- Linux: sh sh wso2server.sh -Dmigrate -DmigrateUMDB=true -Dcomponent=identity
- Windows: wso2server.bat -Dmigrate -DmigrateUMDB=true -Dcomponent=identity

Migrating the configurations

Once you update the database, proceed with the configuration changes as explained below. The configurations can be directly migrated from WSO2 G-Reg 5.1.0 to WSO2 G-Reg 5.2.0.

Do not copy the configurations directly between the product servers.

Configure the following files, to connect WSO2 G-Reg 5.2.0 to the upgraded database.

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 Working with Databases.
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. If you have either changed the default H2 CarbonDB, or created separate databases for user management, identity etc. in G-Reg 5.1.0, then point to the same databases in the respective configuration files of G-Reg 5.2.0 accordingly.
  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_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>

Cleaning resources of the previous version

Follow the steps below to clean all existing resources of WSO2 G-Reg 5.1.0.

Download the org.wso2.carbon.greg.migrate.client-5.2.0.jar file, and copy it to the <G-REG_HOME>/repository/components/dropins/ directory.

If you use a clustered/distributed setup, copy the JAR file only to the master node(s).
Navigate to the <G-REG_HOME>/bin/ directory using your Command Line Interface, and re-start the server by executing the following commands:

It is mandatory to execute this migration command first.
- Linux: sh wso2server.sh -Dmigrate=5.2.0
- Windows: wso2server.bat -Dmigrate=5.2.0
After this migration is completed, stop the server by pressing CTRL+C keys.

Migrating data

Follow the two migrations below to migrate data. One is mandatory and other is optional.

Mandatory data migration

Navigate to the <G-REG_HOME>/bin/ directory using your Command Line Interface , and start the WSO2 Governance Registry 5.2.0 with the following command options, to do the mandatory data migration on the <provider> element.

If you use a clustered/distributed setup, execute the following command options only in the master node(s).

Linux: sh wso2server.sh -Dmigrate=5.2.0 -DmigrateProvider=true
Windows: wso2server.bat -Dmigrate=5.2.0 -DmigrateProvider=true

Optional data migration

If you want to migrate assets of WSO2 G-Reg 5.1.0 that have an email username in their resource path (i.e. because they were created using a user login with an email address as the username), and also if the corresponding resource RXT contains the overview_provider element in its storage path, navigate to the <G-REG_HOME>/bin/ directory using your Command Line Interface, and start the WSO2 Governance Registry 5.2.0 with the following command options to migrate the Registry configurations.

If you use a clustered/distributed setup, execute the following command options only in the master node(s).

Linux: sh wso2server.sh -Dmigrate=5.2.0 -DmigrateEmailUsername=true
Windows: wso2server.bat -Dmigrate=5.2.0 -DmigrateEmailUsername=true
Check for any other configurations that you did for WSO2 Governance Registry 5.1.0 (based on your solutions), and update the configuration files in WSO2 Governance Registry 5.2.0 accordingly. For example, external user stores, caching, mounting etc.

Once the server is completely started, and you are done with the migration tasks, stop the server by pressing CTRL+C keys. Then, remove the migration client JAR file from the <GREG_HOME>/repository/components/dropins/ directory, and restart the server by executing the following normal commands:

Linux: sh wso2server.sh
Windows: wso2server.bat

Re-indexing resources

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

Delete the <G-REG_HOME>/solr/ directory.
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>
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.

Recommended checkpoints

The identity database (i.e. configured in the <G-REG_HOME>/repositiry/conf/identity/identity.xml file), should contain the newly added tables, which are namely as follows:

IDP_METADATA
SP_METADATA

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.