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:

  1. On the deployment details page, under GoldenGate in the Deployment information area, for Maintenance, click Edit.
  2. In the Edit maintenance parameters dialog:
    1. (Optional) Select Customize maintenance window to change the following fields from their default values.
    2. For Major release auto-upgrade period in days, enter a value between 0 and 365.
    3. For Bundle release auto-upgrade period in days, enter a value between 0 and 180.
    4. For Security path auto-upgrade period in days, enter a value between 0 and 14.
    5. (Optional) Select Enable minor release auto-upgrade, and then enter a value for Minor release auto-upgrade period in days.
  3. 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

Use the following command in Admin Client to determine the oldest archive log that you might need to restore when Extract starts. The 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:
    Admin Client > INFO EXTRACT
    (If the source database supports this.)
  • 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:
    1. View open transactions:
      Admin Client > SEND EXTRACT group_name, SHOWTRANS
    2. Record the transaction ID of any transaction you want to clean up.
    3. Clean up old transactions using SEND EXTRACT and either the SKIPTRANS option to skip a transaction, or FORCETRANS 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]
    4. After you finish cleaning up long running transactions, force a Bounded Recovery checkpoint. 
      Admin Client> SEND EXTRACT group_name, BR BRCHECKPOINT IMMEDIATE

Synchronize Replicats

For deployments with Parallel Replicats, ensure that you sychronize Replicats before you upgrade:
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.
To upgrade a deployment:
  1. On the Deployments page, select the deployment you want to upgrade.
  2. On the deployment details page, from the Actions menu, select Upgrade.
  3. In the Upgrade deployment panel, select an available GoldenGate version to upgrade to, and then click Upgrade.

    Note:

    Learn more about versions.

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.

Upgrade Heartbeat tables
You must also upgrade Heartbeat tables if they're used in your deployment. After you complete the upgrade, you can either:
  • 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:

  1. From the Deployments page, select the deployment you want to rollback.
  2. On the deployment details page, select Upgrades.
  3. In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Rollback.
  4. 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

You can reschedule your auto scheduled upgrades. You can reschedule the upgrade to a closer date or postpone it to a later date.

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:

  1. From the Deployments page, select the deployment whose upgrade your want to reschedule.
  2. On the deployment details page, select Upgrades.
  3. In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Reschedule.
  4. In the Reschedule deployment upgrade window, select the date and time to perform the upgrade.
  5. Click Save changes.

In the Upgrades list, the Scheduled date and time reflects the changes.

Cancel upgrades

You can only cancel an auto scheduled upgrade if the target version is a minor release.

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:

  1. From the Deployments page, select the deployment whose upgrade you want to cancel.
  2. On the deployment details page, select Upgrades.
  3. In the Upgrades list, locate the most recent previous version, and then from its Action menu, select Cancel.
  4. 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.