Please read through the previous blog if you have not already done it. I explain there the two SCNs involved (the start SCN, the oldest unprocessed transaction, and the dictionary build SCN, which must predate it) and why their ordering matters. Here, I only cover how to obtain and pass them through the REST API.

As a reminder, these were the steps:

• Build the LogMiner data dictionary (if you don’t already build it regularly).
• Check for long running transactions in the source database.
• Stop the extract that you want to rename.
• Get the SCN of the oldest unprocessed transaction.
• Find the dictionary build to register the new extract.
• Create the new extract, registered and started at the correct SCNs, reusing the old extract’s parameter file with only the name and trail changed.

Building the LogMiner dictionary

DBMS_CAPTURE_ADM.BUILD is a database-side operation, not a GoldenGate one, so the REST API cannot run it directly. The script runs it through the Python oracledb module when available :

import oracledb

def build_dictionary_oracledb(dsn, user, password):
    with oracledb.connect(dsn=dsn, user=user, password=password) as conn:
        with conn.cursor() as cur:
            first_scn = cur.var(int)
            cur.execute("BEGIN DBMS_CAPTURE_ADM.BUILD(first_scn => :first_scn); END;", first_scn=first_scn)
            return int(first_scn.getvalue())

>>> build_dictionary_oracledb("localhost:1521/CDB01", "c##oggadmin", "ogg")
25261458

Or through sqlplus when oracledb is not installed :

import re
import shutil
import subprocess

def build_dictionary_sqlplus(dsn, user, password):
    if not shutil.which("sqlplus"):
        raise RuntimeError("sqlplus is not on PATH")
    script = f"""
        SET SERVEROUTPUT ON
        CONNECT {user}/{password}@{dsn}
        DECLARE
            scn NUMBER;
        BEGIN
            DBMS_CAPTURE_ADM.BUILD(first_scn => scn);
            DBMS_OUTPUT.PUT_LINE('DICTIONARY_BUILD_SCN:' || scn);
        END;
        /
        EXIT
    """
    proc = subprocess.run(["sqlplus", "-s", "/nolog"], input=script, capture_output=True, text=True)
    return int(re.search(r"DICTIONARY_BUILD_SCN:(\d+)", proc.stdout).group(1))

>>> build_dictionary_sqlplus("localhost:1521/CDB01", "c##oggadmin", "ogg")
25262183

If you already build the dictionary on a regular schedule, rename_extract.py never calls either of these : the lookup further down finds an existing build old enough to reuse and moves straight on. It only builds a fresh one as a fallback, when that lookup comes back empty.

Computing the start SCN through the API

Reading the old extract’s recovery checkpoint and the database’s active transactions (exactly what the long running transactions blog describes) gives you the oldest unprocessed transaction. get_extract_checkpoint calls GET /services/{version}/extracts/{extract}/info/checkpoints :

>>> extract_checkpoints = ogg_client.get_extract_checkpoint("EXT1")
>>> extract_checkpoints["current"]["input"][0]["recovery"]
{'timestamp': '2026-09-06T14:03:16.000Z', 'thread': 1, 'sequence': 888, 'offset': 172466704, 'csn': 25167710, 'name': None}
>>> start_scn = extract_checkpoints["current"]["input"][0]["recovery"]["csn"]
>>> start_scn
25167710

get_active_transactions runs the same check the long running transactions blog covers by hand, as a REST call to GET /services/{version}/connections/{connection}/activeTransactions :

>>> ogg_client.get_active_transactions("OracleGoldenGate.source_cdb")
{'activeTransactions': [], 'currentScn': {'csn': 25167998, 'currentDate': '2026-09-06T14:03:30.000Z', 'userName': 'SYS'}, '$schema': 'ogg:activeTransactions'}

No open transactions here, so 25167710 stands as the start SCN. Had there been one, its txnStartScn would have been folded in and the smallest of the two kept, exactly as get_oldest_unprocessed_scn does in the full script rename_extract.py (see below).

Computing the dictionary SCN

Building a LogMiner dictionary is a database-side operation (DBMS_CAPTURE_ADM.BUILD). So is finding the right existing build, directly against the source database :

import oracledb

def get_dictionary_scn_oracledb(dsn, user, password, start_scn):
    with oracledb.connect(dsn=dsn, user=user, password=password) as conn:
        with conn.cursor() as cur:
            cur.execute("""
                SELECT first_change#
                FROM v$archived_log
                WHERE dictionary_begin = 'YES'
                AND standby_dest = 'NO'
                AND name IS NOT NULL
                AND status = 'A'
                AND first_change# < :start_scn
                ORDER BY first_change# DESC
                FETCH FIRST 1 ROWS ONLY
            """, start_scn=start_scn)
            row = cur.fetchone()
            return row[0] if row else None

>>> get_dictionary_scn_oracledb("localhost:1521/CDB01", "c##oggadmin", "ogg", 25167710)
25134064

If dictionary_scn is None, no existing build predates the start SCN. It happens on a source database where the dictionary is not built on a regular schedule (the same case the adminclient blog covers by hand). rename_extract.py handles it by calling build_dictionary (above) for a fresh build. It then waits for the old extract’s checkpoint to move past that build’s SCN before continuing.

if dictionary_scn is None:
    dictionary_scn = build_dictionary(dsn, user, password, driver)
    start_scn = wait_for_dictionary_scn(ogg_client, "EXT1", "OracleGoldenGate.source_cdb", dictionary_scn)

wait_for_dictionary_scn polls get_extract_checkpoint every 30 seconds until the old extract’s start SCN passes the new build’s SCN. It gives up after 10 minutes with an error, rather than hanging forever. Both these delays are configurable. The old extract keeps running throughout, since stopping it would freeze its checkpoint.

When oracledb is not installed, the same query runs through sqlplus instead :

import shutil
import subprocess

def get_dictionary_scn_sqlplus(dsn, user, password, start_scn):
    if not shutil.which("sqlplus"):
        raise RuntimeError("sqlplus is not on PATH")
    script = f"""
        SET FEEDBACK OFF HEADING OFF PAGESIZE 0
        CONNECT {user}/{password}@{dsn}
        SELECT first_change# FROM v$archived_log
        WHERE dictionary_begin = 'YES' AND standby_dest = 'NO'
        AND name IS NOT NULL AND status = 'A'
        AND first_change# < {start_scn}
        ORDER BY first_change# DESC FETCH FIRST 1 ROWS ONLY;
        EXIT
    """
    proc = subprocess.run(["sqlplus", "-s", "/nolog"], input=script, capture_output=True, text=True)
    return int(proc.stdout.strip()) if proc.stdout.strip() else None

>>> get_dictionary_scn_sqlplus("localhost:1521/CDB01", "c##oggadmin", "ogg", 25167710)
25134064

Please note that unlike oracledb, sqlplus needs the statement’s trailing ; to execute the query.

Creating the new extract at the correct SCNs

Rather than retyping the old extract’s parameter file by hand, get_extract returns its exact config and credentials, which the new extract can reuse as is, only changing the EXTRACT name and the EXTTRAIL line :

>>> old = ogg_client.get_extract("EXT1")
>>> old["config"]
['EXTRACT EXT1', 'USERIDALIAS source_cdb DOMAIN OracleGoldenGate', 'EXTTRAIL aa', 'SOURCECATALOG PDB1', 'TABLE SALES.ORDERS;']
>>> old["credentials"]
{'alias': 'source_cdb', 'domain': 'OracleGoldenGate'}

