Database Migration

Achieve Minimal Downtime for your Exadata Cloud@Customer Migrations with Oracle ZDM and GoldenGate on Docker

Introduction

For ZDM Logical Online migrations to Exadata Cloud@Customer you will be running Oracle GoldenGate on-premises instead of on the Marketplace image on Oracle Cloud. Oracle GoldenGate keeps your source and target databases in sync and enables you to achieve zero to negligible downtime for your Oracle database migrations across database versions and platforms.

This blog post describes the steps to download the Oracle GoldenGate Docker image and install it on a VM on-premises to be used with ZDM migrations to Exadata Cloud@Customer.

The Environment

  • VM on-premises with Oracle Linux 7.9 named ggdockervm with IP 192.168.1.4.

Step 0: Download the GoldenGate Docker Image

On Oracle Cloud, create a VM using the Oracle GoldenGate – Database Migrations image from Marketplace. Search for “Goldengate migrations” in the Marketplace and choose the Database Migrations image.

Choose the latest “Oracle DB – Microservices Edition – Promotional” version, and launch the stack:

Once the stack is completed, you will find a VM in OCI Compute Instances with the details you provided during the stack launch. Log in to that VM via SSH and issue the shell list command:

-bash-4.2$ ls -l
total 0
lrwxrwxrwx. 1 opc opc 37 May 17 14:41 ogg-credentials.json -> /u02/deployments/ogg-credentials.json
lrwxrwxrwx. 1 opc opc 36 May 17 14:41 ora21c-2113000.tar -> /opt/dockerimages/ora21c-2113000.tar
drwxr-x---. 3 opc opc 18 May 17 15:55 oradiag_opc

The file /opt/dockerimages/ora21c-2113000.tar is what we are looking for. This is the GoldenGate Docker image. Copy it to your on-premises VM. Once done, you don’t need the VM in OCI anymore and you can terminate it. The only purpose of it was to get access to the ora21c-2113000.tar Docker image file.

Step 1: Set Up the Docker Engine

Set up the Docker engine on the on-premises VM that will host the GoldenGate Docker image. In this case, following the Install Docker engine on Oracle Linux 7: 

# install docker engine
[onpuser@ggdockervm ~]$ sudo yum install docker-engine docker-cli

# start docker service and configure it to start at boot time:
[onpuser@ggdockervm ~]$ sudo systemctl enable --now docker

# ensure docker service is running:
[onpuser@ggdockervm ~]$ systemctl status docker

# display configuration and version of docker engine
[onpuser@ggdockervm ~]$ sudo docker info

Step 2: Load the Docker Image

Load the Docker image to the Docker engine. The ora21c-2113000.tar file is the one you copied to this VM in Step 0:

[onpuser@ggdockervm ~]$ sudo docker load < ./ora21c-2113000.tar
67d008ba80bc: Loading layer [==================================================>]  253.7MB/253.7MB
69e9cf1483ea: Loading layer [==================================================>]  6.144kB/6.144kB
b8c7ceef0daa: Loading layer [==================================================>]  372.8MB/372.8MB
5e5793be3604: Loading layer [==================================================>]  26.62kB/26.62kB
377155359816: Loading layer [==================================================>]  1.739GB/1.739GB
4411981a6090: Loading layer [==================================================>]  18.43kB/18.43kB
Loaded image: oracle/goldengate:21.13.0.0.0

List the images:

[onpuser@ggdockervm ~]$ sudo docker image list
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
oracle/goldengate   21.13.0.0.0         f9d2aea5f6a7        4 months ago        2.34GB

Step 3: Run the Docker Image

Run the GoldenGate Docker image as a container:

[onpuser@ggdockervm ~]$ sudo docker run --name ogg2113 -p 443:443 docker.io/oracle/goldengate:21.13.0.0.0

For more information about the run parameters, check Running Oracle GoldenGate in a Container.

The run output will display the ggadmin user password. You will need this later when running the ZDM migration command:

----------------------------------------------------------------------------------
--  Password for OGG administrative user 'oggadmin' is '/Qlq1UTGMK+N-EksH'
----------------------------------------------------------------------------------

Check the status of the Docker container:

[onpuser@ggdockervm ~]$ sudo docker ps -a
CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS                 PORTS                          NAMES
d9156f6223c3        oracle/goldengate:21.13.0.0.0   "/usr/local/bin/depl…"   2 hours ago         Up 2 hours (healthy)   80/tcp, 0.0.0.0:443->443/tcp   ogg2113

To stop and start the Docker container:

[onpuser@ggdockervm ~]$ sudo docker stop d9156f6223c3
[onpuser@ggdockervm ~]$ sudo docker start d9156f6223c3

Step 4: Ensure Connectivity to Source and Target Databases

Ensure that the source and target database hostnames are resolvable and you can connect to the source and target databases from within the Docker container.

Copy an instant client (instantclient_21_3.zip) from the host VM to the Docker container:

[onpuser@ggdockervm ~]$ sudo docker cp instantclient_21_3.zip d9156f6223c3:/home/ogg/instantclient_21_3.zip

Connect to the docker container:

[onpuser@ggdockervm ~]$ sudo docker exec -it ogg2113 /bin/bash
[root@d9156f6223c3 /]#

