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.

Image showing Source and Target Details

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 to AUTOLOGIN or PASSWORD.
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 to zdmuser 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 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

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

Announcing Oracle Zero Downtime Migration 21.5

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.

Title and Copyright Information

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

G25670-01

January 2025

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

Introduction

Objectives

Prerequisites

Task 1: Prepare and Install ZDM Server

Task 2: Run Prechecks in both Source and Target Database

Task 3: Prepare the Response File

Task 4: Evaluate the Migration

Task 5: Perform the Actual Migration

Related Links

Acknowledgments

More Learning Resources