old_config = old["config"]
credentials = old["credentials"]

new_config = []
for line in old_config:
    if line.startswith("EXTRACT "):
        new_config.append("EXTRACT EXT2")
    elif line.startswith("EXTTRAIL "):
        new_config.append("EXTTRAIL pdb1/bb")
    else:
        new_config.append(line)

The create_extract call then accepts both the begin position (start SCN) and the registration (dictionary build SCN) in a single call, on top of the reused config :

>>> ogg_client.stop_extract("EXT1")
>>> r = ogg_client.create_extract(
...     extract="EXT2",
...     begin={"at": {"csn": start_scn}},
...     registration={"containers": ["PDB1"], "csn": dictionary_scn, "replace": True},
...     source="tranlogs",
...     config=new_config,
...     credentials=credentials,
...     targets=[{"name": "bb", "path": "pdb1"}],
... )
>>> [m["title"] for m in r["messages"]]
['Integrated Extract added.', 'Extract group EXT2 successfully registered with database at SCN 25134064.', 'Parameter file EXT2.prm passed validity check.']
>>> r = ogg_client.start_extract("EXT2")
>>> [m["title"] for m in r["messages"]]
['Extract group EXT2 starting.', 'Extract group EXT2 started.']

Running OGGRestAPI’s get_extract_status method right after confirms it, with a real process ID and no lag :

>>> ogg_client.get_extract_status("EXT2")
{'$schema': 'ogg:extractStatus', 'status': 'running', 'processId': 127046, 'lastStarted': None, 'lag': 0, 'sinceLagReported': 5, 'position': '0.25477722'}

Notice how begin uses the {"at": {"csn": ...}} form to start the integrated extract at a specific SCN, and how registration carries the dictionary build SCN with its csn field. These are the REST equivalents of the add extract ... scn and register extract ... database scn commands.

The targets field is easy to miss and not optional : without it, create_extract writes the EXTTRAIL line into the parameter file but never actually creates the trail on disk, and the new extract abends on start with OGG-02454 Trail ... not found in checkpoint file. targets takes the trail’s two-character name and an optional path value. This also means the new trail must have a different name than the old extract.

Complete script

Assembling everything together into a single script, the only thing left to provide is the connection information and the new trail name. If you already have a dictionary SCN, you can pass it with --dictionary-scn, or let the script look it up by itself with --db-dsn/--db-user (--db-password is prompted if you leave it out) :

python rename_extract.py \
  --url https://vmogg \
  --user ogg \
  --deployment ogg_test_01 \
  --old-extract EXT1 \
  --new-extract EXT2 \
  --connection OracleGoldenGate.source_cdb \
  --db-dsn localhost:1521/CDB01 \
  --db-user c##oggadmin \
  --trail pdb1/bb

Here is the same EXT1 renaming, but forcing --driver sqlplus explicitly :

$ python rename_extract.py \
    --url http://localhost:7810 \
    --user ogg \
    --old-extract EXT1 \
    --new-extract EXT2 \
    --connection OracleGoldenGate.source_cdb \
    --db-dsn localhost:1521/CDB01 \
    --db-user c##oggadmin \
    --driver sqlplus \
    --trail bb
Password for ogg:
Oldest unprocessed SCN of EXT1...
  start SCN (oldest unprocessed): 25378395
Looking up the dictionary build SCN through sqlplus...
  dictionary SCN: 25342438
Stopping extract EXT1...
  start SCN after stop: 25378395
Creating extract EXT2 (register at 25342438, begin at 25378395)...
Starting extract EXT2...
Done.

The script fetches the old extract’s config and credentials, computes the start SCN from its recovery checkpoint, looks up the dictionary SCN (building a fresh one and waiting for the checkpoint to pass it if none was found), stops the old extract, then creates and starts the new one with that config, registered and started at the two SCNs.

You can find the full rename_extract.py in this reference doc. It uses oggrestapi, the GoldenGate REST API Python package you can find here or on GitHub.

L’article Rename a GoldenGate Extract with the REST API est apparu en premier sur dbi Blog.

$ pip install oggrestapi
Collecting oggrestapi
  Using cached oggrestapi-1.0.2-py3-none-any.whl (46 kB)
Collecting urllib3
  Using cached urllib3-2.6.3-py3-none-any.whl (131 kB)
Collecting requests
  Using cached requests-2.32.5-py3-none-any.whl (64 kB)
Collecting charset_normalizer<4,>=2
  Using cached charset_normalizer-3.5.1-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (262 kB)
Collecting certifi>=2017.4.17
  Using cached certifi-2026.7.22-py3-none-any.whl (136 kB)
Collecting idna<4,>=2.5
  Using cached idna-3.19-py3-none-any.whl (68 kB)
Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests, oggrestapi
Successfully installed certifi-2026.7.22 charset-normalizer-3.5.1 idna-3.19 oggrestapi-1.0.2 requests-2.32.5 urllib3-2.6.3

One package for every GoldenGate version

The biggest change is not the packaging itself, though. Until now, the repository held one oggrestapi.py per GoldenGate version (19c, 23ai, 26ai), each generated separately from that version’s swagger.json. But after thorough tests, I realized that most of the differences came from typos or inconsistencies in the swaggers with no functional differences in the API. The PyPI package now merges all of that into a single OGGRestAPI class that works against any of these versions. You can import the same class regardless of the GoldenGate release you are working with:

from oggrestapi import OGGRestAPI

What changed since the last post

A few things arrived in the client between the previous post and this release:

• Auto-discovery mode – A new auto_discovery option lets the client reach every microservice of a deployment (Administration Service, Distribution Service, etc.) from a single connection to the Service Manager, without setting up an NGINX reverse proxy first. The client looks up each service’s own port the first time it is needed.
• New methods – restart_deployment, restart_extract, restart_replicat, restart_service and restart_all_extracts / restart_all_replicats methods, on top of the existing start/stop ones. kill* methods were also added for extracts and replicats.
• Context manager support – with OGGRestAPI(...) as ogg_client: now closes the underlying HTTP session for you.
• Deployment patching helpers – Useful when patching the OGG home of a deployment (or every deployment at once) and optionally restart it, with or without an NGINX reverse proxy.

Auto-discovery in practice

Pointing the client at the Service Manager with auto_discovery=True and a deployment name is enough to access the administration service, for instance, without ever touching a reverse proxy configuration. Of course, this only works if the credentials are the same.

>>> ogg_client = OGGRestAPI(
...     url="https://vmogg:7809",  # Port to the Service Manager
...     username="ogg",
...     password="ogg",
...     deployment="ogg_test_01",
...     auto_discovery=True
... )
>>> ogg_client.list_extracts()  # Administration Service endpoint. Would normally fail if queried against the Service Manager's port.
[{'name': 'EPARTV2', 'status': 'running'}, {'name': 'EVTEXT', 'status': 'running'}, {'name': 'EXTC2', 'status': 'stopped'}, {'name': 'EXTCX', 'status': 'stopped'}, {'name': 'EXTCZ', 'status': 'stopped'}, {'name': 'EXTDB04', 'status': 'running'}, {'name': 'EXTI', 'status': 'stopped'}, {'name': 'EXTPL', 'status': 'stopped'}, {'name': 'EXTPP', 'status': 'running'}, {'name': 'EXTPT', 'status': 'running'}]
>>> ogg_client.list_replicats()
[{'name': 'REPC2', 'status': 'running'}, {'name': 'REPCX', 'status': 'running'}, {'name': 'REPCZ', 'status': 'running'}, {'name': 'REPPL', 'status': 'running'}, {'name': 'REPPT', 'status': 'running'}]

