Upgrade

14 Upgrade

This section provides instructions for upgrading Oracle GoldenGate Microservices Architecture for Oracle database.

Topics:

Obtaining the Oracle GoldenGate Distribution

To obtain Oracle GoldenGate, follow these steps:

Go to edelivery: edelivery.oracle.com
Also see MOS note 1645495.1 and 2193391.1 for more information.

To access Oracle Technology Network, go to https://www.oracle.com/middleware/technologies/goldengate.html
Find the Oracle GoldenGate 21c release and download the ZIP file onto your system.

For more information about locating and downloading Oracle Fusion Middleware products, see the Oracle Fusion Middleware Download, Installation, and Configuration Readme Files on Oracle Technology Network.

Prerequisites

Learn about prerequisites for upgrading Oracle GoldenGate Microservices Architecture.

As a best practice, perform a minimal or basic upgrade first, which implies performing the upgrade without adding any new features and additional or non-mandatory parameters.

If Oracle GoldenGate is upgraded at the source side where the Extract exists, then the trail file format remains the same. Only if a higher FORMAT RELEASE is adjusted to the EXTTRAIL parameter or an ETROLLOVER is performed, will the trail file get upgraded to a higher release. This provides the opportunity to upgrade the target system where the Replicat exists, independently. When all target systems are upgraded, you may update the format release of the EXTTRAIL parameter to leverage new features that rely on a higher trail file format. No repositioning of any process is required.

After you verify that the environment is upgraded successfully, you can implement the new features and additional parameters as required.

The upgrade instructions also include the steps for upgrading the source or target database and Oracle GoldenGate at the same time.

Oracle GoldenGate Upgrade Considerations

Before you start the upgrade, review the information about upgrading Extract and Replicat.

Even though you may only be upgrading the source or target installations, rather than both, all processes are involved in the upgrade. All processes must be stopped in the correct order for the upgrade, regardless of which component you upgrade, and the trails must be processed until empty.

Oracle recommends that you begin your upgrade with the target rather than the source to avoid the necessity of adjusting the trail file format.

Installation Binaries and Deployments

With Microservice Architecture, there is a strong separation between where the software is installed and the deployment directory structure for the Oracle GoldenGate instance, which contains the parameter files, report files, and trail files. For both these areas, the software binaries and deployment, are strictly separated. So, there is no interference between the old and new software installations related to the deployments. During a software upgrade, the new software will be installed independently. The deployment working with the old software will be stopped. Then, the deployment environment will be adjusted to the new software and the deployment will be restarted.

If you have a reverse proxy configuration on your host machine generated with OGG_HOME/lib/utl/reverseproxy/ReverseProxySettings, then consider reconfiguring it to leverage the enhanced ReverseProxySetting utility available with Oracle GoldenGate 21c (21.3) and higher releases.

Considerations for Upgrading Service Manager and other Deployments

When upgrading Oracle GoldenGate, the Service Manager must be updated first. The software version of the Service Manager must be higher or equal to the version of the deployments. There are no issues having a Service Manager running on the highest version and having deployments with lower versions.

After completing the upgrade, run the UPGRADE HEARTBEATTABLE command to add extra columns for tables and lag views. These extra columns are used to track the Extract restart position. See UPGRADE HEARTBEATTABLE to know more.

Topics:

Extract Upgrade Considerations

If you are upgrading multiple Extract processes that operate in a consolidated configuration (many sources to one target), upgrade one Extract at a time.

The output trail file is automatically rolled over when the Extract restarts and the integrated Extract version is upgraded.

Because the TIMEZONE datatype is managed differently with Oracle GoldenGate 21c, you may need to run the ALTER REPLICAT extseqno command to synchronize with newer trail files after consuming the old trail file written by Extract version 1.

Replicat Upgrade Considerations

All Replicat installations should be upgraded at the same time. It is critical to ensure that all trails leading to all Replicat groups on all target systems are processed until empty, according to the upgrade instructions.

