Note:

Migrate from an On-Premises 19c non-Container Database to Oracle Database 23ai Container Database

Introduction

Zero Downtime Migration (ZDM) 21.5 introduces physical migration with an in-flight upgrade, enabling seamless transitions for Oracle databases. This feature supports the migration of 11.2.0.4 and 12c Oracle databases to 19c Oracle databases, as well as migrations from 19c source databases to Oracle Database 23ai.

This tutorial outlines how ZDM facilitates the migration and conversion of a source non-Container Database (CDB) 19c database into a CDB while performing an upgrade at the target level. ZDM performs an initial migration using a temporary non-CDB target database for customers to migrate and upgrade a non-CDB database. Upon completing this initial phase, ZDM leverages auto upgrade to convert to multi-tenant and upgrade the database to the desired version.

This tutorial is specifically tailored for migrating on-premises non-CDB databases running version 19c from a Linux platform to the Oracle Database 23ai CDB.

Following are the properties and details of source and target environments.

Image showing Source and Target Details

Objectives

Prerequisites

Task 1: Prepare and Install ZDM Server

  1. Provision a dedicated compute 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 the host:

    • Oracle Linux 8 and boot volume size of 200GB.
    • 100GB of free storage space.
    • No Oracle Grid Infrastructure running on it.
    • Possible to connect to source and target database (servers).
  2. Connect to the ZDM host using putty.

  3. Run the following command to extend the filesystem to make the 200GB available.

    [opc@zdm ~]$ sudo su -
    [root@zdm ~]# df -h /
    Filesystem      Size  Used Avail Use% Mounted on
    /dev/sda3        39G  3.2G   36G   9% /
    [root@zdm ~]# /usr/libexec/oci-growfs -y
    [root@zdm ~]# df -h /
    Filesystem      Size  Used Avail Use% Mounted on
    /dev/sda3       192G  3.2G  189G   2% /
    
  4. Create a new group, user, and the needed directories as a root user using the following command.

    [root@zdm ~]# groupadd zdm
    [root@zdm ~]# useradd -g zdm zdmuser
    [root@zdm ~]# mkdir -p /home/zdmuser/zdminstall
    [root@zdm ~]# mkdir /home/zdmuser/zdmhome
    [root@zdm ~]# mkdir /home/zdmuser/zdmbase
    [root@zdm ~]# chown -R zdmuser:zdm /home/zdmuser/
    
  5. Install the required software packages as a root user using the following command.

    [root@zdm ~]# yum install oraclelinux-developer-release-el8 libnsl perl unzip glibc-devel expect libaio ncurses-compat-libs ncurses-devel numactl-libs openssl mlocate bind-utils
    
  6. Download the ZDM software version 21.5 and copy the zip file to the ZDM host to /home/zdmuser/zdminstall/ directory. Change the owner of the zip file to zdmuser as a root user using the following command.

    [root@zdm ~]# chown zdmuser:zdm /home/zdmuser/zdminstall/zdm21.5.zip
    
  7. Install the ZDM software as zdmuser using the following command.

    [zdmuser@zdm ~]$ cd /home/zdmuser/zdminstall/
    [zdmuser@zdm zdminstall]$ unzip zdm21.5.zip
    
    [zdmuser@zdm zdminstall]$ ZDMHOME=/home/zdmuser/zdmhome
    [zdmuser@zdm zdminstall]$ ZDMBASE=/home/zdmuser/zdmbase
    
    [zdmuser@zdm zdminstall]$ /home/zdmuser/zdminstall/zdm21.5/zdminstall.sh setup oraclehome=/home/zdmuser/zdmhome oraclebase=/home/zdmuser/zdmbase ziploc=/home/zdmuser/zdminstall/zdm21.5/zdm_home.zip -zdm
    ZDM service setup finished successfully...
    
  8. Run the following command to start ZDM and check the status as zdmuser.

    [zdmuser@zdm ~]$ $ZDMHOME/bin/zdmservice start
    Return code is 0
    Server started successfully.
    [zdmuser@zdm ~]$ $ZDMHOME/bin/zdmservice status
    ---------------------------------------
    		Service Status
    ---------------------------------------
    Running:       true
    
  9. Run the following command to create an SSH key pair for zdmuser. This will be used later to log in to the source and target database server using SSH. Keep the defaults.

    [zdmuser@zdm ~]$ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/zdmuser/.ssh/id_rsa):
    Created directory '/home/zdmuser/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/zdmuser/.ssh/id_rsa.
    Your public key has been saved in /home/zdmuser/.ssh/id_rsa.pub.
    The key fingerprint is:
    SHA256:giU7jz/8Z1VPiS9Ds/gfokHdevpm0dk59fPYEHRChs4
    zdmuser@zdmhost
    The key's randomart image is:
    
  10. Create an authentication token for your OCI user, from the User Details page.

    Click Auth Tokens, Generate Token, enter Description and click Generate Token.

    Note: Copy this token for your records as it will not be shown again.

    Image showing Creation of Authentication token

  11. Run the following command to install the Oracle Cloud Infrastructure Command Line Interface (OCI CLI) tool as zdmuser which will be used to access the OCI resources. For example, copy the data pump dump file into OCI Object Storage.

    [zdmuser@zdm ~]$ bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"
    

    Note: OCI CLI installation requires User OCID, Tenancy OCID, Home Region, use these values as per your cloud tenancy and keep the other parameter values as default.

    [zdmuser@zdm ~]$ oci setup config
    
  12. Run the following command to upload the API signing public key to OCI user in cloud tenancy from zdmhost.

    [zdmuser@zdmhost ~]$ cat /home/zdmuser/.oci/oci_api_key_public.pem
    -----BEGIN PUBLIC KEY-----
    **********
    -----END PUBLIC KEY-----
    

    Go to the OCI Console, navigate to User Details page, click API Keys and Add API Key. Select Paste Public Key, enter the output of the above command, and click Add.

    Image showing Adding API Key

  13. Run the following command to create a standard OCI Object Storage bucket in the OCI tenancy using OCI CLI or OCI Console.

    [zdmuser@zdm ~]$ oci os bucket create --compartment-id ocid1.compartment.oc1.....lh4lfamxdrpuxg3x……… --name zdmbucket
    
  14. Connectivity from zdmhost to source and target database servers: Copy the SSH key from the zdmhost as zdmuser to the source and target as created in Task 1.9.

    #on ZDM host as zdmuser
    [zdmuser@zdm ~]$ cat .ssh/id_rsa.pub
    #on the source database host as user opc
    [opc@sourcedb ~]$ vi .ssh/authorized_keys
    #insert the public key and save the changes
    [opc@targetdb ~]$ vi .ssh/authorized_keys
    #insert the public key and save the changes
    
  15. Resolve the hostnames of source database and target database to zdmhost by copying the hostname, IP and FQDN to /etc/hosts on zdmhost as root user.

