Maintain your OCI GoldenGate deployments
Learn about GoldenGate versions, how and when to upgrade, receive or snooze notifications, and how to rollback upgrades.
Related Topics
About GoldenGate versions
OCI GoldenGate supports multiple concurrent versions, for example, Oracle GoldenGate, Oracle GoldenGate for Big Data, and Oracle GoldenGate for MySQL, to name a few. Refer to the versions reference for details on the appropriate version for you.
Every release has a build number. There are three types of releases:
- Major: The first number in build number indicates a major release. For example, 21.
- Bundle: The second number indicates the bundle release. A bundle release is a set of bug fixes for a major release. For example, 21.5
- Minor: The trailing numbers indicate a minor release. A minor release consists of one or more bug fixes on a bundle release. For example, 21.5.0.0.0.
Note:
All release types can contain security fixes.Depending on the type of release and whether or not it includes a security fix, you have a specific amount of time to upgrade your deployment when a new version becomes available:
Release type | Major | Bundle | Minor |
---|---|---|---|
Non-security fix | 365 days | 180 days | Not applicable |
Security fix | Not applicable | 14 days | 14 days |
If you don't upgrade manually within the given timeframe, then your deployment automatically upgrades to the latest version at the end of this timeframe.
Note:
You can view the date a version is supported until in the Upgrade deployment screen and Upgrades list.Deprecation of versions
A GoldenGate version is available from the date it was released to the date it's deprecated. When a version is deprecated, you can no longer select it for deployment creation or upgrade.
Deprecation periods use the same time frames as version upgrades. For example:
- 365 days after a Major version release, the previous Major version is deprecated.
- 180 days after a Bundle version release, previous Bundle versions of the same Major release are deprecated.
- 14 days after a Security fix release (for Bundle or Minor releases), all previous versions of the same Major release are deprecated.
Note:
The release date may differ between regions.Schedule upgrades
You can customize maintenance windows that define the start of the time period during which to upgrade your deployment when a new GoldenGate version is available. If you don't define a maintenance window, then OCI GoldenGate calculates the best time to upgrade the deployment based on the latest version's release date.
Note:
When a maintenance window is not defined, OCI GoldenGate schedules upgrades on the weekend closest to the calculated end of the auto upgrade period.You can customize the OCI GoldenGate maintenance window when you create the deployment, or later from the deployment details page. When a new GoldenGate version is available, the deployment automatically upgrades on the exact day and time chosen. However, deployments can automatically upgrade before your chosen day and time when the new version's timeframe for manual upgrade falls outside your customized maintenance window.
For example, let's say on January 1st, 2023, you have 30 days left to upgrade your deployment, then you have until Tuesday, January 31st to manually upgrade. However, your customized maintenance window begins on Sundays at 10PM. With this maintenance window, OCI GoldenGate will upgrade your deployment on Sunday, February 4th at 10PM, because OCI GoldenGate will always prioritize your customized window.
To edit the customized maintenance window:
- On the deployment details page, under GoldenGate in the Deployment information area, for Maintenance, click Edit.
- In the Edit maintenance parameters dialog:
- (Optional) Select Customize maintenance window to change the following fields from their default values.
- For Major release auto-upgrade period in days, enter a value between 0 and 365.
- For Bundle release auto-upgrade period in days, enter a value between 0 and 180.
- For Security path auto-upgrade period in days, enter a value between 0 and 14.
- (Optional) Select Enable minor release auto-upgrade, and then enter a value for Minor release auto-upgrade period in days.
- Click Save changes.
Before you upgrade
Before upgrading a deployment, ensure that you complete the following tasks and check for long running transactions.
Ensure Archive Logs are available for recovery
Recovery
Checkpoint
field shows the oldest log needed for
recovery.Admin Client > INFO EXTRACT group_name, SHOWCH
It’s best to perform upgrade activities outside of the peak hours. If there are large and long running transactions, you may consider that on the source system, the new Extract might need to start processing from the normal recovery checkpoint, rather than the bounded recovery checkpoint, if the first record of the oldest open transaction at the time that you stop Extract is in a log that is not on the system.
Clear long running transactions
To clear long running transactions, you have two options:
- You can restore the archives back to, and including, the one shown in
the recovery checkpoint shown
with:
(If the source database supports this.)Admin Client > INFO EXTRACT
- You can clear out the long-running transactions that apply to the Extract that you
are upgrading. This can be done by skipping the transactions or by forcing them to
the trail as committed transactions. Skipping a transaction may cause data loss, and
forcing a transaction to the trail may add unwanted data to the trail if the
transaction is rolled back. To skip or force a transaction:
- View open
transactions:
Admin Client > SEND EXTRACT group_name, SHOWTRANS
- Record the transaction ID of any transaction you want to clean up.
- Clean up old transactions using
SEND EXTRACT
and either theSKIPTRANS
option to skip a transaction, orFORCETRANS
to force a transaction in its current state to the Trail as a committed transaction. For example:Admin Client > SEND EXTRACT group_name, {SKIPTRANS | FORCETRANS transaction_ID [THREAD n] [FORCE]
- After you finish cleaning up long running transactions, force a
Bounded Recovery checkpoint.
Admin Client> SEND EXTRACT group_name, BR BRCHECKPOINT IMMEDIATE
- View open
transactions:
Synchronize Replicats
Admin Client > SYNCHRONIZE REPLICAT group_name
For more information, see SYNCHRONIZE REPLICAT command line interface reference.
Upgrade a deployment
Ensure that you complete the Before you upgrade steps first.
When you upgrade a deployment,
- The deployment is stopped and then restarted after the upgrade completes.
- All Oracle GoldenGate processes are stopped and then restarted if they're configured to auto-start.
The upgrade takes a few minutes to complete. Click Upgrades on the deployment details page after the upgrade completes to view the upgrade history or if an issue is encountered during the upgrade process.
- Run the
UPGRADE HEARTBEATTABLE
command in Admin Client to add extra columns for tables and lag views. GoldenGate uses these extra columns to track the Extract restart position. Learn more. - In the deployment console, open the navigation menu for the Administration console, and then click Configuration. Connect to the database. When Heartbeat tables appear, select Upgrade from the Action menu.
Upgrade notifications
OCI GoldenGate sends you event nofications for when an upgrade is available and when an upgrade is scheduled. See GoldenGate Upgrade Event types for more information, or learn more about events.
Time to upgrade | < 180 days | < 30 days | < 7 days |
---|---|---|---|
Notification period | Every 30 days | Every 7 days | Every day |
Note:
OCI GoldenGate sends notification for security fixes every day.You can also learn about upcoming upgrades from the notification banners that appear on the deployment details page.
Snooze notifications
You can snooze, or delay, event and banner notifications. The snooze period changes as you get closer to the end of the timeframe for manual upgrade.
Time to upgrade | < 180 days | < 30 days | < 7 days |
---|---|---|---|
Snooze period | 30 days | 7 days | Not allowed |
Note:
Snooze for security fixes of Minor or Bundle upgrades is not allowed.You can cancel snooze at any time.
Rollback upgrades
You can rollback a deployment version to the previous one. Rollback is only allowed for your latest successful upgrade to its previous version.
Note:
During rollback, the deployment file system is restored to its last state before upgrading.Rollback is not allowed when the previous version is deprecated.
To rollback an upgrade:
- From the Deployments page, select the deployment you want to rollback.
- On the deployment details page, select Upgrades.
- In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Rollback.
- Select the version to rollback to, and then click
Rollback.
Note:
Refer to the versions reference for a list of available versions.
Your deployment's status changes to updating and takes a few minutes to complete.
Reschedule upgrades
Note:
Rescheduling doesn't take maintenance windows into account. Your newly scheduled date can't be later than OCI GoldenGate's defined value. See About GoldenGate versions for more information.To reschedule an upgrade:
- From the Deployments page, select the deployment whose upgrade your want to reschedule.
- On the deployment details page, select Upgrades.
- In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Reschedule.
- In the Reschedule deployment upgrade window, select the date and time to perform the upgrade.
- Click Save changes.
In the Upgrades list, the Scheduled date and time reflects the changes.
Cancel upgrades
Note:
Canceling an upgrade to a minor release won't disable the auto upgrades for minor releases implicitly and must be disabled manually. You can disable minor release auto upgrade from the deployment details page. See Schedule upgrades for more information.To cancel an upgrade:
- From the Deployments page, select the deployment whose upgrade you want to cancel.
- On the deployment details page, select Upgrades.
- In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Cancel.
- In the Cancel deployment upgrade window, click Cancel deployment upgrade.
The upgrade's status is updated to Cancelled.
Known issues
Issues encountered during rollback from 21.15 or 23.x builds to 21.14
When attempting to rollback a 21.15 or 23.x build to:
- Oracle (21.14.0.0.0_240525)
- Big Data (21.14.0.0.0_240515)
- MySQL (21.14.0.0.0_240404)
- MSSQL (21.14.0.0.0_240404)
You may encounter one of the following issues:
- Missing Connections/Credentials issue due to new wallet encryption
feature introduced 21.15 onwards.
Workaround: You must unassign and reassign existing connections to the deployment and recreate missing users required for any Distribution or Receiver paths in use.
- Service Manager fails to start due to an issue with Performance Metrics Service in rollbacks from 23.x to 21.14. Contact Oracle Support if you encounter this issue.
- Oracle GoldenGate processes fail with the error, "OGG-02431 Invalid
record header found in checkpoint file."
Workaround: Upgrade the deployment to the latest 21.14 build available in the series. Contact Oracle Support if the issue persists.