Where to find it

The package is on PyPI and the source is still on GitHub.

• pip install oggrestapi is now all it takes to get started, on any GoldenGate version.
• Of course, you can still download the oggrestapi.py separately, if you cannot run pip install commands against your environment.

L’article The GoldenGate REST API Python client is now on pip est apparu en premier sur dbi Blog.

Please note that these operations are useful not just for renaming an extract. You can also use the same steps to move an extract to another deployment, or to another host.

Can’t I just directly rename the extract and restart it ?

Unfortunately, it is not possible to just rename the extract and restart it. Extracts are registered in the database and are associated with a specific SCN. If you stop an extract and try to start it with a new name, you will get an error because the extract is not registered with the new name inside the source database. Moreover, if you try to create a new extract with the new name, you will miss transactions if you do not follow the correct steps described in this blog.

Steps to rename a GoldenGate extract

The main steps to rename a GoldenGate extract are the following:

• Build the LogMiner data dictionary (if you don’t already build it regularly).
• Check for long running transactions in the source database.
• Stop the extract that you want to rename.
• Get the SCN of the oldest unprocessed transaction.
• Find the dictionary build to register the new extract.
• Create the new extract, registered and started at the correct SCNs.
• Copy the parameter file and start the new extract.

Build the LogMiner data dictionary

To register the new extract, you need a LogMiner data dictionary build that exists at or before the start SCN. If your dictionary build SCN is after the start SCN, this will not work. If you don’t already build the dictionary regularly, build one now with DBMS_CAPTURE_ADM.BUILD :

SET SERVEROUTPUT ON
DECLARE
    scn NUMBER;
BEGIN
    DBMS_CAPTURE_ADM.BUILD(first_scn => scn);
    DBMS_OUTPUT.PUT_LINE('Dictionary build starting SCN: ' || scn);
END;
/

Dictionary build starting SCN: 17218169

PL/SQL procedure successfully completed.

Check for long running transactions in the source database

The recovery checkpoint only moves forward when a transaction commits. This means that an open long running transaction will freeze the start SCN. It is worth checking for long running transactions here : the start SCN (the oldest unprocessed transaction) must stay after the dictionary build SCN, since that build is what you register the new extract with. The further back a long running transaction freezes the start SCN, the more likely it drops before your build, and the more redo the new extract has to re-mine before it catches up. I dedicated a full blog on checking long running transactions in GoldenGate both from the adminclient and the REST API, please have a look at it.

