Database Migration

Part 1/5: Zero Downtime Migration (ZDM) – Introduction & Installation

Introduction

Oracle Zero Downtime Migration (ZDM) is a free-to-use software solution that allows you to automate your Oracle database migrations to Oracle Cloud. Initially, ZDM supported Data Guard-based migrations following the principles of Oracle Maximum Availability Architecture (MAA). To support Standard Edition migrations, ZDM uses RMAN backup and restore instead. The new ZDM version 21c adds logical migration methods using Data Pump and Oracle GoldenGate supporting zero downtime migrations to Oracle Autonomous Database. In March 2023, the latest version of ZDM, version 21.4, was released with enhanced functionality.

ZDM offers four different migration methods:

  1. Logical Online Migration using GoldenGate
  2. Logical Offline Migration using Data Pump
  3. Physical Online Migration using Data Guard
  4. Physical Offline Migration using RMAN

It is also possible to use GoldenGate and Data Pump targeting co-managed cloud databases.

ZDM 21c supports Oracle database release 11.2.0.4 and later. It supports single instances, Oracle RAC One Node, and Oracle RAC configurations. Furthermore, ZDM can handle the conversion of a non-CDB source database to a PDB of the same version in the cloud as part of the physical migration process.

In this blog post, we will install the ZDM software to be ready to use in the next blog posts that will show each of the migration methods. The aim of these posts is to get you started with a minimal working configuration, as simple as possible. Check the documentation for a complete installation guide.

Preparation

It is highly recommended to have a dedicated host for the ZDM software installation. The host where the ZDM software is installed is referred to as the ZDM Service Host. The following prerequisites must be met on that host:

  • Oracle Linux 7, Oracle Linux 8, or Red Hat Enterprise Linux 8.
  • 100 GB of free storage space.
  • No Oracle Grid Infrastructure running on it.
  • Possible to connect to the source and target database (servers).

The ZDM software can be:

For this blog post, I’ll continue with the manual installation to go through the steps in case you want to install it manually. In the web console, click the navigation menu on the upper left side and select Compute > Instances. Click on Create Instance. I’ll choose the name “zdmhost” and Oracle Linux 7.9. Click on “Specify a custom boot volume size” and put 200 GB as the boot volume size. With that we will have the required 100 GB of free space:

Fill out the remaining needed information and click Create. After a few minutes, you’ll be able to log in to the compute instance. In this example, the public IP address is 130.61.21.179.

ZDM Installation

Log in to the ZDM host via ssh.

Step 1: Check available space on the file system:

[opc@zdmhost ~]$ sudo su -
[root@zdmhost ~]# df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda3       192G  4.1G  188G   3% /

We have 188G already available.

In earlier versions, we needed to extend the file system to make the additional space available. As root user:

[opc@zdmhost ~]$ sudo su -
[root@zdmhost ~]# df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda3        39G  3.2G   36G   9% /
[root@zdmhost ~]# /usr/libexec/oci-growfs -y
[root@zdmhost ~]# df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda3       192G  3.2G  189G   2% /

Step 2: Create a new group, user, and the needed directories. As root user:

[root@zdmhost ~]# groupadd zdm
[root@zdmhost ~]# useradd -g zdm zdmuser
[root@zdmhost ~]# mkdir -p /home/zdmuser/zdminstall
[root@zdmhost ~]# mkdir /home/zdmuser/zdmhome
[root@zdmhost ~]# mkdir /home/zdmuser/zdmbase
[root@zdmhost ~]# chown -R zdmuser:zdm /home/zdmuser/

Step 3: Install the required software packages. As root user:

[root@zdmhost ~]# yum install glibc-devel expect -y

For Oracle Linux 8 and Red Hat Enterprise Linux 8, check the doc for additional packages needed.

Step 4: Download the latest ZDM version from My Oracle Support (MOS) by searching for patch number 33509650 in the “Patches & Updates” tab:

21.4 is the latest version currently:

Copy the zip file to the ZDM host into the /home/zdmuser/zdminstall/ directory. Change the owner of the zip file to zdmuser. As root user:

[root@zdmhost ~]# chown zdmuser:zdm /home/zdmuser/zdminstall/V1037236-01.zip

Step 5: Install the ZDM software. As zdmuser:

Add the ZDMHOME and ZDMBASE to the zdmuser .bash_profile. As zdmuser:

[zdmuser@zdmhost ~]$ vi .bash_profile
#add
export ZDMHOME=/home/zdmuser/zdmhome
export ZDMBASE=/home/zdmuser/zdmbase

