Note:
- This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
- It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.
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.
Objectives
- Migrate to Oracle Cloud Infrastructure (OCI) using the ZDM tool.
Prerequisites
-
Source database should be archive log mode.
-
If the source database is on 12c Release 2 and later, Transparent Data Encryption (TDE) needs to be enabled. Ensure
WALLET_TYPE
is set toAUTOLOGIN
orPASSWORD
. -
The parameter
DB_UNIQUE_NAME
must be different on both the source database and the target database. -
Target database should be created before the migration.
-
Provision an Oracle Home at target server same as source database home version.
Task 1: Prepare and Install ZDM Server
-
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).
-
Connect to the ZDM host using putty.
-
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% /
-
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/
-
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
-
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 tozdmuser
as a root user using the following command.[root@zdm ~]# chown zdmuser:zdm /home/zdmuser/zdminstall/zdm21.5.zip
-
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...
-
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
-
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:
-
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.
-
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
-
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.
-
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
-
Connectivity from
zdmhost
to source and target database servers: Copy the SSH key from thezdmhost
aszdmuser
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
-
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
-
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:
-
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
-
Copy the template response file on
zdmhost
placed under$ZDM_HOME/rhp/zdm/template/
to a different directory. -
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
Related Links
Acknowledgments
- Author - Snehaa Patnaik (Implementation Specialist - Custom, 3rd party, VM Database & Apps)
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.
Migrate from an On-Premises 19c non-Container Database to Oracle Database 23ai Container Database
G25670-01
January 2025
Copyright ©2025, Oracle and/or its affiliates.