Database Upgrade Guide

This page takes you through the general steps for upgrading product versions based on Carbon 4.4.1 to Carbon 4.4.2.

Preparing to Upgrade

The following are the specific prerequisites you must complete before an upgrade:

• Before you upgrade to the latest version of a product, you create a staging database, which is essentially an empty database. Note that you should NOT connect a new product version to an older database that has not been upgraded. 

• Make a backup of the database and the <PRODUCT_HOME> directory prior to upgrading. The <PRODUCT_HOME> directory can simply be copied to the new directory.

• Stop all the Carbon servers connected to the database before running the migration scripts.

  Note that the upgrade should be done during a period when there is low traffic on the system.

Limitations

Upgrading the configurations

There are no database changes between Carbon 4.4.1 to Carbon 4.4.2. Therefore, only the new configuration options in Carbon 4.4.2 should be updated for the new environment as explained below.

1. Copy the data from the old database to the staging database you created. This becomes the new database for your new version of Carbon.

2. Download Carbon 4.4.2 and connect it to your staging database. 

3. Update the configuration files in Carbon 4.4.2 as required. Be mindful of the following configurations:

   • The following configuration is new in 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.

   • Listed below are some important configurations that you need to be mindful of when upgrading to Carbon 4.4.2. These configurations were introduced recently with the Carbon 4.3.0 version.

      Configurations introduced in Carbon 4.3.0

     Configuration File
     The axis2.xml file stored in the <PRODUCT_HOME>/repository/conf/axis2 directory.	The following new parameter is added: <parameter name="httpContentNegotiation">true</parameter>. When this is set to 'true', the server will determine the content type used for responses, by using the 'Accept header' of the request.
     The tenant-axis2.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat directory.	The default value for the "httpContentNegotiation" parameter is set to 'true': <parameter name="httpContentNegotiation">true</parameter>.
     The catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat directory.	Keystore parameters are added under the <Connector> element as shown below. This setting allows you to use a separate keystore and security certificates for certifying SSL connections. Note that the location and password of the default "wso2carbon.jks" keystore is given for these parameters by default. keystoreFile=location of the keystore file keystorePass=password for the keystore
     The master-datasources.xml file stored in the <PRODUCT_HOME>/repository/conf/datasources directory.	The default auto-commit setting for a datasource is set to false: <defaultAutoCommit>false</defaultAutoCommit>.
     The carbon.xml file stored in the <PRODUCT_HOME>/repository/conf directory.	New parameters are added to define the proxy context path as shown below. <MgtProxyContextPath></MgtProxyContextPath> <ProxyContextPath></ProxyContextPath> The proxy context path is a useful parameter that allows you to add a proxy path when a Carbon server is fronted by a reverse proxy. In addition to the proxy host and proxy port, this parameter allows you to add a path component to external URLs. See Adding a Custom Proxy Path for details. The following port configurations have been removed: <!-- Embedded Qpid broker ports → <EmbeddedQpid> <!-- Broker TCP Port → <BrokerPort>5672</BrokerPort> <!-- SSL Port → <BrokerSSLPort>8672</BrokerSSLPort> </EmbeddedQpid> In Carbon 4.2.0, the registry keystore configuration was required for configuring the keystore keys that certify encrypting/decrypting meta data to the registry as shown below. From Carbon 4.3.0 onwards the primary keystore configuration shown below will be used for this purpose as well. Therefore, it is not necessary to use a separate registry keystore configuration for encrypting/decrypting meta data to the registry. Read more about keystore configurations in Carbon 4.4.2. <RegistryKeyStore> <!-- Keystore file location--> <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location> <!-- Keystore type (JKS/PKCS12 etc.)--> <Type>JKS</Type> <!-- Keystore password--> <Password>wso2carbon</Password> <!-- Private Key alias--> <KeyAlias>wso2carbon</KeyAlias> <!-- Private Key password--> <KeyPassword>wso2carbon</KeyPassword> </RegistryKeyStore>
     The registry.xml file stored in the <PRODUCT_HOME>/repository/conf directory.	The default value is changed to 'false' for the following setting: <versionResourcesOnChange>false</versionResourcesOnChange>.

4. Copy the following directories from the old database to the staging database.
   1. To migrate the super tenant settings, copy the <PRODUCT_HOME>/repository/deployment/server directory.
   2. If multitenancy is used, copy the <PRODUCT_HOME>/repository/tenants directory.

   Note that configurations should not be copied directly between servers. 

5. Start the server.

Going into production

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