Rename a GoldenGate Extract Without Missing Transactions

Throughout my consulting missions, I have often been asked to rename GoldenGate extracts. While this is not a difficult task, it should still be done correctly to avoid missing transactions. In this blog, I will explain how to rename a GoldenGate extract from the adminclient. If you often rename extracts, or want to remove the risk of a typo on a SCN by automating the process, I will also write a blog on renaming an extract with the REST API later.

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