Add the hostnames of your source and target database to the /etc/hosts file on the Docker container:

[root@d9156f6223c3 ]# vi /etc/hosts 
10.10.1.157 sourcedbhost
10.10.2.236 targetdbhost

Check database connectivity to the source and target using the hostnames in the connection string:

[root@d9156f6223c3 ]# unzip /home/ogg/instantclient_21_3.zip
[root@d9156f6223c3 ]# chmod 744 /home/ogg/instantclient_21_3/sqlplus
[root@d9156f6223c3 ]# export LD_LIBRARY_PATH=/home/ogg/instantclient_21_3
[root@d9156f6223c3 ]# /home/ogg/instantclient_21_3/sqlplus system/VerySecretPW@sourcedbhost:1521/srcpdb
[root@d9156f6223c3 ]# /home/ogg/instantclient_21_3/sqlplus system/VerySecretPW@targetdbhost:1521/tgtpdb

Step 5: Prepare your Source and Target Databases

Follow the ZDM documentation to prepare the source and target databases for the migration. See Preparing for a Logical Database Migration.

Make sure you grant the required privileges to the ggadmin database user on source and target databases.

Step 6: Prepare the ZDM Response File

Include the following GoldenGate-related information in your response file:

GOLDENGATEHUB_ADMINUSERNAME=oggadmin
GOLDENGATEHUB_SOURCEDEPLOYMENTNAME=Local
GOLDENGATEHUB_TARGETDEPLOYMENTNAME=Local
GOLDENGATEHUB_URL=https://192.168.1.4
GOLDENGATEHUB_ALLOWSELFSIGNEDCERTIFICATE=TRUE

192.168.1.4 is the IP address of the VM hosting the GoldenGate Docker image.

Now you will be ready to validate and initiate the ZDM migration using the GoldenGate Docker image. See Zero Downtime Migration (ZDM) – Logical Online Migration to VM DB Systems.

Troubleshooting

During your migration, you can pause the ZDM migration job after the ZDM_MONITOR_GG_LAG phase.

At this stage, every transaction on the source database is replicated via GoldenGate to the target database. If this is not the case, log in to the Docker container and check the EXTRACT and REPLICATE deployments and log files:

# connect to the docker container and switch to ogg user
[onpuser@ggdockervm ~]$ sudo docker exec -it ogg2113 /bin/bash
[root@d9156f6223c3 /]# su - ogg

# check the deployment files
[ogg@d9156f6223c3 ~]$ ls -l /u02/Deployment/etc/conf/ogg
total 16
-rw-r-----. 1 ogg ogg 257 Jun 10 19:05 EXT4BL3P.prm
-rw-r--r--. 1 ogg ogg  17 Jun 10 13:05 GLOBALS
-rw-r-----. 1 ogg ogg 260 Jun 10 19:34 RN22M.prm
-rw-r-----. 1 ogg ogg 260 Jun 10 19:57 RN22M.prm.backup

# check the deployments log files
[ogg@d9156f6223c3 ~]$ view /u02/Deployment/var/log/extract.log
[ogg@d9156f6223c3 ~]$ view /u02/Deployment/var/log/replicat.log

Check the deployment status:

[ogg@d9156f6223c3 ~]$ /u01/ogg/bin/adminclient
Oracle GoldenGate Administration Client for Oracle
Version 21.13.0.0.0 OGGCORE_21.13.0.0.0OGGRU_PLATFORMS_240108.2205

Copyright (C) 1995, 2024, Oracle and/or its affiliates. All rights reserved.

Oracle Linux 7, x64, 64bit (optimized) on Jan  9 2024 09:04:36
Operating system character set identified as US-ASCII.

OGG (not connected) 1> 
OGG (not connected) 1> connect http://127.0.0.1 as oggadmin password /Qlq1UTGMK+N-EksH
Using default deployment 'Local'

OGG (http://127.0.0.1 Local) 2> info all
Program     Status      Group       Type             Lag at Chkpt  Time Since Chkpt

ADMINSRVR   RUNNING
DISTSRVR    RUNNING
PMSRVR      RUNNING
RECVSRVR    RUNNING
EXTRACT     RUNNING     EXT4BL3P    INTEGRATED       00:00:01      00:00:05
REPLICAT    ABENDED     RN22M       PARALLEL NONINT  00:04:21      00:00:21

In this case, the REPLICAT status was ABENDED. The replicat.log indicated insufficient privileges for the ggadmin user on the target database. After fixing the issue, start the deployment:

OGG (http://127.0.0.1 Local) 3> start RN22M
2024-06-10T20:35:54Z  INFO    OGG-00975  Replicat group RN22M starting.
2024-06-10T20:35:54Z  INFO    OGG-15445  Replicat group RN22M started.

Conclusion

ZDM Logical Online migration to Oracle Cloud can use the GoldenGate image on OCI Marketplace. For Exadata Cloud@Customer migrations, ZDM provides a downloadable GoldenGate Docker image that you can easily install and run on-premises to achieve zero to minimal downtime when migrating across database versions and platforms.

ZDM offers a wide range of options that you might need for more flexibility and control. Have a look at the documentation for the complete list of available parameters.

Further Reading

Would you like to get notified when the next post is published?