When upgrading from releases prior to 19c release of Oracle GoldenGate, ensure that you do not use the SOURCEDEF parameter in Replicat, otherwise the Replicat will abend. However, if the trail file format is pre-12.2, then SOURCEDEF is still required because no metadata exists in the trail file.

Upgrading Oracle GoldenGate Microservices – GUI Based

Learn the steps to upgrade Oracle GoldenGate Microservices using the GUI.

Follow these steps to obtain the Oracle GoldenGate installation software and set up the directories for upgrade.

Download the latest Oracle GoldenGate Microservices 21c software from the Oracle Technology Network or eDelivery.
Move the Oracle GoldenGate 21c MA software to a staging folder and unzip it.

For Linux, use the following example:
```
$ mv /home/user/fbo_ggs_Linux_x64_Oracle_services_shiphome.zip /tmp
$ cd /tmp$ unzip fbo_ggs_Linux_x64_Oracle_services_shiphome.zip
```
Upload the Oracle GoldenGate Microservices 21c software to a staging location on the server where a previous release of Oracle GoldenGate Microservices exists.
Save the changes and return to the Service Manager Overview page.
Select the Action dropdown for the deployment and select Restart.
Log in to the Administration Service and click Action button in the Replicat section.
Click the Parameter File tab and change the value of the BATCHSQL parameter to double the value of BATCHESPERQUEUE. You must do this before starting Replicat. For example: BATCHSQL BATCHESPERQUEUE 40000000.
Log back into the Adminstration Service and start Extract and Replicat.

At this point, you should have a new Oracle GoldenGate 21c MA home and any prior release homes of Oracle GoldenGate MA.

Upgrade the Service Manager

After installing the latest Oracle GoldenGate MA version, the next step is to upgrade the Service Manager:

Log into Service Manager from the URL: https://hostname:servicemanager_port
Select the ServiceManager link in the Deployments section of the Service Manager Overview page.
Click the pencil icon next to the Deployment Detail section to open the dialog box for editing the GoldenGate home path.
Update the GoldenGate Home path with the full path to the new Oracle GoldenGate home.
Click Apply.
Use the Action dropdown to restart the Service Manager.

Upgrade the Deployment

Deployments can be upgraded in the same step with the Service Manager or they can be upgraded at a later time after the Service Manager has been upgraded.

To upgrade a deployment:

Stop all Extract and Replicat processes gracefully:
- Check for open (long running) transaction and Bounded Recovery as it may take longer to stop Extract gracefully.
- If any unnecessary open transactions are visible, for example SEND EXTRACT group_name SHOWTRANS, then those transactions can be skipped or immediately forced to stop. In this case, a Bounded Recovery checkpoint can be retrieved using the following command:
  
  SEND EXTRACT group_name, BR BRCHECKPOINT immediate
Verify the current location of Oracle GoldenGate home directory from Service Manager.
1. Login to the Service Manager: http://hostname:servicemanager_port
2. Click the link to the deployment name in the Deployments section on the Service Manager Overview page. The deployment details are displayed.
Edit and update the the deployment with the location of the new Oracle GoldenGate Home directory.
1. Click the pencil next to Service Manager Deployment Detail to edit the Oracle GoldenGate Home directory on the Details tab.
2. Update the Oracle GoldenGate Home path with the complete path to the new Oracle GoldenGate home directory.
3. Click Apply.
4. Confirm that the Oracle GoldenGate Home path has been updated.
5. Select the link for the Administration Service in the Deployment section.
6. Log in and stop any Extracts and Replicats. Close the Administration Service page and return to the Service Manager page.
Return to the Deployment Detail page of the deployment and then select the Configuration tab to modify the settings for the environment variables. With the new Unified Build in Oracle GoldenGate 21c, the environment variables for ORACLE_HOME, LD_LIBRARY_PATH, and TNS_ADMIN need to be adjusted to the Oracle Database Client software within Oracle GoldenGate. Set the environment variables as:
- ORACLE_HOME = $OGG_HOME/lib/instantclient
- LD_LIBRARY_PATH = $OGG_HOME/lib:$OGG_HOME/lib/instantclient
- TNS_ADMIN = Location of tnsnames.ora and sqlnet.ora
- JAVA_HOME = $OGG_HOME/jdk
Save the changes and return to the Service Manager Overview page.
Save the changes and return to the Service Manager Overview page.
Select the Action dropdown for the deployment and select Restart.
Log back into the Adminstration Service and start any Extract and Replicats.

