GoldenGate DB2 z/OS Upgrade Checklist

Upgrading GoldenGate when the source is DB2 for z/OS is not quite the same exercise as upgrading a GoldenGate installation for Oracle. Most of what I described in my generic blogs about planning a GoldenGate upgrade and migrating from Classic to Microservices Architecture is still valid. However, there is an extra layer to deal with. It has to do with the IBM Data Server Driver for ODBC and CLI, and everything DB2-side depending on it. This blog is a consolidated checklist of everything you should check before, during, and after a GoldenGate for DB2 z/OS upgrade, based on issues I faced.

Why DB2 z/OS upgrades are different

With Oracle, a GoldenGate upgrade does not really involve the databases themselves. You just have to install the new home, and migrate or reconfigure extracts and replicats. Provided that you do not have a complex custom layer on top of it (automation, pipelines, etc.), this is everything you have to do. With DB2 z/OS, GoldenGate talks to the DB2 database through the CLI driver. This driver has its own version, its own licensing, and its own DB2-side procedures that need to be updated. If you only upgrade GoldenGate and the CLI driver but forget the DB2 z/OS side, you will hit errors when trying to extract data from DB2. On top of this, a stored procedure is installed in the DB2 database, for GoldenGate to work.

The SQL1598N licensing issue

The first error you might encounter when upgrading the CLI driver as part of a GoldenGate upgrade is related to the licensing file. I detailed this in a previous blog, but the short version is: the IBM Data Server Driver for ODBC and CLI does not ship with a license file to connect to DB2 for z/OS. A separate file, db2consv_zs.lic, has to be placed manually into the clidriver/license/ directory. This file is tied to the exact driver version ! Reusing the license from your old driver (11.1) in the new driver’s directory (12.1) will not work, and connections will fail with:

SQLState : 42968
NativeError : -1598
DiagMsg: [IBM][CLI Driver] SQL1598N An attempt to connect to the database
server failed because of a licensing problem. SQLSTATE=42968

Remember to get the new license file and test it way before the cutover. Whoever manages IBM software on your side, or IBM support directly, needs to provide a new db2consv_zs.lic matching the target driver version. Since getting a license file from IBM support is rarely instantaneous, plan some time to get this done.

The DB2-side stored procedure step

This is the part which is easy to miss because it doesn’t happen on the GoldenGate host at all. However, it is documented by Oracle. A GoldenGate extract for DB2 z/OS relies on an initialization and utility stored procedure which is installed directly in DB2 itself. This stored procedure ships with each GoldenGate release and is versioned against it. When you upgrade GoldenGate, the stored procedure sitting in the DB2 subsystem does not upgrade itself. It stays at whatever version was installed during the last GoldenGate install, until it is explicitly reinstalled.

When setting up a new GoldenGate home for DB2, a zOSutils.zip file is included under $OGG_HOME/lib. This is what you must use. The new stored procedure will replace the old one in the catalog.

Just like the CLI driver issues described above, this should be managed by DB2 engineers. Installing or replacing a stored procedure at the DB2 level requires the appropriate privileges, which a Database/GoldenGate/Linux administrator typically does not have. Talk with your DB2 for z/OS DBA or systems engineer as part of the upgrade plan, and treat the stored procedure reinstall as a mandatory step of the GoldenGate upgrade itself.

OGG-30121 or OGG-30057 with DB2 procedure upgrade

If GoldenGate itself gets upgraded but the stored procedure in the DB2 subsystem is left at its old version, the extract will detect the mismatch at startup and abend with OGG-30121:

OGG-30121  ERROR  The initialization and utility stored procedure major version is 210610 and is not compatible with this Extract. (The minor version is 00).

Getting an OGG-30121 error during a GoldenGate upgrade means that the DB2-side stored procedure reinstall was missed. There is no need to start debugging the GoldenGate configuration.

Also, please note that this stored procedure change needs to happen during the GoldenGate upgrade, not before. What I mean by this is that you cannot ask for the stored procedure to be updated a week before the GoldenGate upgrade. You will need to allocate time for updating the stored procedure in your upgrade scenario.

The reverse situation also exists. If you update the procedure but not GoldenGate, you will have an OGG-30057 error when attempting to restart the extracts.

OGG-30057  ERROR  The log reading user-defined function major version is 231010 and is not supported. (The minor version is 00)

Other things to check during the upgrade

Here are a few other points regarding issues I faced when upgrading GoldenGate for DB2 setups in the past:

• The response file contain an IBMCLIDRIVER variable. It must point to the actual root of the CLI driver installation, not a parent directory. A wrong path produces an INS-85037 deployment error when using oggca.sh.
• Confirm your GoldenGate version is still under Premier Support or Extended Support before you upgrade. Indeed, 19c and 21c Premier Support came to an end in May 2026, as covered in my migration planning blog.

Using the Migration Utility with DB2 z/OS sources

If part of your upgrade also involves moving from Classic Architecture to Microservices, the general procedure and its limitations are the same, regardless of source database, and covered in Upgrade GoldenGate from Classic to Microservices Architecture. You can use the migration utility delivered by Oracle (patch 37274898 / KB100447 in MOS). You will still have to pay attention to the points described above.

Checklist summary

Before upgrading GoldenGate for DB2 z/OS:

• Confirm your support status before deciding on a target version. You should upgrade to 26ai.
• Identify the current and target CLI driver version and request the matching db2consv_zs.lic from IBM (or your internal license owner) ahead of time, if needed.
• Open a change request with your DB2 for z/OS DBA/systems engineer to reinstall the GoldenGate stored procedure in every affected DB2 database. This must be done during the upgrade, after stopping and before restarting the new extracts.
• After cutover, if an extract abends with the OGG-30121 or OGG-30057 error, check the stored procedure at the DB2 level.

With this, I hope you will succeed in your GoldenGate for DB2 z/OS migrations and upgrades.