With GoldenGate 19c and 21c Premier Support coming to an end in April 2026, time is ticking for many clients with old installations of GoldenGate. Fortunately, Oracle provides a Migration utility (patch 37274898 / KB100447 in MOS) that is designed to migrate your old Classic Architecture to a brand new Microservices Architecture in GoldenGate 23ai.
As mentioned in a previous blog post, the migration procedure depends on the version of GoldenGate you’re currently running on. This blog will only be about migrations of 19c/21c versions of GoldenGate. If you run GoldenGate 18c or older, you first have to upgrade to GoldenGate 19c (Classic Architecture), and then run the migration utility described below.
Prerequisites to a Migration from Classic to Microservices Architecture
Before attempting the migration, you need to prepare a few things:
- You should install GoldenGate 23ai on the same host. I wrote an article about the installation process with automation tips, if you have many deployments that need to be upgraded. Technically, you can also migrate to a 19c or 21c Microservices installation, but it doesn’t make sense to do that anymore.
- The GoldenGate 23ai processes must be running. You can have multiple deployments running at the same time, it’s not a problem for the migration. As a matter of fact, the migration tool will ask on which deployment you want to migrate, if you have more than one.
- Stop all processes from the source GoldenGate setup you want to migrate. If some processes are
ABENDED, you should either delete them, or restart them and stop them properly.
GGSCI (vmogg as ggadmin/DB1) > stop er *
GGSCI (vmogg as ggadmin/DB1) > stop mgr- If you can, try to clean the original GoldenGate setup. You should delete all drafts or unuseful connections, extracts and replicats before migrating. This way, you avoid generating errors during the migration, and you start with a clean setup on the target. More specifically, the
dirprmfolder shouldn’t include any parameter file that is not active, because the migration tool might fail trying to migrate them. - Set
OGG_HOMEandLD_LIBRARY_PATHto the home of the new 23ai installation.
[oracle@vmogg ~]$ export OGG_HOME=/u01/app/oracle/product/ogg23ai
[oracle@vmogg ~]$ export LD_LIBRARY_PATH=$OGG_HOME/lib- Patch your source GoldenGate installation at least to 200714. I’ve had successful migrations without this patch level, but Oracle recommends it.
- Install Java 1.8 JRE or later. You should be able to use the java binaries located in your GoldenGate 23ai directory.
Limitations of the Migration Utility
Even though the migration tool is powerful, it has some limitations, and you might not be able to migrate everything at once. Here are the important points to bear in mind.
Classic extracts cannot be migrated
As a reminder, classic extracts were deprecated in 19c, and desupported in 21c, so you cannot have them in 23ai. If a classic extract is set up, the migration utility will fail as such:
[oracle@vmogg ~]$ /usr/bin/java -jar ogg-migration-package-23.4.0.0.0.jar -classicHome /u01/app/oracle/product/ogg19 -dryrun
...
The following processes will be migrated to deployment ogg_test_01:
Extracts:
EXT
Do you wish to continue? (yes/no):> yes
...
Migrating EXTRACT EXT to http://oggma:7810.
ERROR: Extract EXT is a Classic Extract and GoldenGate Version 23.9.0.25.7 does not support Classic Extract.
Migration of Extract EXT Failed!
...
Migration Summary
Migration of Extract EXT .................................: Failed
Migration of Credential OracleGoldenGate.ggdb1 .........: Successful
Copy of Trail Files ......................................: Successful with Warnings
Migration of GLOBALS .....................................: Successful with Warnings
Wallet Migration .........................................: Not Attempted
Migration Simulation (Dry Run) Complete, 1 process would have migrated were successfully, 1 process migrations would have failed.To know whether your extracts are classic extracts or not, when using ggsci, run the following command and search for Oracle Redo Logs in the Log Read Checkpoint section.
GGSCI (vmogg) > info extract *
EXTRACT EXT Last Started 2025-12-22 18:17 Status STOPPED
Checkpoint Lag 00:00:00 (updated 00:00:21 ago)
Log Read Checkpoint Oracle Redo Logs
2025-12-22 18:17:16 Seqno 10, RBA 145814
SCN 0.1340545 (1340545)If it’s written Oracle Integrated Redo Logs, you’re good to go ! I wrote a blog on how to migrate classic extracts before attempting the migration, if you want to learn more on that matter.
Other limitations
The full list of restrictions is available in the Oracle documentation, but these are also important:
- If your trail files are not under the standard
dirdatdirectory, you must move the files and useconvchkbefore attempting the migration. - If you are using macros and nested
INCLUDEstatements, the migration tool does not support them.
Migration Procedure
Before migrating, here are a few things that you should know. The first one is that after the migration, all extracts and replicats will be deleted from your old Classic Architecture installation. The parameter files will still be there, but you will not see the processes in your manager (see below). However, the credentials won’t be deleted. So don’t panic if you see this in ggsci after the migration.
GGSCI (vmogg) 1> info er *
No ER groups exist.Normal extracts and replicats will be transferred as extracts and replicats in the Microservices Architecture. Pump extracts, however, will be migrated to distribution paths in the GoldenGate Distribution Service.
Another important point is that you don’t have to run the migration directly. Instead, you can use the dryrun option to simulate the migration. Keep in mind that the results will not be exactly the same ! For instance, credentials could be marked as “Successfully migrated” with the dryrun, but fail when migrating for real because they already exist on the target.
With that in mind, let’s stop all process and the manager.
GGSCI (vmogg as C##GGADMIN@CDB01/CDB$ROOT) > info er *
EXTRACT EXT Last Started 2025-12-22 18:18 Status RUNNING
Checkpoint Lag 00:02:32 (updated 00:00:05 ago)
Process ID 18041
Log Read Checkpoint Oracle Integrated Redo Logs
2025-12-22 18:16:05
SCN 0.0 (0)
GGSCI (vmogg as C##GGADMIN@CDB01/CDB$ROOT) > stop er *
Sending STOP request to EXTRACT EXT ...
Request processed.
GGSCI (vmogg as C##GGADMIN@CDB01/CDB$ROOT) > stop mgr
Manager process is required by other GGS processes.
Are you sure you want to stop it (y/n)?y
Sending STOP request to MANAGER ...
Request processed.
Manager stopped.Once the manager is stopped, first make a dryrun of the migration with the following command. The script follows the same process as the normal migration, so I will only include the output of the real migration (see at the end).
[oracle@vmogg ~]$ /usr/bin/java -jar ogg-migration-package-23.4.0.0.0.jar -classicHome /u01/app/oracle/product/ogg19 -dryrunThe utility follows these steps:
- Confirm the detected service manager URL, or give another one.
- Input manager credentials.
- Choose the target deployment.
- Confirm the list of migrated processes.
- Decide whether to migrate the old
GLOBALSfile. - Depending on the content of the migration, other inputs are needed (distribution service, for instance).
If the output of the dry run is successful, follow with the migration.
[oracle@vmogg ~]$ /usr/bin/java -jar ogg-migration-package-23.4.0.0.0.jar -classicHome /u01/app/oracle/product/ogg19
************************************************************************************
** Oracle GoldenGate Classic to Microservices Migration Utility **
** Version 23.4.0.0.0 Build 126 at Tue Jun 24 19:00:30 UTC 2025 **
** **
** Copyright (C) 1995, 2025, Oracle and/or its affiliates. All rights reserved. **
** **
** Operating system character set identified as UTF-8. **
************************************************************************************
Command Entered: -classicHome /u01/app/oracle/product/ogg19
Log File for this session is /home/oracle/./Migration122225182926.log.
Service Manager Detected at URI http://vmogg:7809.
Use Scanned URI for Service Manager? Press Enter to Accept or type Alternate URI:>
Enter Service Manager Credentials:
User Id:--> ogg
Password:->
Scanning for Microservices Deployments...
The Following Microservices Deployments have been found:
(1) - ogg_test_01 [5333bd80-9f2a-47d6-a789-8afa3e862e06]
(2) - ogg_test_02 [eadeebb7-f0d2-4900-97f6-3a427badcb5e]
Enter Deployment Number of the Deployment you wish to migrate to or 0 to quit:> 1
Using Deployment ogg_test_01 [5333bd80-9f2a-47d6-a789-8afa3e862e06]
The following processes will be migrated to deployment ogg_test_01:
Extracts:
EXT1
EXT2
EXTP
Do you wish to continue? (yes/no):> yes
Migrating Credentials from /u01/app/oracle/product/ogg19/dircrd.
Migrating Credentials for Domain OracleGoldenGate with alias of c##ggadmin.
Migrating Credentials for Domain OracleGoldenGate with alias of c##cdb01.
Copying Trail Files from /u01/app/oracle/product/ogg19/dirdat to /u01/app/oracle/product/ogg_test_01/var/lib/data/.
100% ----+----+----+----+----+----+----+----+----+----+
6 trail files copied, 1 already existed and where not overwritten, total bytes copied 7,916.
Do you wish to migrate your GLOBALS parameters? (yes/no):> yes
The Merge of GLOBALS has the following Issues:
Classic GLOBALS file does not exist, GLOBALS will not be merged.
Do you wish to continue migrating your GLOBALS parameters? (yes/no):> yes
GLOBALS parameters successfully migrated, 0 parameters were merged.
Migrating EXTRACT EXT1 to http://vmogg:7810.
Checkpoint File(s) Copied and Converted Successfully.
Parameter File ext1.prm Saved Successfully.
EXTRACT EXT1 patched.
Extract EXT1 Process Definitions patched.
Migration of Extract EXT1 Completed Successfully.
Migrating EXTRACT EXT2 to http://vmogg:7810.
Checkpoint File(s) Copied and Converted Successfully.
Parameter File ext2.prm Saved Successfully.
EXTRACT EXT2 patched.
Extract EXT2 Process Definitions patched.
Migrating PUMP EXTP to http://vmogg:7811.
Use Default Pump Target URI of ogg://vmogg:7812/services/v2/targets?trail=./ep? Press Enter to Accept or type Alternate URI:>
Creating Distribution Path for Pump EXTP.
Distribution Path Created Successfully. Setting trail sequence to 3 with an RBA of 1812.
Migration of Pump EXTP Completed Successfully.
Migrating Manager tasks to http://vmogg:7810.
No tasks to migrate.
Migration of Manager Tasks Completed Successfully.
Migration Summary
Migration of Extract EXT1 ................................: Successful
Migration of Extract EXT2 ................................: Successful
Migration of Pump EXTP ...................................: Successful
Migration of Credential OracleGoldenGate.c##ggadmin .....: Successful
Migration of Credential OracleGoldenGate.c##cdb01 .......: Successful
Migration of Credential OracleGoldenGate.ggadmin ........: Successful
Copy of Trail Files ......................................: Successful with Warnings
Migration of GLOBALS .....................................: Successful with Warnings
Wallet Migration .........................................: Not Attempted
Migration Processing Complete, 4 process were migrated successfully.Once the migration is complete, you can view all migrated objects from the Web UI. For instance, in the Extracts tab of the Administration Server.
![Thumbnail [60x60]](https://www.dbi-services.com/blog/wp-content/uploads/2025/05/JDE_Web-1-scaled.jpg)
![Thumbnail [90x90]](https://www.dbi-services.com/blog/wp-content/uploads/2022/08/JDU_web-min-scaled.jpg)
![Thumbnail [90x90]](https://www.dbi-services.com/blog/wp-content/uploads/2025/07/ALK_MIN.jpeg)