#Source the .bash_profile file to set the variables
[zdmuser@zdmhost ~]$ . .bash_profile

Unzip the ZDM software. As zdmuser:

[zdmuser@zdmhost ~]$ cd /home/zdmuser/zdminstall/
[zdmuser@zdmhost zdminstall]$ unzip V1037236-01.zip

Start the installation by running the ZDM installation script. As zdmuser:

[zdmuser@zdmhost zdminstall]$ /home/zdmuser/zdminstall/zdm21.4.1/zdminstall.sh setup oraclehome=$ZDMHOME oraclebase=$ZDMBASE ziploc=/home/zdmuser/zdminstall/zdm21.4.1/zdm_home.zip
...
ZDM service setup finished successfully...

Step 6: Start ZDM and check the status. As zdmuser:

[zdmuser@zdmhost ~]$ $ZDMHOME/bin/zdmservice start
...
Return code is 0
Server started successfully.

[zdmuser@zdmhost ~]$ $ZDMHOME/bin/zdmservice status
---------------------------------------
        Service Status
---------------------------------------
 Running:       true
...

Step 7: Verify the installed version:

[zdmuser@zdmhost ~]$ $ZDMHOME/bin/zdmcli -build
version: 21.0.0.0.0
full version: 21.4.0.0.0
patch version: 21.4.1.0.0
label date: 221207.25
ZDM kit build date: Jul 31 2023 14:24:25 UTC
CPAT build version: 23.7.0

Post Tasks

Task 1: Create an SSH key pair for zdmuser. This will be used later on to log in to the sources (and target) database server via SSH. In Oracle Linux 8, the default is OPENSSH. ZDM requires the key to be in RSA format. As zdmuser:

[zdmuser@zdmhost ~]$ ssh-keygen -m PEM -t rsa
#keep the defaults and click ENTER

Check the key format:

[zdmuser@zdmhost ~]$ head -n1 id_rsa
#to change the format:
[zdmuser@zdmhost ~]$ ssh-keygen -p -m PEM -f id_rsa

Task 2: Create an API Signing Key. This will be used to authenticate OCI CLI against the Cloud Control Plane. As zdmuser:

[zdmuser@zdmhost ~]$ mkdir ~/.oci
[zdmuser@zdmhost ~]$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048
[zdmuser@zdmhost ~]$ chmod go-rwx ~/.oci/oci_api_key.pem
[zdmuser@zdmhost ~]$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
#Copy the contents of the public key to the clipboard using pbcopy
[zdmuser@zdmhost ~]$ cat ~/.oci/oci_api_key_public.pem

Upload the PEM public key in the Console. From your user’s page, click on API Keys and Add API Key. Select Paste Public Key, paste the output from the previous command, and click Add.

The key’s fingerprint will be displayed, for example, 9f:3b:55:c1:bd:a4:3e:de:d7:e1:a1:12:eb:93:ba:3a. You’ll need this later on for the ZDM response file parameter OCIAUTHENTICATIONDETAILS_USERPRINCIPAL_FINGERPRINT.

Task 3 (optional): Install OCI CLI. As zdmuser:

[zdmuser@zdmhost ~]$ bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"
[zdmuser@zdmhost ~]$ oci setup config
Do you want to generate a new API Signing RSA key pair? [Y/n]: n
#use the once created i Task 2
Enter the location of your API Signing private key file: /home/zdmuser/.oci/oci_api_key.pem

Task 4 (optional): Check the CLI configuration, e.g., by creating an Object Storage bucket. As zdmuser:

[zdmuser@zdmhost ~]$ export COMPARTMENT_OCID=ocid1.compartment.oc1...
[zdmuser@zdmhost ~]$ oci os bucket create --compartment-id $COMPARTMENT_OCID --name zdmbucket
{
  "data": {
  ...
}

If the response contains the “Python 3.6 is no longer supported” warning message, follow Step 1: Install Python in this blog post to install Python version 3.8.

Task 5: Make sure port 1521 is open on your source and target database servers. As user root:

[root@onpremdb ~]# firewall-cmd --permanent --add-port=1521/tcp
success
[root@onpremdb ~]# firewall-cmd --reload
success

Log Files

ZDM creates log files on the source and target hosts (physical migrations) in the directory

$ORACLE_BASE/zdm/zdm_<db_name>_<job_id>/zdm/log/

Conclusion

ZDM version 21.4 provides additional capabilities for database migrations. Make sure to always use the latest release. The automation enables you to test your migration multiple times as needed, and when you are ready, ensure that you are executing the same steps and reduce human error.

Further Reading

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