OGG (https://vmogg ogg_test_01) 1> send extract ext1 showtrans tabular

Sending showtrans tabular request to Extract group EXT1 ...

No transactions found.

Here, the idea is to wait until there are no transactions started before the dictionary build SCN.

Stop the extract that you want to rename

Once the dictionary is built and there are no long running transactions, you can stop the extract.

OGG (https://vmogg ogg_test_01) 2> stop extract ext1

Get the SCN of the oldest unprocessed transaction

The SCN you are looking for is the one of the oldest unprocessed transaction, which corresponds to the recovery checkpoint of the extract. In the rest of the blog, I will refer to it as the start SCN, because this is the SCN from which the new extract will be started. In this example, the start SCN is 17219083.

OGG (https://vmogg ogg_test_01) 3> info extract ext1 showch
...
  Recovery Checkpoint (position of oldest unprocessed transaction in the data source):
    Timestamp: 2026-08-12 18:35:47.000000
    SCN: 0.17219083 (17219083)
...

Find the dictionary build to register the new extract

If you waited for long running transactions to commit, as mentioned before, the dictionary build that you have will be before the start SCN. However, if you build the dictionary on a regular basis and did not check the long running transactions, you need to retrieve the most recent build that is still older than the start SCN:

SELECT first_change#
FROM v$archived_log
WHERE dictionary_begin = 'YES'
AND standby_dest = 'NO'
AND name IS NOT NULL
AND status = 'A'
AND first_change# < 17219083 -- the start SCN retrieved above
ORDER BY first_change# DESC
FETCH FIRST 1 ROWS ONLY;

FIRST_CHANGE#
-------------
   17218169

The first_change# < start_scn filter is the important part. Without it, you might pick the most recent dictionary build overall, which is not guaranteed to have happened before the start SCN. In the rest of the blog, I will refer to 17218169 as the dictionary build SCN.

If the query returns no rows at all, no build predates the start SCN yet. In that case, you must build the dictionary again, as shown above. Then, you must restart the extract and wait for the oldest unprocessed transaction (recovery checkpoint) to go beyond this SCN.

Create the new extract at the correct SCNs

We now have the two SCNs we need :

• The dictionary build SCN (17218169 in the example), used to register the extract.
• The start SCN (17219083 in the example), the oldest unprocessed transaction, used to add the extract.

From the adminclient, log into the database, then create and register the new extract :

OGG (https://vmogg ogg_test_01) 4> dblogin useridalias source_cdb
Successfully logged into database CDB$ROOT.

# Here, we are using the start SCN
OGG (https://vmogg ogg_test_01) 5> add extract ext2, integrated tranlog, scn 17219083
Integrated Extract added.

# Here, we are using the dictionary build SCN
OGG (https://vmogg ogg_test_01) 6> register extract ext2 database scn 17218169 container (pdb1)
Extract group EXT2 successfully registered with database at SCN 17218169.

Copy the parameter file and start the new extract

Finally, copy the content of the parameter file from the old extract to the new one, only changing the extract name. Here, you need to make one choice:

• Keep the same trail file name, aa in this case. You will have to delete the original EXT1 extract, since two extracts cannot write to the same trail file. EXT2 will start from the next trail sequence.
• Change to another trail file name. In that case, you would have to reconfigure all replicats or distribution paths consuming the trail file.

OGG (https://vmogg ogg_test_01) 7> view params ext1
EXTRACT EXT1
USERIDALIAS source_cdb DOMAIN OracleGoldenGate
EXTTRAIL aa
SOURCECATALOG PDB1
TABLE SALES.ORDERS;

OGG (https://vmogg ogg_test_01) 8> edit params ext2
EXTRACT EXT2
USERIDALIAS source_cdb DOMAIN OracleGoldenGate
EXTTRAIL aa
SOURCECATALOG PDB1
TABLE SALES.ORDERS;

In this case, after deleting EXT1 to free the trail, assign the trail to EXT2, then start the new extract. It will pick up exactly where the old one left off.

OGG (https://vmogg ogg_test_01) 9> add exttrail aa, extract ext2
EXTTRAIL added.

OGG (https://vmogg ogg_test_01) 10> start extract ext2

L’article Rename a GoldenGate Extract Without Missing Transactions est apparu en premier sur dbi Blog.

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.

L’article GoldenGate DB2 z/OS Upgrade Checklist est apparu en premier sur dbi Blog.

The problem

Migrating ~5,600 Oracle tables to SQL Server with SSMA. Most load fine; ~100 tables fail Migrate Data with the same error:

ERROR [42S22] [Oracle][ODBC][Ora]ORA-00904:
"SYS_C00004_21081414:28:22$": invalid identifier

The named column exists in no DDL anyone wrote. The [Ora] prefix says Oracle itself is rejecting the query: SSMA built an extraction SELECT naming a column Oracle refuses to resolve. Tellingly, SELECT * and COUNT(*) run fine against the same table, whatever this column is, Oracle is happy to ignore it, but not to be asked for it by name.

Where the column actually comes from

The name is the giveaway: SYS_C00004_21081414:28:22$ is what Oracle calls a column after ALTER TABLE … SET UNUSED COLUMN.

Oracle offers two ways to get rid of a column: a logical delete and a physical one. The physical delete (ALTER TABLE … DROP COLUMN) is the honest one, but on a large table it is very time- and resource-consuming. That’s why people reach for the logical delete instead:

ALTER TABLE table_name SET UNUSED (column_name);

That statement is metadata-only and instant. The column immediately stops being visible to users, and the physical removal is deferred to whenever there is time for it (see Oracle Documentation):

ALTER TABLE table_name DROP UNUSED COLUMNS;
-- on large tables, cap undo growth by checkpointing every N rows:
ALTER TABLE table_name DROP UNUSED COLUMNS CHECKPOINT 250;

To free the original name for reuse, Oracle renames the column to SYS_C<internal column number>_<YYMMDDHH24:MI:SS>$, sets USER_GENERATED to NO, HIDDEN_COLUMN to YES and releases its COLUMN_ID. So the timestamp is not when the column was added, it is the second someone ran SET UNUSED. Ours says 14 August 2021, 14:28:22.

That also explains the error pattern. The operation is one-way and the column is unreadable by design, so naming it gets you ORA-00904 «invalid identifier». SELECT * and COUNT(*) keep working because the column no longer has a COLUMN_ID and is simply excluded from the star. SSMA, however, lists it and builds an explicit column list Oracle then refuses.

Not to be confused with SYS_NC…$. Those are a different animal: virtual columns backing a function-based index or extended statistics.

Bottom line: returning NULL costs you nothing. This is a column its owner already decided to delete, holding data Oracle itself will no longer hand out. There is no information left to lose.

What doesn’t work for the migration

• SSMA setting Ignore hidden system columns = Yes was not making any effect on this use case
• Dropping the column on SQL Server resolves nothing because the error is on the source SELECT, unaffected.
• Dropping it on Oracle could not be done in our scenario because the source is frozen; DDL not allowed.
• Custom select, column removed or bare NULL: SSMA still expects the name in its mapping and fails with “key not present” or “does not match up” before the query ever reaches Oracle.

Find them all first

Before editing anything, get the full list. Discovering the affected tables one failed migration at a time is a waste of an afternoon because the data dictionary already knows.

The reason the columns are findable at all is an asymmetry between two views: an unused column is gone from ALL_TAB_COLUMNS, but still listed in ALL_TAB_COLS with HIDDEN_COLUMN = 'YES'. That second view is what you query:

SELECT owner,
table_name,
column_name,
data_type,
internal_column_id,
TO_DATE(REGEXP_SUBSTR(column_name, '\d{8}:\d{2}:\d{2}'),
'YYMMDDHH24:MI:SS') AS set_unused_at
FROM dba_tab_cols
WHERE hidden_column = 'YES'
AND user_generated = 'NO'
AND REGEXP_LIKE(column_name, '^SYS_C\d+_\d{8}:\d{2}:\d{2}\$$')
-- AND owner = '<SCHEMA_NAME>'
ORDER BY owner, table_name, internal_column_id;

The regex is deliberately strict: it matches only the SET UNUSED naming pattern, so virtual columns and other system-generated names stay out of the result.

One more view is worth a look, as a cross-check:

SELECT owner, table_name, count AS unused_columns
FROM   dba_unused_col_tabs
--WHERE owner = '<SCHEMA_NAME>'
ORDER  BY count DESC, table_name;

DBA_UNUSED_COL_TABS gives the number of unused columns per table. Sorting by that number puts the dangerous tables first: those with two or three hidden columns are the ones where you’ll forget a line in the custom select and be back at square one.

The fix

Keep the hidden column’s name as an alias, but return a literal NULL instead of reading it. SSMA’s mapping finds the name (no “key not present”); Oracle never resolves the real column (no ORA-00904).

• Tools → Project Settings → General → Migration → enable Extended data migration options.

• Data Migration Settings tab → tick Use custom select → replace each hidden-column line with:

 SELECT ...   
    TO_CHAR("<COLUMN_NAME>", 'TM', 'NLS_NUMERIC_CHARACTERS = ''.,''') as "<COLUMN_NAME>",
    NULL as "SYS_C00004_21081414:28:22$"
from <OWNER>.<TABLE_NAME> t

• Migrate Data → 100%. Drop the NULL-filled column(s) on SQL Server in post-migration cleanup.

Takeaway

SYS_C…$ is not an exotic Oracle feature, it’s an ordinary column someone deleted years ago, logically. Oracle keeps the name on file; SSMA finds it, insists on naming it, and Oracle refuses to hand it over. Aliasing a NULL satisfies both, then you drop the column on the target. No source DDL, no external tooling, everything inside SSMA, behind a project setting that’s hidden by default.

L’article Fixing ORA-00904 on Oracle hidden columns during SSMA data migration est apparu en premier sur dbi Blog.

This blog covers the exact same setup, using the REST API instead. I will show two ways of doing it :

• Using oggrestapi.py, the GoldenGate REST client I released in another blog.
• Using the requests library to call the REST API directly.

Prerequisites

The prerequisites are the same as in the previous blog :

• Two GoldenGate Microservices deployments, ogg_test_01 (source) on oggvm1 and ogg_test_02 (target) on oggvm2. I will use the latest 26ai version.
• Both OGG setups secured with NGINX acting as a reverse proxy, so everything goes through port 443.
• A running extract on the source, writing to a trail (aa in my case).

Just like in the Web UI, there are three steps to get a working distribution path :

• Create a path connection on the source, to authenticate against the target.
• Register the target’s CA certificate on the source Service Manager.
• Create and start the distribution path.

A quick note on URLs before we start. Behind an NGINX reverse proxy, each service has its own path prefix :

• Administration Service : /services/<deployment>/adminsrvr/v2/...
• Distribution Service : /services/<deployment>/distsrvr/v2/...
• Service Manager : /services/ServiceManager/v2/...

The oggrestapi.py client builds these for you as soon as you pass reverse_proxy=True and the deployment name, so let’s connect once and reuse the client. If you don’t provide the password argument, you will be prompted for it.

from oggrestapi import OGGRestAPI

ogg_source = OGGRestAPI(
    url="https://oggvm1",
    username="ogg",
    deployment="ogg_test_01",
    reverse_proxy=True,
)

Create the path connection

As explained in Creating Path Connections with GoldenGate REST API, a path connection is simply an alias in the Network domain. It stores the credentials of a user that exists on the target deployment, and its alias is only known on the source side.

With the client, just call the create_alias method :

ogg_source.create_alias(
    alias="ogg_target",
    domain="Network",
    data={
        "userid": "ogg_user_on_target",
        "password": "***",
    },
)

As mentioned in the introduction, here is the same call with requests, calling the Administration Service of oggvm1 through NGINX :

import requests

auth = ("ogg", "ogg_password")

response = requests.post(
    "https://oggvm1/services/ogg_test_01/adminsrvr/v2/credentials/Network/ogg_target",
    auth=auth,
    json={
        "userid": "ogg_user_on_target",
        "password": "***",
    },
)

After refreshing the source Web UI, the new path connection is visible under the Path Connections tab :

But of course, you can also view the new path connection by calling the REST API:

# Since path connections are aliases of the Network domain, we use the get_alias method to retrieve them
>>> ogg_source.get_alias('Network', 'ogg_target')
{'$schema': 'ogg:credentials', 'userid': 'ogg_user_on_target', 'type': 'PASSWORD'}

Register the target’s CA certificate

Because the deployments are secured with NGINX, the source has to trust the certificate authority that signed the target’s certificate. This is done on the source Service Manager, by registering the target’s root CA certificate.

With the client, use create_deployment_certificate against the source deployment. The certificate type to use is truststore, and the certificate content goes under trustpointBundle.trustpointPem:

target_ca = open("rootCA_ogg_test_02.pem").read()

ogg_source.create_deployment_certificate(
    deployment="ogg_test_01",
    type="truststore",
    certificate="rootCA_ogg_test_02",
    data={
        "trustpointBundle": {
            "trustpointPem": target_ca,
        }
    },
)

The same call with requests, this time on the Service Manager prefix :

target_ca = open("rootCA_ogg_test_02.pem").read()

response = requests.post(
    "https://oggvm1/services/ServiceManager/v2/deployments/ogg_test_01/certificates/truststore/rootCA_ogg_test_02",
    auth=auth,
    json={
        "trustpointBundle": {
            "trustpointPem": target_ca,
        }
    },
)

Registering under the specific deployment (ogg_test_01) is the equivalent of the Local option in the Web UI. To get the Shared behavior instead, register the same certificate under the ServiceManager deployment name, so it becomes available to every deployment on that node.

If the certificate file contains a chain of certificates, you must register each certificate individually, since GoldenGate does not accept them in one go. I described that issue in detail in a blog about the OGG-30007 error.

Create and start the distribution path

We can now create the distribution path itself. It has a source endpoint (the local trail) and a target endpoint (the target’s Receiver Service, reached over wss through NGINX). Because the target is NGINX-secured, the target URI :

• uses the wss protocol on port 443,
• points at the Receiver Service path prefix, recvsrvr, not distsrvr (that prefix is only for the Distribution Service on the source side),
• does not carry the path connection alias itself. The alias goes in a separate authenticationMethod key.

With the client :

ogg_source.create_distribution_path(
    distpath="path12",
    name="path12",
    source={
        "uri": "trail://localhost/services/v2/sources?trail=PDB1/aa",
    },
    target={
        "uri": "wss://oggvm2/services/ogg_test_02/recvsrvr/v2/targets?trail=PDB1/bb",
        "authenticationMethod": {
            "domain": "Network",
            "alias": "ogg_target",
        },
    },
    begin="now",
    status="running",
)

And the equivalent requests call, on the Distribution Service prefix (/services/ogg_test_01/distsrvr/):

response = requests.post(
    "https://oggvm1/services/ogg_test_01/distsrvr/v2/sources/path12",
    auth=auth,
    json={
        "name": "path12",
        "source": {
            "uri": "trail://localhost/services/v2/sources?trail=PDB1/aa",
        },
        "target": {
            "uri": "wss://oggvm2/services/ogg_test_02/recvsrvr/v2/targets?trail=PDB1/bb",
            "authenticationMethod": {
                "domain": "Network",
                "alias": "ogg_target",
            },
        },
        "begin": "now",
        "status": "running",
    },
)

The trail value in both URIs also has to match the path the extract actually registers, EXTTRAIL PDB1/aa on the source becomes trail=PDB1/aa in the source URI, and the same logic applies to the target’s bb trail. A bare trail=aa without the PDB path segment matches neither what the extract writes nor what the target’s own directory layout expects.

Once the path is created with status: "running", the trail files start flowing. You can confirm it on the target :

oracle@oggvm2:~/ ll $OGG_DEPLOYMENT_HOME/var/lib/data/PDB1
total 0
-rw-r-----. 1 oracle oinstall 0 Mar 22 07:34 bb000000000

The remote peer submitted a certificate that failed validation

If your distribution path doesn’t start and generates a “certificate that failed validation” error, it means that you incorrectly registered your certificates. Make sure that the target deployment’s CA certificate is registered on the source Service Manager, and not the other way around.

And that’s it. With three REST calls, through oggrestapi.py or using the requests module, you get the exact same NGINX-secured distribution path as the Web UI method, but in a form you can script and repeat.

L’article NGINX Secured Distribution Path with GoldenGate REST API est apparu en premier sur dbi Blog.

Every step below shows two ways to make the same call:

• A standard requests call, the default Python module to handle REST APIs.
• The equivalent call using oggrestapi.py, the OGGRestAPI Python client I presented in another blog, which handles everything for you.

Installing the latest version of GoldenGate

This part does not change: the REST API cannot install software on the server, so you still need to unzip the patched installation to a new OGG_HOME and run runInstaller in silent mode, as described in the web UI blog.

Patching the Service Manager with the REST API

As with the web UI, the Service Manager has to be patched first. Assume the following setup:

• sm_url: https://vmogg:7809
• new_ogg_home: /u01/app/ogg/product/23.26.2.0.1
• username / password: an administrator on the Service Manager

Updating OGG_HOME is a PATCH call on the ServiceManager deployment:

import requests

sm_url = "https://vmogg:7809"
auth = ("oggadmin", "password")

requests.patch(
    f"{sm_url}/services/v2/deployments/ServiceManager",
    json={"oggHome": "/u01/app/ogg/product/23.26.2.0.1"},
    auth=auth,
)

With oggrestapi.py:

from oggrestapi import OGGRestAPI

client = OGGRestAPI(url="https://vmogg:7809", username="oggadmin", password="password")
client.update_deployment(deployment="ServiceManager", ogg_home="/u01/app/ogg/product/23.26.2.0.1")

Already, you can see that the REST API client simplifies the patching a lot.

Restarting the Service Manager is the same endpoint, this time setting status:

requests.patch(
    f"{sm_url}/services/v2/deployments/ServiceManager",
    json={"status": "restart"},
    auth=auth,
)

client.restart_deployment(deployment="ServiceManager")

restart_deployment is a dedicated method in oggrestapi.py, following the same pattern already used for restart_service, restart_extract and restart_replicat. It makes it easier to use the API, instead of building the {"status": "restart"} payload yourself. It also takes an optional only_if_running argument, so a deployment that was already stopped before the patch is left alone rather than being started by the restart call.

As with the web UI, all your deployment processes are still running on the old OGG_HOME at this point. The AIService, introduced in 26ai, does not pick up the new home automatically either. You should then list the services attached to the Service Manager and restart the ones that are not ServiceManager itself:

services = requests.get(
    f"{sm_url}/services/v2/deployments/ServiceManager/services",
    auth=auth,
).json()["response"]["items"]

for service in services:
    if service["name"] != "ServiceManager":
        requests.patch(
            f"{sm_url}/services/v2/deployments/ServiceManager/services/{service['name']}",
            json={"status": "restart"},
            auth=auth,
        )

for service in client.list_services("ServiceManager"):
    if service.get("name") != "ServiceManager":
        client.restart_service(deployment="ServiceManager", service=service.get("name"))

Patching each deployment with the REST API

Once the Service Manager runs on the new home, repeat the same update, then restart sequence for each deployment (oggHome, then status: restart):

deployment = "ogg_test_01"

requests.patch(
    f"{sm_url}/services/v2/deployments/{deployment}",
    json={"oggHome": "/u01/app/ogg/product/23.26.2.0.1"},
    auth=auth,
)

requests.patch(
    f"{sm_url}/services/v2/deployments/{deployment}",
    json={"status": "restart"},
    auth=auth,
)

client.update_deployment(deployment="ogg_test_01", ogg_home="/u01/app/ogg/product/23.26.2.0.1")
client.restart_deployment(deployment="ogg_test_01")

Once the deployment is back up, restart its extracts and replicats. Since these processes are not accessible through the Service Manager port, you need to change the URL. If you use a reverse proxy setup, or auto_discovery=True (see below), this is also easier with the Python client.

admin_url = "https://vmogg:7810"

extracts = requests.get(f"{admin_url}/services/v2/extracts", auth=auth).json()["response"]["items"]
for extract in extracts:
    requests.patch(f"{admin_url}/services/v2/extracts/{extract['name']}", json={"status": "stopped"}, auth=auth)
    requests.patch(f"{admin_url}/services/v2/extracts/{extract['name']}", json={"status": "running"}, auth=auth)

replicats = requests.get(f"{admin_url}/services/v2/replicats", auth=auth).json()["response"]["items"]
for replicat in replicats:
    requests.patch(f"{admin_url}/services/v2/replicats/{replicat['name']}", json={"status": "stopped"}, auth=auth)
    requests.patch(f"{admin_url}/services/v2/replicats/{replicat['name']}", json={"status": "running"}, auth=auth)

With oggrestapi.py, restart_all_extracts and restart_all_replicats do the same thing on an OGGRestAPI client already pointed at the deployment (either connected directly to its Administration Service, or through an NGINX reverse proxy with deployment= set):

admin_client = OGGRestAPI(url="https://vmogg:7810", username="oggadmin", password="password")
admin_client.restart_all_extracts(only_if_running=True)
admin_client.restart_all_replicats(only_if_running=True)

Automating the whole patching in one call

The steps listed above (update home, restart deployment, restart processes for every deployment) is exactly what patch_deployment (a single deployment) and patch_deployments (all of them) already do in oggrestapi.py, internally calling restart_deployment for the restart step. They also handle the ServiceManager special case (patch and restart the deployment and its services, but never restart extracts and replicats on it) and the wait_until_deployment_status polling in between:

client = OGGRestAPI(url="https://vmogg:7809", username="oggadmin", password="password", reverse_proxy=True)
client.patch_deployments(new_home="/u01/app/ogg/product/23.26.2.0.1", ask_credentials=False)

Both methods take restart_after_patch and restart_processes_after_patch (both default to True) if you need to skip either step, for example to patch every home first and restart everything in a separate maintenance window:

client.patch_deployments(
    new_home="/u01/app/ogg/product/23.26.2.0.1",
    restart_after_patch=False,
    restart_processes_after_patch=False,
    ask_credentials=False,
)

restart_processes_after_patch=True needs per-deployment routing: restarting extracts and replicats on ogg_test_01 is a different call than on ogg_test_02, and a plain connection to the Service Manager’s own port has no way to reach either one. oggrestapi.py gives you two ways to get that routing from a single client:

• reverse_proxy=True, shown above, if you already run NGINX in front of your deployments.
• auto_discovery=True, with no reverse proxy at all. The client looks up each deployment’s real Administration/Distribution/Performance Metrics Service port through the Service Manager itself (the same GET .../deployments/{deployment}/services/{service} call), the first time each one is actually needed, and reuses that lookup for the rest of the run:

client = OGGRestAPI(url="https://vmogg:7809", username="oggadmin", password="password", auto_discovery=True)
client.patch_deployments(new_home="/u01/app/ogg/product/23.26.2.0.1", ask_credentials=False)

Without either flag, patch with restart_processes_after_patch=False and restart each deployment’s processes yourself through a separate client pointed at that deployment’s own admin URL.

Some services are still running on the old OGG_HOME

Same as with the web UI: a restart call on a deployment returns as soon as the Administration Service (adminsrvr) is back up. The Receiver Service (recvsrvr) or the Distribution Service (distsrvr) can take a bit longer to restart. If, after polling for a few minutes, a service is still reporting the old home, restart it individually with the same PATCH .../services/{service} call shown above for the AIService, or with the restart_service method.

Other things to consider

If you change the name of your home at every release, remember to update OGG_HOME in every script and environment that references it, for example:

• DMK environment files.
• systemd service files, which might hardcode the OGG_HOME variable.

L’article GoldenGate 26ai out-of-place patching with Python est apparu en premier sur dbi Blog.

When and why should I worry about long running transactions ?

In a standard extract life-cycle, you should not be worrying about long running transactions. In fact, the only time you should think about these is when you plan an extract migration. By this, I mean moving an ongoing extract to a new GoldenGate environment.

This could be the case if you are moving the extract to a new GoldenGate deployment, whether it’s because of a version upgrade, system change or architecture change.

Another candidate scenario would be if you wanted to rename an extract.

Checking for Long Running Transactions with the adminclient

To check for long running transactions in the source database, you can use the adminclient and the showtrans tabular option of the send command.

OGG (https://vmogg ogg_test_01) 1> send extract ext showtrans tabular

Sending showtrans tabular request to Extract group EXT ...



XID                     Items    Extract   Redo Thread  Start Time           SCN                               Redo Seq  Redo RBA            Status
------------------------------------------------------------------------------------------------------------------------------------------------------
0.17.18.1700953         0        EXT       1            2026-06-06:08:04:12  629.3084780551 (2704619209735)    48911     156909584           Running

WARNING: This command will query the database for ALL active transactions ! There is absolutely no filter in place to only show transactions that are relevant for the extract you are targeting. To confirm this, let’s look in the database to get more information about this transaction.

-- Query to get the schema associated with a specific transaction, based on the XID column from the OGG output above
SELECT s.username, t.xidusn, t.xidslot, t.xidsqn, t.start_time, t.start_scn
FROM v$transaction t
JOIN v$session s ON t.ses_addr = s.saddr
WHERE t.xidusn = 17
AND t.xidslot = 18
AND t.xidsqn = 1700953;

USERNAME       XIDUSN     XIDSLOT      XIDSQN START_TIME          START_SCN
---------  ----------  ----------  ---------- ------------------- ----------------
DBIBLOG            17          18     1700953 06/06/26 08:04:12   2704619209735

But if I look at the extract parameter file, the DBIBLOG schema is not even being extracted.

OGG (https://vmogg ogg_test_01) 1> view params EXT
EXTRACT EXT
USERIDALIAS source_cdb DOMAIN OracleGoldenGate
EXTTRAIL pdb1/aa
SOURCECATALOG PDB1
TABLE APP_SCHEMA.*;

Of course, the DBIBLOG user might be editing data in the APP_SCHEMA schema, but there is no way to know for sure just by looking at the output of adminclient command above.

When searching for long running transactions, you should retrieve the START_SCN of the transaction. In the example given above, the START_SCN is 2704619209735.

Now that we have the START_SCN, we can check if the extract has already processed it or not by looking at the checkpoint information. From the adminclient, run the info extract EXT showch command:

OGG (https://vmogg ogg_test_01) 1> info extract EXT showch

Extract    EXT       Last Started 2026-06-06 07:45   Status RUNNING
Description          'Test extract'
Checkpoint Lag       00:01:45 (updated 00:00:32 ago)
Process ID           11711
Log Read Checkpoint  Oracle Integrated Redo Logs
                     2026-06-06:09:01:45
                     SCN 629.3086233843 (2704620663027)
Settings Profile     ogg:managedProcessSettings:dbiDefault


Current Checkpoint Detail:

Read Checkpoint #1

  Oracle Integrated Redo Log

  Startup Checkpoint (starting position in the data source):
    Timestamp: 2026-06-06:07:45:45.000000
    SCN: 0.0 (0)

  Recovery Checkpoint (position of oldest unprocessed transaction in the data source):
    Timestamp: 2026-06-06:08:04:13.000000
    SCN: 629.3084780551 (2704619209735)

  Current Checkpoint (position of last record read in the data source):
    Timestamp: 2026-06-06:09:01:45.000000
    SCN: 629.3086233843 (2704620663027)

  BR Startup Recovery Checkpoint:
    Timestamp: 2026-06-02 10:17:33.403806
    SCN: 0.0 (0)

  BR Begin Recovery Checkpoint:
    Timestamp: 2026-06-06 08:04:13.000000
    SCN: 629.3084780551 (2704619209735)

  BR End Recovery Checkpoint:
    Timestamp: 2026-06-06 08:08:45.000000
    SCN: 629.3084879559 (2704619308743)

Write Checkpoint #1

  GGS Log Trail

  Current Checkpoint (current write position):
    Sequence #: 41
    RBA: 50476
...

If we put side to side the START_SCN of the long running transaction and the SCN of the recovery checkpoint, we can see that they are exactly the same (2704619209735). This is expected, and it means that the extract has not yet processed this transaction.

# From SQL query on the source database
USERNAME       XIDUSN     XIDSLOT      XIDSQN START_TIME          START_SCN
---------  ----------  ----------  ---------- ------------------- ----------------
DBIBLOG            17          18     1700953 06/06/26 08:04:12   2704619209735

# From adminclient
  Recovery Checkpoint (position of oldest unprocessed transaction in the data source):
    Timestamp: 2026-06-06:08:04:13.000000
    SCN: 629.3084780551 (2704619209735)

If you wanted to move the extract to another GoldenGate installation or rename it, this would be the SCN at which you would need to start the new extract to avoid missing transactions.

Checking for Long Running Transactions from the REST API

If you are trying to automate the process of checking for long running transactions, using the adminclient might not be the best option. In fact, the display of long running transactions in the adminclient is not designed to be easily parsed by scripts.

Fortunately, you can also check for long running transactions using the official GoldenGate REST API. The endpoint that you need to call is GET /services/{version}/connections/{connection}/activeTransactions. It is described in the GoldenGate REST API documentation.

The endpoint path parameters explain why the transactions shown in the output are not specific to the endpoint. In GoldenGate, a connection is database specific. Combine the domain name and the alias name with a dot separator to form the connection name. In my case, the connection name is OracleGoldenGate.source_cdb.

In Python, let’s see two ways of getting the same information:

• Using the production-ready Python client I presented in another blog.
• Using the requests library to call the REST API directly.

Using the Python client, you can just call the get_active_transactions method as follows:

from oggrestapi import OGGRestAPI

ogg_client = OGGRestAPI(
    url="https://vmogg:7809",
    username="ogg",
)

active_transactions = ogg_client.get_active_transactions('OracleGoldenGate.source_cdb')

>>> active_transactions
{'activeTransactions': [{'txnStartScn': 2704619209735, 'txnStatus': 'ACTIVE', 'txnStartDate': '2026-06-06T08:04:12.000Z', 'sid': 834, 'serialNum': 16450, 'instanceId': 1, 'userName': 'DBIBLOG', 'osUser': 'oracle', 'sessionStatus': 'INACTIVE', 'logonTime': '2026-06-06T08:04:11.456Z'}], 'currentScn': {'csn': 2704620465717, 'currentDate': '2026-06-06T08:27:45.717Z', 'userName': 'SYS'}, '$schema': 'ogg:activeTransactions'}

Otherwise, with the requests library, you can call the activeTransactions endpoint as follows:

import requests

connection_name = "OracleGoldenGate.source_cdb"
# Basic configuration
# Direct connection (no reverse proxy)
# url = f"https://vmogg:7809/services/v2/connections/{connection_name}/activeTransactions"
# NGINX reverse proxy
url = f"https://vmogg/services/ogg_test_01/adminsrvr/v2/connections/{connection_name}/activeTransactions"

auth = ("ogg", "ogg_password")
response = requests.get(
    url,
    auth=auth
)

Here is an example of the output that you should get when looking at the response.json() value:

>>> active_transactions = response.json()['response']
>>> active_transactions
{'activeTransactions': [{'txnStartScn': 2704619209735, 'txnStatus': 'ACTIVE', 'txnStartDate': '2026-06-06T08:04:12.000Z', 'sid': 834, 'serialNum': 16450, 'instanceId': 1, 'userName': 'DBIBLOG', 'osUser': 'oracle', 'sessionStatus': 'INACTIVE', 'logonTime': '2026-06-06T08:04:11.456Z'}], 'currentScn': {'csn': 2704620465717, 'currentDate': '2026-06-06T08:27:45.717Z', 'userName': 'SYS'}, '$schema': 'ogg:activeTransactions'}

Or using the json.dumps() method to get a more readable output:

>>> import json
>>> print(json.dumps(active_transactions, indent=4))
{
    "activeTransactions": [
        {
            "txnStartScn": 2704619209735,
            "txnStatus": "ACTIVE",
            "txnStartDate": "2026-06-06T08:04:12.000Z",
            "sid": 834,
            "serialNum": 16450,
            "instanceId": 1,
            "userName": "DBIBLOG",
            "osUser": "oracle",
            "sessionStatus": "INACTIVE",
            "logonTime": "2026-06-06T08:04:11.456Z"
        }
    ],
    "currentScn": {
        "csn": 2704620465717,
        "currentDate": "2026-06-06T08:27:45.717Z",
        "userName": "SYS"
    },
    "$schema": "ogg:activeTransactions"
}

Using the REST API, the information is more complete and easier to parse. As mentioned before, retrieving the SCN at which the transaction started is sometimes necessary. In that case, you can get it from the following command:

>>> start_scn = active_transactions['activeTransactions'][0]['txnStartScn']
>>> start_scn
2704619209735

If you have multiple long running transactions, you should retrieve the minimum value for the txnStartScn to be sure to get the SCN of the oldest long running transaction.

>>> start_scns = [txn['txnStartScn'] for txn in active_transactions['activeTransactions']]
>>> min(start_scns)
2704619209735

Now that we’ve retrieved the START_SCN of the long running transaction, we should check the checkpoint information.

Using the Python client, you can call the get_extract_checkpoint method as follows:

>>> extract_checkpoints = ogg_client.get_extract_checkpoint('EXT')
>>> extract_checkpoints
{'$schema': 'ogg:extractCheckpoints', 'current': {'input': [{'starting': {'timestamp': '2026-06-06T07:45:45.000Z', 'thread': 1, 'sequence': 0, 'offset': 0, 'csn': None, 'name': None}, 'recovery': {'timestamp': '2026-06-06T08:04:13.000Z', 'thread': 1, 'sequence': 48911, 'offset': 156909584, 'csn': 2704619209735, 'name': None}, 'current': {'timestamp': '2026-06-06T09:01:45.000Z', 'thread': 1, 'sequence': 0, 'offset': 0, 'csn': 2704620663027, 'name': None}, 'boundedRecoveryPrevious': {'timestamp': '2026-06-02 10:17:33.404Z', 'thread': 0, 'sequence': 0, 'offset': 0, 'csn': None, 'name': None}, 'boundedRecoveryBegin': {'timestamp': '2026-06-06T08:04:13.000Z', 'thread': 0, 'sequence': 48911, 'offset': 156909584, 'csn': 2704619209735, 'name': None}, 'boundedRecoveryEnd': {'timestamp': '2026-06-06T08:08:45.000Z', 'thread': 1, 'sequence': 48912, 'offset': 156918384, 'csn': 2704619308743, 'name': None}}]}

Or, using the requests library:

response = requests.get(
    "https://vmogg/services/ogg_test_01/adminsrvr/v2/extracts/EXT/checkpoint",
    auth=auth
)

extract_checkpoints = response.json()['response']

Here is a more readable output from the checkpoint information:

>>> print(json.dumps(extract_checkpoints, indent=4))
{
    "$schema": "ogg:extractCheckpoints",
    "current": {
        "input": [
            {
                "starting": {
                    "timestamp": "2026-06-06T07:45:45.000Z",
                    "thread": 1,
                    "sequence": 0,
                    "offset": 0,
                    "csn": null,
                    "name": null
                },
                "recovery": {
                    "timestamp": "2026-06-06T08:04:13.000Z",
                    "thread": 1,
                    "sequence": 48911,
                    "offset": 156909584,
                    "csn": 2704619209735,
                    "name": null
                },
                "current": {
                    "timestamp": "2026-06-06T09:01:45.000Z",
                    "thread": 1,
                    "sequence": 0,
                    "offset": 0,
                    "csn": 2704620663027,
                    "name": null
                },
                "boundedRecoveryPrevious": {
                    "timestamp": "2026-06-02T10:17:33.404Z",
                    "thread": 0,
                    "sequence": 0,
                    "offset": 0,
                    "csn": null,
                    "name": null
                },
                "boundedRecoveryBegin": {
                    "timestamp": "2026-06-06T08:04:13.000Z",
                    "thread": 0,
                    "sequence": 48911,
                    "offset": 156909584,
                    "csn": 2704619209735,
                    "name": null
                },
                "boundedRecoveryEnd": {
                    "timestamp": "2026-06-06T08:08:45.000Z",
                    "thread": 1,
                    "sequence": 48912,
                    "offset": 156918384,
                    "csn": 2704619308743,
                    "name": null
                }
            }
        ]
    }
}

And to finish with, from the json, you can retrieve the SCN of the recovery checkpoint:

>>> recovery_checkpoint_scn = extract_checkpoints['current']['input'][0]['recovery']['csn']
>>> recovery_checkpoint_scn
2704619209735

Whether it’s to rename or move an extract, you now know why you should check long running transactions in GoldenGate, and how to do it from the adminclient and the REST API.

L’article Checking Long Running Transactions in GoldenGate est apparu en premier sur dbi Blog.

In this GoldenGate upgrade, the previous driver was version 11.1 and the target version was 12.1. After installing the new driver, db2cli execsql commands that previously worked started failing with the following error:

db2cli execsql -db <database_alias> -user <username> -passwd <password> \
  -inputsql /home/oracle/input.sql

Where /home/oracle/input.sql just contains a trivial test query:

select 1 from sysibm.sysdummy1;

The sysibm.sysdummy1 table is DB2’s equivalent of Oracle’s DUAL, so this is about the simplest query you can run to check connectivity. It failed with the following error:

SQLError: 1 = 0 (SQL_SUCCESS)
SQLGetDiagRec: 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

What SQL1598N means

SQL1598N means the DB2 client does not have a valid license to connect to this database. The CLI driver loaded fine. But when it tried to establish an authenticated connection the server rejected it on licensing grounds.

This is distinct from a connection failure or an authentication failure.

Root cause

It might not be obvious for Oracle-accustomed DBAs, but the DB2 CLI Driver does not ship with a license file for connecting to DB2 for z/OS. A separate license file named db2consv_zs.lic must be placed manually in the clidriver/license/ directory of the driver installation.

The critical point is that the license file is version-specific and cannot be reused across driver versions. The license file that worked with driver 11.1 is not valid for driver 12.1. After upgrading the driver, the new installation directory does not contain the license file in the license/ folder, and copying the old license file into it will not resolve the error.

Observed behavior

The error was reproducible every time the same command was run against the new driver. For reference, a successful run against a properly licensed driver returns:

FetchAll: Columns: 1
1
1
FetchAll: 1 rows fetched.

License file location

It is important to keep in mind that the license file belongs in the license/ subdirectory of the CLI driver installation. With CLI driver 11.1, the path looked like:

/opt/ibm/db2_odbc_cli_11_1/clidriver/license/db2consv_zs.lic

After upgrading to 12.1, the new driver has its own separate installation directory with its own license/ subdirectory. Placing the old 11.1 license file there will not work – the file is tied to the driver version.

How to fix the issue ?

Since the old file is unusable, you must obtain a new license file matching the installed driver version from IBM. Essentially, you have two options here:

• Contact your DB2 engineers: if someone on the team manages IBM software licenses, they should be able to provide the correct db2consv_zs.lic for the version you installed.
• Open a case with IBM customer support: IBM will provide the appropriate license file for the new driver version.

Once you have the correct file, place it in the clidriver/license/ directory of the new driver installation and retry the same db2cli execsql command given above. No restart is required.

DB2 CLI drivers are not that complicated to use and to debug. However, there are a few fundamentals that GoldenGate administrators should know before attempting a migration. Renewing the license file is one of them.

L’article DB2 SQL1598N Licensing Error When Upgrading GoldenGate est apparu en premier sur dbi Blog.

The client’s GoldenGate extract was running on a dedicated server, capturing changes from an Oracle 19c source database. Trail files were written on an NFS. Depending on the configuration, this is officially supported by Oracle, and works rather well.

OGG-02897 / OGG-01668 Input/Output Error

On a Monday morning, however, the extract was ABENDED. The extract had been down since Saturday night, with the following error messages:

2026-06-07T00:19:11.404+0200  ERROR   OGG-02897  Oracle GoldenGate Capture for Oracle, EXT.prm:  Failed to synchronize trail file. Error detail: Could not sync "PDB1/aa000000009" (error 5, Input/output error).
2026-06-07T00:19:11.404+0200  ERROR   OGG-01668  Oracle GoldenGate Capture for Oracle, EXT.prm:  PROCESS ABENDING.

The extract was failing with an OGG-02897 error. The OS-level error, errno 5: Input/output error, did not seem to indicate any good news for us. Needless to say that restarting the extract did not fix the issue.

Root Cause Analysis

A firewall upgrade had taken place that Saturday night. The firewall between the GoldenGate server and the NFS server was upgraded, and it briefly went down during the operation.

The real problem was what happened after the firewall came back up: some extracts caught up and managed to restart properly, while other were left in this ABENDED state, unable to restart. For these extracts, I/O operations kept failing even though the network path was healthy again.

Solution: Remount the NFS

The solution was to stop all GoldenGate processes whose trail files were generated on the NFS, including all the processes which were running fine, and then unmount and remount the NFS filesystem.

# Unmount the NFS path
umount /path/to/nfs

# Remount all filesystems defined in /etc/fstab, including the NFS
mount -a

Once that came back up, I restarted the extracts from the adminclient and they all started successfully.

In this case, the firewall upgrade happened during the night with no GoldenGate-aware procedure in place. Next time, a scheduled GoldenGate maintenance spanning over the firewall upgrade window will probably avoid crashing multiple replications during the week-end, or worse.

L’article GoldenGate Extract Abending on NFS Trail: OGG-02897 / OGG-01668 Input/Output Error est apparu en premier sur dbi Blog.