Upgrading Oracle GoldenGate Microservices Using REST APIs

Learn how to upgrade Oracle GoldenGate Microservices to Oracle GoldenGate Microservices 21c using REST APIs.

Follow these steps to obtain the Oracle GoldenGate installation software and set up the directories for upgrade.

Download the latest Oracle GoldenGate Microservices 21c software from the Oracle Technology Network or eDelivery.
Move the Oracle GoldenGate 21c MA software to a staging folder and unzip it.

For Linux, use the following example:
```
$ mv /home/user/fbo_ggs_Linux_x64_Oracle_services_shiphome.zip /tmp
$ cd /tmp$ unzip fbo_ggs_Linux_x64_Oracle_services_shiphome.zip
```
Upload the Oracle GoldenGate Microservices 21c software to a staging location on the server where a previous release of Oracle GoldenGate Microservices exists.
Save the changes and return to the Service Manager home page.
Select the Action dropdown for the deployment and select Restart.
Log in to the Administration Service and click Action button in the Replicat section.
Click the Parameter File tab and change the value of the BATCHSQL parameter to double the value of BATCHESPERQUEUE. You must do this before starting Replicat. For example: BATCHSQL BATCHESPERQUEUE 40000000
Log back into the Adminstration Service and start Extract and Replicat.

Upgrade a Service Manager

When upgrading the Service Manager, you can use the following cURL example to update the Oracle GoldenGate home:

curl -u adminname:adminpwd -X PATCH \
   https://hostname:port/services/v2/deployments/ServiceManager \
  -H 'cache-control: no-cache' \
  -d '{"oggHome":"new OGG_HOME_absolute_path", "status":"restart"}'

In this syntax, enter the new Oracle GoldenGate home directory absolute directory path such as /u01/app/oracle/product/21c/gghome_1.

Check if Service Manager is running from the new $OGG_HOME, using the following command:

ps -ef|grep -i servicemanager

If you don't see Service Manager in running state, then run the following command:

cd $NEW_OGG_HOME/bin
$ ./ServiceManager

Upgrade a Deployment

To upgrade a deployment:

Stop all Extract and Replicat processes gracefully:
- Check for open (long running) transaction and Bounded Recovery as it may take longer to stop Extract gracefully.
- If any unnecessary open transactions are visible, for example SEND EXTRACT group_name SHOWTRANS, then those transactions can be skipped or immediately forced to stop. In this case, a Bounded Recovery checkpoint can be retrieved using the following command:
  
  SEND EXTRACT group_name, BR BRCHECKPOINT immediate

Change the environment variables for the deployment, as shown in the following example:

curl -k -u adminname:adminpwd -X PATCH \
https://server.oracle.com:9000/services/v2/deployments/uat_01 \
-H 'cache-control: no-cache' \
-d '{"environment": [ {"name": "ORACLE_HOME" , "value": "/u01/app/oracle/product/21c/gghome_1/lib/instantclient"}
                                 , {"name": "LD_LIBRARY_PATH" , "value": "/u01/app/oracle/product/21c/gghome_1/lib/instantclient:/u01/app/oracle/product/21c/gghome_1/lib"}
                                 , {"name": "JAVA_HOME" , "value": "/u01/app/oracle/product/21c/gghome_1/jdk"}
                                 , {"name": "TNS_ADMIN" , "value": "/u01/app/oracle/network/admin"} ] }'

Run this cURL command to upgrade the Oracle GoldenGate deployment:

 curl -u SM username:SM password -X PATCH 
http://hostname:servicemanager port/services/v2/deployments/Deployment-name 
-H 'cache-control: no-cache'
-d '{"oggHome":"new OGG_HOME complete path","status":"restart"}'

Start all Extracts and Replicats.

When the Service Manager or deployment restarts, the upgrade is complete.