Task 2: Run Prechecks in both Source and Target Database

  1. Run the following commands to create the ORACLE_HOME on the target Oracle Base Database Service instance with the same version as source.

    [root@tgtzdm ~]# dbcli list-dbhomes
    
    ID                                       Name                 DB Version                               Home Location                                 Status
    ---------------------------------------- -------------------- ---------------------------------------- --------------------------------------------- ----------
    c548b052-64b7-4257-bfdc-d7c201a430ab     OraDB23000_home1     23.5.0.24.07                             /u01/app/oracle/product/23.0.0.0/dbhome_1     Configured
    
    [root@tgt23ai ~]# dbcli create-dbhome -v 19.23
    
    Job details
    ----------------------------------------------------------------
    					ID:  a63db258-7ffc-4dee-b8e5-5accf223e39b
    			Description:  Database Home creation with Id : db1b4bb8-2ed0-4c0f-ade9-a656f21cf808
    				Status:  Created
    				Created:  September 19, 2024 at 3:22:48 PM IST
    			Progress:  0%
    				Message:  Create Database Home
    			Error Code:
    
  2. Run the following command to validate the database home creation.

    [root@tgt23ai ~]# dbcli describe-job --jobid a63db258-7ffc-4dee-b8e5-5accf223e39b
    
    Job details
    ----------------------------------------------------------------
    					ID:  a63db258-7ffc-4dee-b8e5-5accf223e39b
    			Description:  Database Home creation with Id : db1b4bb8-2ed0-4c0f-ade9-a656f21cf808
    				Status:  Success
    				Created:  September 19, 2024 at 3:22:48 PM IST
    			Progress:  100%
    				Message:  Create Database Home
    			Error Code:
    
    Task Name                                                                Start Time                          End Time                            Status
    ------------------------------------------------------------------------ ----------------------------------- ----------------------------------- ----------
    Database home creation                                                   September 19, 2024 at 3:22:49 PM IST September 19, 2024 at 3:27:40 PM IST Success
    
    
    [root@test23ai ~]# dbcli list-dbhomes
    
    ID                                       Name                 DB Version                               Home Location                                 Status
    ---------------------------------------- -------------------- ---------------------------------------- --------------------------------------------- ----------
    43247858-4ff6-4fcb-85f2-09d453d863bf     OraDB23000_home1     23.5.0.24.07                             /u01/app/oracle/product/23.0.0.0/dbhome_1     Configured
    a63db258-7ffc-4dee-b8e5-5accf223e39b     OraDB19000_home1     19.23.0.0.0                              /u01/app/oracle/product/19.0.0.0/dbhome_1     Configured
    

Task 3: Prepare the Response File

  1. Copy the template response file on zdmhost placed under $ZDM_HOME/rhp/zdm/template/ to a different directory.

  2. Modify the copied response file as per the source and target environment setup. The following is a sample response file shared with minimal parameters used to complete the migration with upgrade.

    TGT_DB_UNIQUE_NAME=tgt23ai_ai
    MIGRATION_METHOD=OFFLINE_PHYSICAL
    DATA_TRANSFER_MEDIUM=OSS
    PLATFORM_TYPE=VMDB
    SRC_DB_LISTENER_PORT=1521
    HOST=https://swiftobjectstorage.eu-frankfurt-1.oraclecloud.com/v1/frrudica1wgd
    OPC_CONTAINER=ZDM
    NONCDBTOPDB_CONVERSION=TRUE
    TGT_SKIP_DATAPATCH=FALSE
    ZDM_NONCDBTOPDB_PDB_NAME=newpdb23
    ZDM_PRE_UPGRADE_TARGET_HOME=/u01/app/oracle/product/19.0.0.0/dbhome_1
    

Task 4: Evaluate the Migration

Evaluate the migration by modifying the parameters as per source and target details.

./zdmcli migrate database -rsp /home/zdmuser/response_files/zdm_phyupg.rsp \
-sourcedb test \
-sourcenode test23ai1 \
-srcauth zdmauth \
-srcarg1 user:opc \
-srcarg2 identity_file:/home/zdmuser/.ssh/id_rsa \
-srcarg3 sudo_location:/usr/bin/sudo \
-targetnode tgt23ai \
-tgtauth zdmauth \
-tgtarg1 user:opc \
-tgtarg2 identity_file:/home/zdmuser/.ssh/id_rsa \
-tgtarg3 sudo_location:/usr/bin/sudo \
-tdekeystorepasswd \
-tgttdekeystorepasswd \
-backupuser oracleidentitycloudservice/s****aik@oracle.com \
-eval

Note: You can monitor the job using the following command.

$ZDM_HOME/bin/zdmcli query job -jobid <jobid>

Task 5: Perform the Actual Migration

Perform the actual migration using the following command. Modify the values as per the source and target environment.

./zdmcli migrate database -rsp /home/zdmuser/response_files/zdm_phyupg.rsp \
-sourcedb test \
-sourcenode test23ai1 \
-srcauth zdmauth \
-srcarg1 user:opc \
-srcarg2 identity_file:/home/zdmuser/.ssh/id_rsa \
-srcarg3 sudo_location:/usr/bin/sudo \
-targetnode tgt23ai \
-tgtauth zdmauth \
-tgtarg1 user:opc \
-tgtarg2 identity_file:/home/zdmuser/.ssh/id_rsa \
-tgtarg3 sudo_location:/usr/bin/sudo \
-tdekeystorepasswd \
-tgttdekeystorepasswd \
-backupuser oracleidentitycloudservice/s***aik@oracle.com

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.