Previous Next JavaScript must be enabled to correctly display this content

## 4 Preparing for a Physical Database Migration

Before starting a Zero Downtime Migration physical database migration you must, prepare the source and target databases, set parameters in the response file, and configure any required migration job customization. Configure connectivity between the source to target databases for online physical migration.

Note:

The hostname must be different in both source and target, if the hostname is the same, the migration will fail.
See the Zero Downtime Migration Release Notes for the latest information about new features, known issues, and My Oracle Support notes.

### 4.1 Prerequisites for Online Physical Migration

You must configure connectivity prerequisites for online physical migration.If connectivity using SCAN and the SCAN port is not possible between the source and target database servers, set up an SSH tunnel from the source database server to the target database server.

Related Topics

- Set up an SSH Tunnel

### 4.2 Preparing the Source and Target Databases

There are several tasks you must complete on the source and target databases before configuring a migration job. The following are prerequisites that apply to both source and target database.

- Zero Downtime Migration online physical migrations leverage Oracle Data Guard, so you must have the same operating system and database version on both source and target.

- The Zero Downtime Migration physical migration work flow does not support cross-edition migration; however, you can migrate Standard Edition to Enterprise Edition using the logical migration work flow.

- The character set on the source database must be the same as the target database.

- The source and target databases must use a server parameter file (SPFILE).

- ZDM supports the source databases that are not using SPFILE for offline migration. For online migration, you must run the source database with SPFILE.

- System time of the Zero Downtime Migration service host and source database server should be in sync with your Oracle Cloud Infrastructure target.

  If the time on any of these systems varies beyond 6 minutes from the time on OCI, it should be adjusted. You can use `ntp time check` to synchronize the time if NTP is configured. If NTP is not configured, then it is recommended that you configure it. If configuring NTP is not an option, then you need to correct the time manually to ensure it is in sync with OCI time.

- Set the `COMPATIBLE` database initialization parameter to the same value on the source and target database. See Values for the COMPATIBLE Initialization Parameter in Oracle Database for valid values.

- Ensure that both source and target SQLNET.ORA have the same encryption algorithm.

- Ensure that the target database time zone is same as the source or higher. If the source database time zone version is lower than the target database, then post migration, you must upgrade the database timezone. Time zone upgrade will encounter downtime when you adjust the time zone and this involves database to be restarted twice. The downtime involved in the time zone upgrade depends on the amount of data requiring change. Preferably, match the time zone version of the source and the target database to avoid time zone upgrade involving extended downtime. However, ZDM automates upgrading time zone for physical migration as a part of workflow. See ZDM_TGT_UPGRADE_TIMEZONE_FILE .
- ZDM enables backup compression and encryption to be turned off. You can turn off the encryption when migrating between on-premises databases only. Encryption is mandatory when migrating to cloud targets. See ZDM_RMAN_ENCRYPT_BACKUP.
- You can configure the section size to be used by RMAN. See ZDM_RMAN_SECTION_SIZE.
- Ensure that `/tmp` is mounted with `execute` permission as a prerequisite for the source and target databases if you want to perform a physical migration.

### 4.3 Source Database Prerequisites

Meet the following prerequisites on the source database before the Zero Downtime Migration process starts.

- Set archiving mode

  The source database must be running in `ARCHIVELOG` mode. See Changing the Database Archiving Mode.

- Configure the TDE wallet on Oracle Database 12c Release 2 and later.

  For Oracle Database 12c Release 2 and later, if the source database does not have Transparent Data Encryption (TDE) enabled, then it is mandatory that you configure the TDE wallet before migration begins. You need not encrypt the data in the source database; the data is encrypted at target using the wallet setup in the source database. The `WALLET_TYPE` can be `AUTOLOGIN` (preferred) or `PASSWORD` based.

  Ensure that the wallet `STATUS` is `OPEN` and `WALLET_TYPE` is `AUTOLOGIN` (For an `AUTOLOGIN` wallet type), or `WALLET_TYPE` is `PASSWORD` (For a `PASSWORD` based wallet type). For a multitenant database, ensure that the wallet is open on all PDBs as well as the CDB, and the master key is set for all PDBs and the CDB.

      SQL> SELECT * FROM v$encryption_wallet;

  Enabling TDE on Oracle Database 11g Release 2 (11.2.0.4) and Oracle Database 12c Release 1 is optional.

- For Oracle RAC:

  If the source is an Oracle RAC database, and `SNAPSHOT CONTROLFILE` is not on a shared location, configure `SNAPSHOT CONTROLFILE` to point to a shared location on all Oracle RAC nodes to avoid the ORA-00245 error during backups to Oracle Object Store.

  For example, if the database is deployed on ASM storage,

      $ rman target /
      RMAN> CONFIGURE SNAPSHOT CONTROLFILE NAME TO '+DATA/db_name/snapcf_db_name.f';

  If the database is deployed on an ACFS file system, specify the shared ACFS location in the above command.

- Check port connections

  - Verify that port 22 on the source database server allows incoming connections from the Zero Downtime Migration service host.

  - Ensure that the scan listener ports (1521, for example) on the source database servers allow incoming connections from the target database servers and outgoing connections to the target database servers.

    Alternate SQL connectivity should be made available if a firewall blocks incoming remote connection using the SCAN listener port.

- Maintain RMAN backup strategy

  To preserve the source database Recovery Time Objective (RTO) and Recovery Point Objective (RPO) during the migration, the existing RMAN backup strategy should be maintained.

  During the migration a dual backup strategy will be in place; the existing backup strategy and the strategy used by Zero Downtime Migration.

  Avoid having two RMAN backup jobs running simultaneously (the existing one and the one initiated by Zero Downtime Migration).

  If archive logs were to be deleted on the source database, and these archive logs are needed by Zero Downtime Migration to synchronize the target cloud database, then these files should be restored so that Zero Downtime Migration can continue the migration process.

- Configure RMAN to automatically back up to control file

  If RMAN is not already configured to automatically back up the control file and SPFILE, then set `CONFIGURE CONTROLFILE AUTOBACKUP` to `ON` and revert the setting back to `OFF` after migration is complete.

      RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON;

- Register with SRVCTL

  If the source database is deployed using Oracle Grid Infrastructure and the database is not registered using SRVCTL, then you must register the database before the migration.

- For offline migrations

  Plan to make sure no incoming transactions take place on the source database before the `ZDM_BACKUP_DIFFERENTIAL_SRC` phase, so that there is no loss of data during the migration.

  Once Zero Downtime Migration starts generating backups and transfers them, any new transactions on the source won't be part of the backups and therefore the target in the cloud won't have those changes.

- Handling of DB_nK_CACHE_SIZE

  Zero Downtime Migration automates the copy of DB_nK_CACHE_SIZE values from the source `init` file to the target database. This automation benefits migrations where the source database uses any tablespace of variable block size other than `db_block_size`. In such cases, without Zero Downtime Migration handling of `DB_nK_CACHE_SIZE`, the restore process would fail.

  Note:

  For migrations where non-CDB to PDB conversion takes place, you must set this value in the actual target CDB in which the source will be plugged in.

### 4.4 Target Database Prerequisites

You must create a placeholder target database before beginning a migration to the target environment. The following prerequisites must be met on the target database before you begin the Zero Downtime Migration process.

The placeholder target database is overwritten during migration, but it retains the overall configuration.

- For this release, only Grid Infrastructure-based database services are supported as targets. For example, an LVM-based instance or an instance created in a node without Grid Infrastructure are not supported targets.

- For the Oracle Exadata Database Service on Dedicated Infrastructure and Oracle Exadata Database Service on Cloud@Customer targets, the placeholder database must be created using the Control Plane, not Grid Infrastructure Database Services before database migration begins.

- Size for the future

  When you create the database from the console, ensure that your chosen shape can accommodate the source database, plus any future sizing requirements. A good guideline is to use a shape similar to or larger in size than source database.

- Set name parameters

  - `DB_NAME`

    If the target database is Oracle Exadata Database Service on Dedicated Infrastructure or Oracle Exadata Database Service on Cloud@Customer, then the database `DB_NAME` should be the same as the source database `DB_NAME`.

    If the target database is Oracle Cloud Infrastructure, then the database `DB_NAME` can be the same as or different from the source database `DB_NAME`.

  - `DB_UNIQUE_NAME`

    If the target database is Oracle Cloud Infrastructure, Oracle Exadata Database Service on Dedicated Infrastructure, or Oracle Exadata Database Service on Cloud@Customer, the target database `DB_UNIQUE_NAME` parameter value must be unique to ensure that Oracle Data Guard can identify the target as a different database from the source database.

    Note:

    Ensure that the name for source and target database are same and they also have the same letter case, lowercase or uppercase.

- Match the source SYS password

  Specify a `SYS` password that matches that of the source database.

- Disable automatic backups

  Provision the target database from the console without enabling automatic backups.

  For Oracle Cloud Infrastructure and Oracle Exadata Database Service on Dedicated Infrastructure, do not select the Enable automatic backups option under the section Configure database backups.

  For Oracle Exadata Database Service on Cloud@Customer, set Backup destination Type to `None` under the section Configure Backups.

- Verify patch level

  The target database version should be the same as the source database version. Oracle recommends that the target database patch level should also be the same as (or higher than) the source database.

  Note:

  While Oracle Zero Downtime Migration supports discrepancies in patch levels, it is always recommended, even for the purposes of migration, to only have a difference of one year maximum between patch levels.

  If the target database environment is at a higher patch level than the source database (for example, if the source database is at Jan 2020 PSU/BP and the target database is at April 2020 PSU/BP), then Zero Downtime Migration runs the datapatch utility as part of the migration.

- Verify time zone file version

  The target placeholder database must have a time zone file version that is the same or higher than the source database. If that is not the case, then the time zone file should be upgraded in the target placeholder database.

  To check the current time zone version, query the `V$TIMEZONE_FILE` view as shown here, and upgrade the time zone file if necessary.

      SQL> SELECT * FROM v$timezone_file;

- Verify TDE wallet folder exists

  Verify that the TDE wallet folder exists, and ensure that the wallet `STATUS` is `OPEN` and `WALLET_TYPE` is `AUTOLOGIN` (For an auto-login wallet type), or `WALLET_TYPE` is `PASSWORD` (For a password-based wallet). For a multitenant database, ensure that the wallet is open on all PDBs as well as the CDB, and the master key is set for all PDBs and the CDB.

      SQL> SELECT * FROM v$encryption_wallet;

- For Oracle RAC targets:

  If the target is an Oracle RAC database, then verify that SSH connectivity without a passphrase is set up between the Oracle RAC servers for the oracle user.

- Check disk groups size and usage

  Check the size of the disk groups and usage on the target database (ASM disk groups or ACFS file systems) and make sure adequate storage is provisioned and available on the target database servers.

- Check connections

  - Verify that ports 22 and 1521 (or the configured database listener port) on the target servers in the Oracle Cloud Infrastructure, Oracle Exadata Database Service on Dedicated Infrastructure, or Oracle Exadata Database Service on Cloud@Customer environment are open and not blocked by a firewall.

    An open connection is required from the Zero Downtime Migration host and the and source database server.

  - Verify that port 22 on the target database server allows incoming connections from the Zero Downtime Migration service host.

- Capture the output of the RMAN `SHOW ALL` command

  Capture output so that you can compare RMAN settings after the migration, then reset any changed RMAN configuration settings to ensure that the backup works without any issues.

      RMAN> show all;

### 4.5 Setting Up the Transparent Data Encryption Keystore

For Oracle Database 12c Release 2 and later, if the source and target databases do not have Transparent Data Encryption (TDE) enabled, then it is mandatory that you configure the TDE keystore before migration begins.

Note:

For Oracle Database 11.2 and 12.1 sources TDE wallet configuration is not required. If the source does not have a TDE wallet configured, any TDE configuration on the target is removed. After the migration, you must configure the TDE wallet at the target.

Note:

If you migrate Oracle Database 11.2 and 12.1 sources, for unencrypted sources, even when providing a TDE wallet (which is a requirement), ZDM will not be able to use ENCRYPT on RESTORE at the target database. This is applicable when you migrate and upgrade the CDB databases. You must perform any missing encryption tasks manually, post-migration.

TDE should be enabled and the `TDE WALLET` status on both source and target databases must be set to `OPEN`. The `WALLET_TYPE` can be `AUTOLOGIN`, for an auto-login keystore (preferred), or `PASSWORD`, for a password-based keystore. On a multitenant database, make sure that the keystore is open on all PDBs as well as the CDB, and that the master key is set for all PDBs and the CDB.

Note:

Ensure to open all the PDBs before running any of the commands described.

If TDE is not already configured as required on the source and target databases, use the following instructions to set up the TDE keystore.

Note:

When the source TDE wallet is configured with `LOCAL_AUTOLOGIN` single sign-on certificate, ZDM does not copy the single sign-on, because the `LOCAL_AUTOLOGIN` single sign-on certificates are only valid on the nodes for which they are generated. Instead, you must enter the TDE wallet password to generate the `AUTOLOGIN` certificate for the target nodes. So, when the source is using the `LOCAL_AUTOLOGIN` wallet, post migration the target will have `AUTOLOGIN` wallet. ZDM will not generate the `LOCAL_AUTOLOGIN` wallet.

Note:

When the source or the target database is using keystore location different from the `FILE` or `ASM` wallet, ZDM does not migrate the TDE keys. Ensure that the wallet keys at the source that are accessible from the target because, when the keystore is available not on file system keystore, the export, import, or migration of the keys need to be handled using keystore specific tools. ZDM cannot migrate the keys from keystores that are different from `FILE` or `ASM`.
ZDM encrypts *all* tablespaces for cases where TDE is mandatory for migrations involving backup/restore or direct migration using restore from service.

ZDM now uses a single restore statement with `encrypt on restore` for the entire database for targets which have Oracle Database 19c and later versions:

    RESTORE DATABASE AS ENCRYPTED AS ENCRYPTED FROM TAG 'ZDM_JOB_10';

Note:

This feature affects migrations that uses backup/restore or direct migration using restore from service. For migrations using ZDLRA or direct using active duplicate, ZDM does not perform any additional encryption, the encryption status on the target post restore is same as the source database.

For a password-based keystore, you only need to do steps 1, 2, and 4; for an auto-login keystore, complete all of the steps.

1. Set `ENCRYPTION_WALLET_LOCATION` in the `$ORACLE_HOME/network/admin/sqlnet.ora` file.

       /home/oracle>cat /u01/app/oracle/product/12.2.0.1/dbhome_4/network/admin/sqlnet.ora

       ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)
         (METHOD_DATA=(DIRECTORY=/u01/app/oracle/product/12.2.0.1/dbhome_4/network/admin/)))

   For an Oracle RAC instance, also set `ENCRYPTION_WALLET_LOCATION` in all the nodes.

2. Create and configure the keystore.

   1. Connect to the database and create the keystore.

          $ sqlplus "/as sysdba"
          SQL> ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin'
           identified by password;

   2. Open the keystore.

      For a non-CDB environment, run the following command.

          SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
          keystore altered.

      For a CDB environment, run the following command.

          SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password container = ALL;
          keystore altered.

   3. Create and activate the master encryption key.

      For a non-CDB environment, run the following command.

          SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password with backup;
          keystore altered.

      For a CDB environment, run the following command.

          SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password with backup container = ALL;
          keystore altered.

   4. Query `V$ENCRYPTION_KEYS` to get the keystore status, keystore type, and keystore location.

          SQL> SELECT * FROM v$encryption_keys;

          WRL_TYPE    WRL_PARAMETER
          --------------------            --------------------------------------------------------------------------------
          STATUS                         WALLET_TYPE          WALLET_OR FULLY_BAC    CON_ID
          ------------------------------ -------------------- --------- ---------            ----------
          FILE        /u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin/
          OPEN                           PASSWORD             SINGLE    NO         0

   The configuration of a password-based keystore is complete at this stage, and the keystore is enabled with status `OPEN` and `WALLET_TYPE` is shown as `PASSWORD` in the query output above.

   Continue to step 3 only if you need to configure an auto-login keystore, otherwise skip to step 4.

3. For an auto-login keystore only, complete the keystore configuration.

   1. Create the auto-login keystore.

          SQL> ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE
           '/u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin/' IDENTIFIED BY password;
          keystore altered.

   2. Close the password-based keystore.

          SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY password;
          keystore altered.

   3. Query `V$ENCRYPTION_WALLET` to get the keystore status, keystore type, and keystore location.

          SQL> SELECT * FROM v$encryption_wallet;
          WRL_TYPE WRL_PARAMETER
          -------------------- --------------------------------------------------------------------------------
          STATUS WALLET_TYPE WALLET_OR FULLY_BAC CON_ID
          ------------------------------ -------------------- --------- --------- ---------
          FILE /u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin/
          OPEN AUTOLOGIN SINGLE NO

      In the query output, verify that the TDE keystore `STATUS` is `OPEN` and `WALLET_TYPE` set to `AUTOLOGIN`, otherwise the auto-login keystore is not set up correctly.

      This completes the auto-login keystore configuration.

4. Copy the keystore files to the second Oracle RAC node.

   If you configured the keystore in a shared file system for Oracle RAC, or if you are enabling TDE for a single instance database, then no action is required.

   If you are enabling TDE for Oracle RAC database without shared access to the keystore, copy the following files to the same location on second node.

   - `/u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin/ew*`

   - `/u01/app/oracle/product/12.2.0.1/dbhome_2/network/admin/cw*`

Note:

ZDM can migrate all the wallet files and sub-directories configured under `WALLET_ROOT`. If the source has PDB wallets in isolated mode, ZDM migrates all of the wallet's files in sub-directories under `WALLET_ROOT`.

Handling TDE for the PDB clone: If the source PDB has encrypted data or a TDE master encryption key has been set, you must provide the target keystore password using the `-tgttdekeystorepasswd` CLI parameter. To setup TDE wallet, see How Configuring Transparent Data Encryption Works.

Related Topics

- Using Transparent Data Encryption
- Configuring a TDE Wallet

### 4.6 Using Supported Data Transfer Media

The Zero Downtime Migration physical migration process involves creating a backup of the source database and restoring it to the target database, or using and existing backup.

Oracle Cloud Infrastructure Object Storage

OCI Object Storage is supported as a backup medium when migrating a database to Oracle Cloud Infrastructure, Oracle Exadata Database Service on Dedicated Infrastructure, or any on-premises Oracle Exadata Database Service on Cloud@Customer target.

Zero Downtime Migration service either initiates the source database backup as part of the migration work flow, or you can specify an existing backup already in the Object Storage bucket, and Zero Downtime Migration restores it to the target environment, so Object Storage must be accessible from both the source and target environments.

The source database is backed up to the specified container and restored to the target using RMAN SQL*Net connectivity.

The Zero Downtime Migration service host uses an SSH connection to the source and target database servers to install and configure the backup module software necessary to back up to and restore from Object Storage. The backup from the source database to Object Storage takes place over an RMAN channel.

Make sure that the Object Storage bucket is created using the Oracle Cloud Service Console as appropriate.

Also, make sure adequate storage is provisioned and available on the object store to accommodate the source database backup.

Zero Data Loss Recovery Appliance

Zero Data Loss Recovery Appliance is supported as a backup medium for migrating a database to an Oracle Exadata Database Service on Cloud@Customer target or an Oracle Exadata Database Machine.

If Zero Data Loss Recovery Appliance is chosen as backup medium, then you must ensure that the Zero Data Loss Recovery Appliance has a valid backup of the source database, because Zero Downtime Migration does not initiate a backup to Zero Data Loss Recovery Appliance as part of the work flow.

You must also ensure that all instances of the database are up before initiating a backup to Zero Data Loss Recovery Appliance. The duplicate database operation might fail if the backup is initiated when an instance is down.

The Zero Downtime Migration service accesses the backup in Zero Data Loss Recovery Appliance and restores it to Oracle Exadata Database Service on Cloud@Customer. The Zero Data Loss Recovery Appliance access credentials and wallet location are mandatory input parameters, so that Zero Downtime Migration can handle the Zero Data Loss Recovery Appliance wallet setup at the target database.

Any transfer of redo stream between the source and the target database server, in either direction, takes place over a SQL*Net link.

Refer to the Zero Data Loss Recovery Appliance documentation for information about creating backups.

Network File System (NFS)

NFS is supported as a backup medium when migrating a database to an Oracle Exadata Database Service on Cloud@Customer target, or any on-premises Oracle Exadata Database Machine target.

If you choose to back up the database to an NFS mount, then the Zero Downtime Migration service initiates the source database backup (or you can specify a pre-existing backup) and restores it to the Exadata target environment. The NFS should be accessible from both the source and target environments.

The source database is backed up to the specified path and restored to Oracle Exadata Database Service on Cloud@Customer using RMAN SQL*Net connectivity.

When you perform a migration using offline migration through NFS, SQL*Net connectivity between the source and target are not needed.

Note:

For physical migration, NFS is supported for all the target types as long as the storage is shared between the source and the target databases. Also, `NFS` can be any shared file system, not only the network file system. Other shared file system such as ZFS should work as well.

### 4.7 Setting Physical Migration Parameters

Set the required physical migration response file parameters. Get the response file template, `$ZDM_HOME/rhp/zdm/template/zdm_template.rsp`, which is used to create your Zero Downtime Migration response file for the database migration procedure, and edit the file as described here.

Note:

Currently, only online physical migration is supported when DATA_TRANSFER_MEDIUM=DIRECT.
The following response file settings show you how to configure a typical use case. To further customize your configuration you can find additional parameters described in Zero Downtime Migration Physical Migration Response File Parameters Reference.

TGT_DB_UNIQUE_NAME

Set `TGT_DB_UNIQUE_NAME` to the target database `DB_UNIQUE_NAME` value. To find `DB_UNIQUE_NAME` run

    SQL> show parameter db_unique_name

For Cloud type Exadata Cloud at Customer Gen 1, set `TGT_DB_UNIQUE_NAME` to a different `DB_UNIQUE_NAME` not currently in use.

PLATFORM_TYPE

Set `PLATFORM_TYPE` to one of the following:

- `VMDB` - Oracle Cloud Infrastructure virtual machine or bare metal targets.

- `EXACC` - Oracle Exadata Database Service on Cloud@Customer, including Oracle Exadata Database Service on Exascale Infrastructure

- `EXACS` - Oracle Exadata Database Service on Dedicated Infrastructure, including Oracle Exadata Database Service on Exascale Infrastructure

- `NON_CLOUD` - On-premises Exadata Database Machine

MIGRATION_METHOD

Set `MIGRATION_METHOD` to one of the following:

- `ONLINE_PHYSICAL` - Oracle Data Guard (online)

- `OFFLINE_PHYSICAL` - RMAN backup and restore (offline). Note that this is the only migration method supported for Oracle Database Standard Edition 2.

DATA_TRANSFER_MEDIUM

`DATA_TRANSFER_MEDIUM` specifies the media used for the source database backup.

- `OSS` - Oracle Data Guard using Object Storage Service (OSS) for standby initialization.

  Supported for `PLATFORM_TYPE` set to Oracle Cloud Infrastructure (`VMDB`), Oracle Exadata Database Service on Dedicated Infrastructure(`EXACS`), and Oracle Exadata Database Service on Cloud@Customer (`EXACC`).

  Also set `ZDM_LOG_OSS_PAR_URL` to the Cloud Object Store pre-authenticated URL if you want to upload migration logs onto Cloud Object Storage. For information about getting a pre-authenticated URL see Oracle Cloud documentation at https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm#usingconsole.

  When you perform a migration using backup and restore (`OFFLINE_PHYSICAL`) through Object Storage Service, SQL*Net connectivity between the source and target are not needed.

  See Using Supported Data Transfer Media for more information about using OSS.

- `ZDLRA` - Oracle Data Guard using ZDLRA for standby initialization.

  Supported for `PLATFORM_TYPE` set to Oracle Exadata Database Service on Cloud@Customer (`EXACC`) or on-premises Exadata Database Machine (`NON_CLOUD`), and set the following parameters.

  - Set `SRC_ZDLRA_WALLET_LOC` for the wallet location, for example,

        SRC_ZDLRA_WALLET_LOC=/u02/app/oracle/product/12.1.0/dbhome_3/dbs/zdlra

  - Set `TGT_ZDLRA_WALLET_LOC` for the wallet location, for example, `TGT_ZDLRA_WALLET_LOC=target_database_oracle_home/dbs/zdlra`.

  - Set `ZDLRA_CRED_ALIAS` for the wallet credential alias, for example,

        ZDLRA_CRED_ALIAS=zdlra_scan:listener_port/zdlra9:dedicated

  See Using Supported Data Transfer Media for more information about using ZDLRA.

- `NFS` - Oracle Data Guard using backup location such as NFS.

  Supported for `PLATFORM_TYPE` set to Oracle Exadata Database Service on Cloud@Customer (`EXACC`) or on-premises Exadata Database Machine (`NON_CLOUD`).

  Also set `BACKUP_PATH` to specify the actual NFS path which is made accessible from both the source and target database servers, for example, an NFS mount point. The NFS mount path should be same for both source and target database servers. This path does not need to be mounted on the Zero Downtime Migration service host.

  Note the following considerations:

  - The path set in `BACKUP_PATH` should have 'rwx' permissions for the source database user, and at least read permissions for the target database user (either sharing a common Linux user ID or sharing a common Linux group with the source database user).

  - In the path specified by `BACKUP_PATH`, the Zero Downtime Migration backup procedure will create a directory, `$BACKUP_PATH/dbname`, and place the backup pieces in this directory.

  See Mount Options for Oracle files for RAC databases and Clusterware when used with NFS on NAS devices (Doc ID 359515.1)

  See Using Supported Data Transfer Media for more information about using NFS.

  Now ZDM supports multi mount point scenario for cross data center migrations where the source NFS is not accessible by the target database due to network limitations. ZDM allows different NFS mount point paths for both the source and the target databases.

  Set TGT_BACKUP_PATH to specify the target NFS path which is made accessible only from the target database server. To make the backup pieces available for the target database Zero Downtime Migration copies the files from the source NFS path (`$BACKUP_PATH/dbname`) into the target NFS path (`$TGT_BACKUP_PATH/dbname`). For the copy operation, you can specify the optional BACKUP_TRANSFERTARGET_* parameters:-
  - `BACKUP_TRANSFERTARGET_HOST`: Transfer node host. It defaults to the target node specified for the -targetnode CLI parameter if the property is not specified.
  - `BACKUP_TRANSFERTARGET_USER`: Transfer user that has write permission to the target NFS path. It defaults to the user specified for the target zdmauth plug-in if the property is not specified.
  - `BACKUP_TRANSFERTARGET_USERKEY`: Transfer authentication key. It defaults to the value specified for the `identity_file` argument of the target `zdmauth` plug-in.
  The backup pieces are copied in parallel using the Linux sftp utility by default. You can use the Linux rsync utility if it is available in both the source database and the target database by setting `BACKUP_RSYNC_AVAILABLE` to `TRUE`.
  Customize the parallel copy settings by specifying the next parameters:-
  - `BACKUP_NFS_PARALLEL_COUNT`: Maximum number of backup pieces to transfer to the transfer node in parallel.
  - `BACKUP_NFS_RETRY_COUNT`: Maximum number of times to retry the copy of a backup piece after a failure occurred.

  Note:

  -
  - The path set in BACKUP_PATH_TGT should have 'rwx' permissions for the transfer user.
  - The target database user should share a common group with the transfer user to be able to read the backup pieces.
  - The paths specified in both BACKUP_PATH and BACKUP_PATH_TGT can be different. In that case, Zero Downtime Migration will run the RMAN catalog.

- `DIRECT` - Uses RMAN active database duplication or restore from service to transfer data directly from the source to the target.

  The transfer method (restore from service or active duplicate) is configured with `ZDM_RMAN_DIRECT_METHOD`, which is set to `RESTORE_FROM_SERVICE` by default.

  ZDM uses the default service and only if you want to use a service other than the default service, then provide the `ZDM_SRC_DB_RESTORE_SERVICE_NAME` parameter.

  Note:

  Here, the source database is the primary source itself.

  See Using Direct Data Transfer for more information about direct data transfer, and see Using an Existing Standby to Instantiate the Target Database to directly transfer data from a standby.

- `EXTBACKUP` - Oracle Data Guard with existing backup in external location.

  Supported for `PLATFORM_TYPE` set to Oracle Exadata Database Service on Cloud@Customer (`EXACC`) or on-premises Exadata Database Machine (`NON_CLOUD`)

  See Using an Existing RMAN Backup as a Data Source for more information.

Additional Oracle Cloud Object Storage Settings

When `DATA_TRANSFER_MEDIUM=OSS`, set the following additional parameters to access Oracle Cloud Object Storage.

- Set `HOST` to the cloud storage REST endpoint URL.

  - For Oracle Cloud Infrastructure storage the typical value format is `HOST=https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/ObjectStorageNamespace`

    To find the Object Storage Namespace value, log in to the Cloud Console and select Menu, Administration, Tenancy Detail, and in the Object Storage Settings section find Value against entry Object Storage Namespace:

  - For Oracle Cloud Infrastructure Classic storage the typical value format is `HOST=https://acme.storage.oraclecloud.com/v1/Storage-tenancy name`

- Set the Object Storage bucket `OPC_CONTAINER` parameter.

  The bucket is also referred to as a container for Oracle Cloud Infrastructure Classic storage.

TGT_SSH_TUNNEL_PORT

If SSH tunneling is set up, set the `TGT_SSH_TUNNEL_PORT` parameter.

Data and Redo Locations

Zero Downtime Migration automatically discovers the location for `data`, `reco`, and `redo` (for non-Exadata systems) storage volumes from the specified target database. If you need to override the discovered values, specify the target database data files storage (ASM or ACFS) location using the appropriate set of parameters.

- ASM: `TGT_DATADG`, `TGT_REDODG`, and `TGT_RECODG`
- ACFS: `TGT_DATAACFS`, `TGT_REDOACFS`, and `TGT_RECOACFS`

SKIP_FALLBACK

Set `SKIP_FALLBACK=TRUE` if you do not want to ship redo logs from the target to the source standby, either voluntarily or because there is no connectivity between the target and the source.

TGT_SKIP_DATAPATCH

Zero Downtime Migration runs the datapatch utility by default as part of the migration process if the target database environment is at a higher patch level than the source database (for example, if the source database is at Jan 2020 PSU/BP and the target database is at April 2020 PSU/BP).

If you want to skip this task set the `TGT_SKIP_DATAPATCH=FALSE` response file parameter.

PHASE_NAME_MONITORING_INTERVAL

Set `PHASE_NAME_MONITORING_INTERVAL=n mins` if you want Zero Downtime Migration to monitor and report the status of backup and restore operations at the configured time interval during the migration. The default interval value is 10 minutes. To disable monitoring, set these values to 0 (zero).

    ZDM_BACKUP_FULL_SRC_MONITORING_INTERVAL=
    ZDM_BACKUP_INCREMENTAL_SRC_MONITORING_INTERVAL=
    ZDM_BACKUP_DIFFERENTIAL_SRC_MONITORING_INTERVAL=
    ZDM_CLONE_TGT_MONITORING_INTERVAL=
    ZDM_OSS_RESTORE_TGT_MONITORING_INTERVAL=
    ZDM_OSS_RECOVER_TGT_MONITORING_INTERVAL=

ZDM_BACKUP_RETENTION_WINDOW

Set `ZDM_BACKUP_RETENTION_WINDOW=number of days` if you wish to retain source database backup after the migration.

ZDM_SRC_TNS_ADMIN

Set `ZDM_SRC_TNS_ADMIN=TNS_ADMIN value` in case of custom location.

ZDM_APPLY_LAG_MONITORING_INTERVAL

Set `ZDM_APPLY_LAG_MONITORING_INTERVAL` = `{NONE | DAILY | WEEKLY}`, to monitor redo apply lag after standby database creation. This phase queries the current redo apply lag, and waits until redo apply is finished before resuming the job. See ZDM_APPLY_LAG_MONITORING_INTERVAL.

### 4.8 Using an Existing RMAN Backup as a Data Source

Zero Downtime Migration lets you use an existing level 0 backup to skip the full backup phase of a migration job.

This method is supported for Oracle Exadata Database Service on Cloud@Customer or on-premises Exadata Database Machine targets.

Zero Downtime Migration takes level 0 and level 1 backups on the fly for both online and offline physical migration jobs. During a migration job, Zero Downtime Migration lets you re-use existing source database backup in place of performing a full back up.

All types of backup devices, such as DISK, SBT_TAPE, and ZDLRA, are supported as data transfer media for this migration method.

Only level 0 backups with `incremental_level=0` are valid for this use case.

To use an existing RMAN backup, set the following response file parameters.

    ZDM_USE_EXISTING_BACKUP=TRUE
    ZDM_BACKUP_TAG=RMAN backup tag

Note:

For ZDLRA, you must bring up the pre-existing backup. However, skip the `ZDM_USE_EXISTING_BACKUP` parameter for ZDLRA.
When you run the ZDMCLI database migration command in evaluation mode (`ZDMCLI database migration -eval`), Zero Downtime Migration verifies the existence of the backup, checks that it is valid, and displays whether the backup is available and validated in the job output.

In migrate mode (`ZDMCLI database migration`), Zero Downtime Migration performs the same steps done in evaluation mode, then skips full backup and performs other backup operations like incremental and differential backup.

Creating a Backup

To take a valid RMAN backup to use as a migration source, you can run the following commands.

For DISK:

    RUN {
    ALLOCATE CHANNEL channel_name DEVICE TYPE DISK FORMAT 'directory_path/%d_backup_%U';
    ALTER SYSTEM ARCHIVE LOG CURRENT;
    BACKUP AS COMPRESSED BACKUPSET FORCE INCREMENTAL LEVEL 1 FOR RECOVER OF TAG 'backup_tag'
     DATABASE FORMAT 'directory_path/%d_backup_%U_DBF' SECTION SIZE 4G ;
    }

For SBT_TAPE:

    RUN {
    ALLOCATE CHANNEL channel_name DEVICE TYPE SBT FORMAT '%d_%I_%T-%s_%p'
     PARMS 'SBT_LIBRARY=path/libopc.so, SBT_PARMS=(OPC_PFILE=path/OPC/mzdm.conf)';
    ALTER SYSTEM ARCHIVE LOG CURRENT;
    BACKUP AS COMPRESSED BACKUPSET FORCE INCREMENTAL LEVEL 1 FOR RECOVER OF TAG 'backup_tag'
     DATABASE FORMAT '%d_%I_%T-%s_%p_DBF' SECTION SIZE 4G ;
    }

Creating a Standby Control File Backup

Also, create a standby control file backup in the specified path and provide read permissions to the backup pieces for the target database user. For example,

    RMAN> BACKUP CURRENT CONTROLFILE FOR STANDBY FORMAT 'BACKUP_PATH/lower_case_dbname/standby_ctl_%U';

Where `standby_ctl_%U` is a system-generated unique file name.

Alternate Use Case

If the `ZDM_BACKUP_TAG` value is provided and `ZDM_USE_EXISTING_BACKUP=FALSE` the Zero Downtime Migration will create a full backup with the provided tag.

Using Backups with Password Authentication

To use an existing backup with backup password authentication, you can specify the password using the `-backuppasswd password` option in the command `migrate database`.

You can also specify a backup wallet path by using `-backupwallet` in the command `migrate database`.

### 4.9 Using Direct Data Transfer

Zero Downtime Migration supports direct data transfer during a physical migration to avoid backing up the source database to an intermediate store such as Object Storage or NFS.

Active Database Duplication

RMAN active database duplication is supported in Oracle Database 11g (11.2) and later releases.

Restore From Service

RMAN restore from service is supported in Oracle Database 12g (12.1) and later releases. Oracle MAA best practices recommend using active duplication for Oracle Database 11.2 and using restore from service for Oracle Database 12.1 and later.

Because the connection is initiated from the target database host, both active duplication and restore from service direct transfer methods require SQL*Net connectivity from the target to the source database.

### 4.10 Using an Existing Standby to Instantiate the Target Database

To reduce the load on your primary database system, Zero Downtime Migration can use an existing standby database to instantiate the standby in the target environment in a physical migration.

This migration option is only available when you are using direct data transfer with RMAN restore from service.

Because Oracle Database 11.2 doesn't support RMAN restore from service, it is therefore not supported for migration from an existing standby.

In the previous versions of Zero Downtime Migration, it was required to create a standby control file backup. However, from the 21.4 version of Zero Downtime Migration, you do not require to create a standby control file backup.

Ensure Snapshot Control File is on Shared Storage

In an Oracle Real Application Clusters (Oracle RAC) environment, the snapshot control file location must be on a shared file system- that is, a storage that is accessible to all Oracle RAC instances or ASM.

The snapshot control file location in the RMAN configuration points to the non-shared location in the ORACLE_HOME/dbs/ directory by default.

In cases when data is transferred from a primary database, Zero Downtime Migration configures the snapshot file location, but for direct data transfer from the standby database, Zero Downtime Migration does not configure the location.

You must ensure that RMAN is configured correctly for direct data transfer from the standby.

The example RMAN commands in the following steps set the configuration for the location of the snapshot control file for your cluster database; therefore, ensure that the directory location is shared by all nodes that perform backups.

1. Configure the snapshot control file on one node of source primary database, as shown in this example.

       RMAN> CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/dbhome2_prim/snapcf_dbhome21.f';

       new RMAN configuration parameters:
       CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/dbhome2_prim/snapcf_dbhome21.f';
       new RMAN configuration parameters are successfully stored

       RMAN> show SNAPSHOT CONTROLFILE NAME;

       RMAN configuration parameters for database with db_unique_name DBHOME2_PRIM
       are:
       CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/dbhome2_prim/snapcf_dbhome21.f';

2. Configure the snapshot control file on one node of the source standby database, as shown in this example.

       RMAN> CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/DBHOME2_STBY/snapcf_dbhome21.f';

       new RMAN configuration parameters:
       CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/DBHOME2_STBY/snapcf_dbhome21.f';
       new RMAN configuration parameters are successfully stored

       RMAN> show SNAPSHOT CONTROLFILE NAME;

       RMAN configuration parameters for database with db_unique_name DBHOME2_STBY
       are:
       CONFIGURE SNAPSHOT CONTROLFILE NAME TO
       '+ASM_STBM000038VM5/DBHOME2_STBY/snapcf_dbhome21.f';

Enable Target Database Instantiation from the Standby

To request instantiation of the target database from an existing standby, set the following parameters in the physical migration response file.

`ZDM_USE_EXISTING_STANDBY = TRUE` (default FALSE)

`ZDM_STANDBY_DB_CONNECT_STRING=connection string to access existing standby` (optional)

Keeping Source and Target in Sync

Once the target database is instantiated it is kept in sync by registering with the primary and applying archive redo logs shipped from primary.

Set the following parameters ZDM_USE_EXISTING_STANDBY = TRUE (default FALSE) and ZDM_STANDBY_DB_CONNECT_STRING=connection string to access existing standby (optional). If you want to use the existing standby option, then skip the ZDM_SRC_DB_RESTORE_SERVICE_NAME parameter as that is for the source database. By default, ZDM tries to infer the standby database connect string from the Data Guard configuration and you can specify ZDM_STANDBY_DB_CONNECT_STRING to override ZDM's standby database connect string discovery.

Existing Oracle Data Guard Broker Configuration Using TNS Aliases

ZDM also supports a standby database with an existing Data Guard Broker configuration using TNS aliases. During the migration, ZDM exports the TNS aliases from the existing configuration and imports only the non-existing ones into the target database by performing the following steps:-

1. Searches the TNS aliases from the existing Data Guard Broker configuration (ZDM_SETUP_SRC phase).
2. Setups non-existing TNS aliases at all target database instances (ZDM_SETUP_TGT phase).

### 4.11 Preparing for Automatic Application Switchover

To minimize or eliminate service interruptions on the application after you complete the database migration and switchover, prepare your application to automatically switch over connections from the source database to the target database.

Note:

In physical migrations, Autonomous Database targets are not supported for automatic application switchover.

In the following example connect string, the application connects to the source database, and when it is not available the connection is switched over to the target database.

    (DESCRIPTION=
        (FAILOVER=on)(LOAD_BALANCE=on)(CONNECT_TIMEOUT=3)(RETRY_COUNT=3)
        (ADDRESS_LIST=
            (ADDRESS=(PROTOCOL=TCP)(HOST=source_database_scan)(PORT=1521))
            (ADDRESS=(PROTOCOL=TCP)(HOST=target_database_scan)(PORT=1521)))
        (CONNECT_DATA=(SERVICE_NAME=zdm_prod_svc)))

On the source database, create the service, named zdm_prod_svc in the examples.

    srvctl add service -db clever -service zdm_prod_svc -role PRIMARY
     -notification TRUE -session_state dynamic -failovertype transaction
     -failovermethod basic -commit_outcome TRUE -failoverretry 30 -failoverdelay 10
     -replay_init_time 900 -clbgoal SHORT -rlbgoal SERVICE_TIME -preferred clever1,clever2
     -retention 3600 -verbose

If the `db_domain` changes between the source and target then the connect string specified in the application should cater to both for failover to be effective.

    (DESCRIPTION_LIST=
                (FAILOVER=ON)
                (LOAD_BALANCE=ON)
                (DESCRIPTION=
                (ADDRESS= (PROTOCOL=TCP) (HOST=SRC_SCAN) (PORT=1521))
                (CONNECT_DATA=
                (SERVICE_NAME=SVC.SRC_DOMAIN)))
                (DESCRIPTION=
                (ADDRESS= (PROTOCOL=TCP) (HOST=TGT_SCAN) (PORT=1521))
                (CONNECT_DATA=
                (SERVICE_NAME= SVC.TGT_DOMAIN))

See Also:

Oracle MAA white papers about client failover best practices on the MAA Best Practices - Oracle Database page at https://www.oracle.com/goto/maa.

High Availability in Oracle AI Database Development Guide

### 4.12 Using Oracle Data Guard Broker Role Switchover

In physical migrations, Zero Downtime Migration can leverage the Oracle Data Guard broker to manage database role switchover.

Typically, the Zero Downtime Migration service manages database role switchover after the data migration is complete. You can alternatively enable an option that lets the broker handle the switchover.

The Data Guard Broker is a feature of Data Guard, which is available via the online migration workflow. The Data Guard broker is a distributed management framework that automates the creation, maintenance, and monitoring of Data Guard configurations. You can use a Data Guard broker configuration to improve usability and centralize management and monitoring of the Oracle Data Guard configuration. Using the broker helps not only to set up replication, but also performs gap detection, switchover, and switchback operations.

Note:

Currently, ZDM broker enabled migrations from single instances is only supported if the source environment has an existing Data Guard broker enabled configuration. All the Oracle RAC sources are supported. If you want to migrate a single instance database with no active Data Guard Broker configuration, proceed to migrate with ZDM without the Data Guard Broker.

Prerequisites

Broker-managed role switchovers require two-way SQL*Net connectivity.

Note that broker configuration is not supported for Oracle Database 11.2.0.4.

Enabling Broker Database Role Switchover

You can enable or disable the broker-managed role switchover option using the `ZDM_USE_DG_BROKER` response file parameter.

`ZDM_USE_DG_BROKER = TRUE | FALSE`

`ZDM_USE_DG_BROKER` is set to `FALSE` by default, meaning that the broker does not handle the switchover.

Broker Option Validation

When the broker-managed switchover option is enabled, Zero Downtime Migration verifies that the source primary database has no existing standby that is not broker-managed. This check is done because the broker configuration cannot co-exist with a non-broker managed standby.

With the broker option enabled, in cases when the primary (source) database does not have an existing standby, or has a standby that is already managed by the broker, Zero Downtime Migration creates a broker configuration to manage the target (Data Guard standby) database.

### 4.13 Configuring Resiliency to Intermittent Network Failures

Zero Downtime Migration physical migrations are resilient to intermittent network failures that can cause backups or SSH connectivity to fail.

Zero Downtime Migration can auto-detect intermittent network failures. Zero Downtime Migration automatically retries the RMAN retry-able errors, and some retry customization is available.

SSH connection retries are customized using the following parameters:

`SRC_SSH_RETRY_TIMEOUT`

`TGT_SSH_RETRY_TIMEOUT`

You can customize RMAN backup retries with following parameters:

`ZDM_OPC_RETRY_WAIT_TIME`

`ZDM_OPC_RETRY_COUNT`

`ZDM_OPC_RETRY_WAIT_TIME`

### 4.14 Converting a Non-CDB Database to a CDB During Migration

As part of the physical migration process, Zero Downtime Migration can handle conversion of a non-CDB source database to a PDB of the same version in the cloud. The conversion process transforms the source non-CDB into a target PDB that is then plugged into an existing CDB in the target.

Downtime will increase due to the non-CDB to CDB conversion. This process is offline (no redo transport and apply), and no rollback is possible.

ZDM physical migration allows the conversion between Non-CDB sources and PDB targets. Define the name of the target PDB before starting the migration with the `ZDM_NONCDBTOPDB_PDB_NAME` response file parameter.

Note:

For the conversion use case, when a non-CDB source database is being migrated to a target CDB database as a PDB, if the target database has a standby configured, then the unplug or plug process does not replicate the PDB database to the target standby database. To migrate the new PDB, either you need to rebuild the standby or you need to replicate the PDB. Refer to this MOS note for the steps for replicating the PDB to standby.

Source non-CDB Database Prerequisites

- Oracle Database 12c or later versions, because this is when multitenant architecture became available

- Same character set as the target CDB

Target Database CDB and PDB Prerequisites

- The target CDB must not contain a PDB with same name as the resulting converted PDB, because Zero Downtime Migration will create the PDB.

- The target database must be at least the same major version as the source database.

  - If the minor version is different on the target, it must be a higher minor version than the source database.
  - If the patch level is different, you must set the response file parameter `TGT_SKIP_DATAPATCH=FALSE`.
- Ensure that the target CDB database has sufficient resources such as memory and CPU, to accommodate migrating a non-CDB database and converting to a PDB, that is plugged into the target CDB database.

Transparent Data Encryption Requirements

- For source credentials, the `migrate database` command must include either `-tdekeystorepasswd` or the `-tdekeystorewallet` auto-login option.

- If any of these options is used then the target credentials must be also provided by using either `-tgttdekeystorepasswd` or the `-tgttdekeystorewallet` auto-login option.

Application Express Requirements

- If Application Express (APEX) is not installed on the source there are no further requirements.

- If APEX exists on the source, and the source database is a non-CDB, you must choose one of the following options:

  - Remove APEX from the source non-CDB.
  - Verify that the APEX version on the target CDB is the same as that on the source.

    If APEX is not at the same version conversion is not possible; APEX schemas vary between versions and the target PDB will not be able to open.

The target CDB is not dropped in the process, and the presence or absence of other PDBs does not affect the outcome of the conversion and plug-in.

Parameters in the response file are set as follows:

- (Required) `NONCDBTOPDB_CONVERSION`: Set to `TRUE` to indicate that you want to convert a source database from non-CDB to PDB.
- (Optional) `NONCDBTOPDB_SWITCHOVER`: Set to `TRUE` for a physical migration using Data Guard switchover, to execute switchover operations during a migration job with non-CDB to PDB conversion enabled.

Note:

Ensure that the `AUX` name (PDB name) that you specify in the response file does not overlap with the target `db_name`, `db_unqiue name`, and any target `SID` names. ZDM assumes the `SID` name for `AUX` as `<AUX_NAME>1`, as well as `<AUX_NAME>` and if either of those overlap with the target `db_name`, `db_unqiue name`, or target `SIDs`, that can cause an issue. You can also run the `-eval` option. Ensure that the AUX name is kept to 11 or fewer characters to ensure that SID does not exceed 12 characters.

The following are examples of the ZDMCLI `migrate database` command usage for converting a non-CDB to a PDB during migration using the TDE credentials.

Example interactively supplying passwords:

    zdmuser> $ZDM_HOME/bin/zdmcli migrate database
      -sourcedb source_db_unique_name_value
      -sourcenode source_database_server_name
      -srcroot
      -targetnode target_database_server_name
      -backupuser Object_store_login_user_name
      -rsp response_file_location
      -tgtauth zdmauth
      -tgtarg1 user:target_database_server_login_user_name
      -tgtarg2 identity_file:ZDM_installed_user_private_key_file_location
      -tgtarg3 sudo_location:/user/bin/sudo
      -tdekeystorepasswd
      -tgttdekeystorepasswd

Example using auto-login wallet for CDB TDE keystore:

    zdmuser> $ZDM_HOME/bin/zdmcli migrate database
      -sourcedb source_db_unique_name_value
      -sourcenode source_database_server_name
      -srcroot
      -targetnode target_database_server_name
      -backupuser Object_store_login_user_name
      -rsp response_file_location
      -tgtauth zdmauth
      -tgtarg1 user:target_database_server_login_user_name
      -tgtarg2 identity_file:ZDM_installed_user_private_key_file_location
      -tgtarg3 sudo_location:/user/bin/sudo
      -tdekeystorepasswd
      -tgttdekeystorewallet /scratch/credentials/cdbtde.sso

### 4.15 Migrating an On-Premises Database to an On-Premises Exadata Database Machine

An on-premises migration to an on-premises Exadata Database Machine target using Zero Downtime Migration works the same way as a migration to a cloud target. In the response file, you indicate that the migration target is on-premises by setting `PLATFORM_TYPE=NON_CLOUD`.

Just like in cloud migration scenarios, you must provision the target database with the shape and size desired, including configuring any initialization parameters, before starting the migration. The target database is expected to be the same major version as the source database, Oracle Grid Infrastructure is mandatory at the target database, and target datafiles can be stored on ASM or ACFS.

One aspect where an on-premises to on-premises migration is different from migrating to the cloud is in the handling of Transparent Data Encryption (TDE). On the cloud, TDE is mandatory for Oracle Database 12.2 and later releases; however, for an on-premises to on-premises migration, TDE must be configured at the target only if TDE is used at the source. You must configure TDE at the target before the migration starts; Zero Downtime Migration does not configure it for you.

You can specify that TDE is not configured at the source or target by setting the response file parameter `ZDM_TDE_MANDATORY=FALSE`. This parameter can only be used when you set `PLATFORM_TYPE=NON_CLOUD`. With `ZDM_TDE_MANDATORY=FALSE` set, Zero Downtime Migration does not require TDE at the target when the source is not using TDE, and does not encrypt the target on restore.

For an on-premises Exadata target database migration, `MIGRATION_METHOD` can be set to `ONLINE_PHYSICAL` or `OFFLINE_PHYSICAL`, and `DATA_TRANSFER_MEDIUM` can be set to any of the values supported by Zero Downtime Migration. Set the remaining parameters as you would for a cloud migration.

### 4.16 Creating an Oracle Cloud Native Disaster Recovery Strategy

In a typical migration, ZDM migrates a source database to only one target database (single point of failure). Now you can create a DR (Disaster Recovery) strategy during post-migration to be able to respond to and recover from an event that negatively affects your business operations.

Two target databases are instantiated during the migration (target primary database and target standby database), where both can be in different regions (to reduce impacts of natural disasters). During post-migration, Oracle Data Guard Broker configuration is restored in both target databases to allow cloud native operations like switchover and failover (in the Oracle Database Cloud Service console).

Prerequisites:

1. Instantiate both target database and target standby database before beginning the migration process. These environments are assumed to be configured using Data Guard (DG) Broker.
   - When ExaCS/ExaCC is used for platform_type, this can be done using DG Associations (in the Oracle Database Cloud Service console).
   - For VMDB platform_type, the configuration can be done (manually) using DGMGRL Oracle Data Guard Broker CLI tool.
2. Supported migration methods: Only online migrations are supported (where Oracle Data Guard is used).
3. Supported data transfer methods: OSS, ZDLRA, Direct.
4. Supported Platform type: ExaCS, ExaCC, VMDB (ZDLRA is not supported).
5. Set the parameters in the response file as follows:

   Required:

   - Set TGT_STBY_NODE to the target standby database IP address to indicate that you want to configure a DR strategy on post-migration.
   - TGT_STBY_DB_UNIQUE_NAME: can identify the target standby as a different database from both the source database and the target database.
   - For connectivity to the target standby database, set TGT_STBY_AUTH= `zdmauth` and configure TGT_STBY_SUDO_USER (target_standby_database_server_login_user_name),TGT_STBY_IDENTITY_FILE (ZDM_installed_user_private_key_file_location), and TGT_STBY_SUDO_PATH (sudo_path).

   Optional:

   - To keep the target standby database in sync during the migration, set ZDM_TGT_STBY_CASCADING to `TRUE` (default value) to allow redo log shipping from the target database or set to `FALSE` to allow the redo log shipping from the source database (primary).
   - Set TGT_STBY_ZDLRA_WALLET_LOC if you want to use ZDLRA as the data transfer medium.

   Note:

   This use case is only supported for Non-CDB to Non-CDB migrations and for CDB to CDB migrations, migrations that require conversion are not currently supported.

When migrating NON-CDB to PDB using regular migration, it will get plugged into the target CDB. The target CDB can be setup to have a DR setup (for example using Oracle Data Guard Association in the console) of its own and when the NON-CDB is plugged into the target CDB, it would be replicated via the target CDB.

For DR migrations using ZDM, the source database will not be added (during post migration) to the OCI Oracle Data Guard Broker Configuration so it won't be managed by the OCI Console. However, the source database will still continue to receive the redo logs from the target database after the switchover.

### 4.17 Migration and Upgrade of CDB Databases

ZDM performs migration of a CDB database to a CDB database and later upgrades the target CDB database to a version of `ORACLE_HOME` provided in the `ZDM_UPGRADE_TARGET_HOME` parameter.

ZDM supports migration and upgrade of CDB for the target environment VMDB (Oracle Base Database Service) using `dbcli` utility. For other target environments apart from Oracle Base Database Service, Oracle Exadata Database Service on Dedicated Infrastructure, and Oracle Exadata Database Service on Cloud@Customer, ZDM uses autoupgrade to perform upgrade of CDB.

ZDM supports migration and upgrade of CDB for Oracle Exadata Database Service on Dedicated Infrastructure and Oracle Exadata Database Service on Cloud@Customer target environment using the `dbaascli` utility.

Note:

For VMDB/EXACC/EXACS CDB upgrade target auth plugin, dbuser, and sudoasuser are not supported. Only zdmauth is the supported plugin in this scenario.

Note:

You must ensure that the source database has TDE configured and you provide the wallet details, this ensures that post the migration and upgrade, the Oracle Database 19c target database has TDE configured. For upgrade and migrate scenario, TDE is mandatory for all releases. This is mandatory for all source versions, including Oracle Database 11.2 and Oracle Database 12.1. TDE is mandatory in the Oracle Cloud, for Oracle Database 12.2 and higher versions. For more information, see Setting Up the Transparent Data Encryption Keystore.

Note:

Currently, for Oracle Base Database Service, when you provision an Oracle Database 19c, the GI provisioned is also of the same version Oracle Database 19c. Currently, it is not possible to upgrade the Oracle Grid Infrastructure 19c to Oracle Grid Infrastructure 26ai either. So effectively, it is currently not possible to install an Oracle AI Database 26ai database on the VMDB system initially created with Oracle Database 19c/GI. So, for the migration and upgrade scenario, provision the database version at the same version as source and provide an additional database version running at a higher version.

Autoupgrade is used only for non_cloud targets. For all cloud platforms such as Oracle Exadata Database Service on Dedicated Infrastructure, Oracle Exadata Database Service on Cloud@Customer as well as Oracle Base Database Service, cloud tooling is used for upgrade. For Oracle Exadata Database Service on Dedicated Infrastructure and Oracle Exadata Database Service on Cloud@Customer `dbaascli` is used and `dbcli` for Oracle Base Database Service.

As a prerequisite, provision ORACLE_HOME in Oracle Base Database Service, Oracle Exadata Database Service on Dedicated Infrastructure, and Oracle Exadata Database Service on Cloud@Customer environments as follows:

- Provision ORACLE_HOME in VMDB using the following command:
  `/opt/oracle/dcs/bin/dbcli create-dbhome -v <supported db version>`

  Note:

  For the use cases that do not involve Non-CDB to PDB conversion, the provisioned target database must be of the same version as the source database.
- Provision ORACLE_HOME in EXACC/EXACS using console or by using the following command:

  `dbaascli dbhome create --version <supported_version>`

The upgrade starts after the completion of migration. Perform the following steps:

1. Select the same version of the source and the target CDB.
2. Provision the `ORACLE_HOME` to the version you want to upgrade in the target database.
3. Provide the path of the provisioned `ORACLE_HOME` in the `ZDM_UPGRADE_TARGET_HOME` parameter.

For migrate+upgrade scenario, not involving conversion to PDB, ZDM will migrate the source database as is to the target. You can use any of the existing migration method, offline/online for this. Once the database is running in the target, ZDM uses the cloud platform tooling or autoupgrade to upgrade the database.

### 4.18 Migration, Upgrade, and Conversion of a Non-CDB to a PDB Database

In a single migration job, ZDM can migrate a non-CDB database to the target environment, upgrade the database to a PDB, and then plug in the upgraded PDB into the provided target CDB.

ZDM supports migration and plug in of a non-CDB source database to a higher version target database using `autoupgrade.jar` to perform upgrade precheck, fixups and upgrade+plug operation. For example, the source non-CDB database could be of version Oracle Database 12.1 and target database could be a CDB of version Oracle Database 19c.

Note:

For the upgrade of Non-CDB database, Oracle Database 11g Release 2 (11.2.0.4) , `catbundle.sql` is required. ZDM validates in the target database, the `catbundle.sql` location for the upgrade scenario of Oracle Database 11g Release 2 (11.2.0.4) database.

The following inputs are required for this type of migration:

1. The source database is a non-CDB, presumably at a lower release than target CDB (for example 12.1)
2. A CDB on the target host at the desired database version (for example, 19c).
3. A database `ORACLE_HOME` of the same major version as the current source non-CDB version located on the target host.

   This home is used by ZDM to create an auxiliary Non-CDB database that is used during the migration process.

   Set the `ZDM_PRE_UPGRADE_TARGET_HOME` response file parameter to the path of this `ORACLE_HOME`.

For migrate+upgrade+conversion use case, ZDM will first migrate non-CDB as non-CDB database to target. Initially non-CDB will be migrated as an auxiliary staging database using any of the existing migration methods offline or online. The auxiliary will be running at the same version as source. ZDM does need an additional home at the same version as the source to migrate and stage the non-CDB first. Once the database is running on the target, ZDM will use AutoUpgrade to unplug or plug and upgrade non-CDB into 19c CDB target. Additionally, unplug or plug and/or upgrade, is an offline operation, meaning these operations involve additional downtime. If an online method was used for migrating the data, ZDM will first disconnect the target and source database before proceeding to unplug/plug and/or upgrade phase.

### 4.19 Using External Keystores

When the TDE keys are on external keystore, then you must migrate the keys on your own.

Ensure proper installation, password configuration, and communication setup for seamless operation.

Work with your external keystore vendor for detailed configuration steps. The details outlined below provides a high-level overview of the generic steps required to configure an external keystore.

External Keystore Server Installation: You are responsible for installing and configuring the external keystore server using the documentation provided by the vendor.

External Keystore Password Format: The format of the external keystore password varies depending on the provider.

Network Configuration: Ensure that a connection is established between the Guest VM and the external keystore server by: -

- Setting up the required network.
- Opening the necessary ports.
- Enabling the protocol specified by the external keystore vendor.

PKCS#11 Library Installation: Install the PKCS#11-related software and configure the PKCS#11 library on the VMs according to the external keystore vendor's documentation.

Communication Validation: Verify that the PKCS#11 library can successfully communicate with the external keystore.

Note:

The cloud automation does not perform prechecks to validate this connection. If the key is inaccessible, the database will return an error with the relevant details.

You must migrate the encryption keys on the external keystore and then set the ZDM_SKIP_TDE_WALLET_MIGRATION=TRUE parameter in the RSP file to skip the ZDM TDE Wallet migration.

ZDM supports automatic keystore migration if the source or target are configured with OKV (Oracle Key Vault) external keystore. For more information, see Migrating Source Database with OKV Keystore Configured as an External Keystore.

#### 4.19.1 Migrating Source Database with OKV Keystore Configured as an External Keystore

ZDM performs migration of external keystore wallets if the source or target database are configured to use OKV (Oracle Key Vault) external keystore.

There are four supported scenarios when migrating a wallet with ZDM:

- Source database with OKV wallet to Target database with OKV wallet
- Source database with OKV wallet to Target database with File wallet.
- Source database with File wallet to Target database with OKV wallet
- Source database with File wallet to Target database with File wallet.

You can migrate a source database configured with or without an OKV wallet to a target database configured with or without an OKV wallet. Currently, ZDM allows migrating databases that use the file TDE wallets and also it allows migrations where the wallet is not transferred during the ZDM workflow.

Note:

ZDM does not provision the OKV wallet on the endpoints. You must configure and provision the OKV wallet on all endpoints.

ZDM identifies whether the source database is configured to use OKV wallet and it will download the keys from the OKV wallet to then migrate them to the target database. If the target database is also configured with OKV wallet, ZDM will upload the keys to the OKV wallet. Do not change the default value of ZDM_SKIP_TDE_WALLET_MIGRATION parameter to allow ZDM to migrate the OKV wallet.

As prerequisite, the `$OKV_HOME` location should be inside the `wallet_root` folder, pointing to `<wallet_root>/okv`. If the `$OKV_HOME` location is in a different folder, you can set the ZDM_SRC_DB_OKV_HOME and ZDM_TGT_DB_OKV_HOME parameters in the RSP file to specify `$OKV_HOME` for the respective source and target database. ZDM will validate that `$OKV_HOME` contains the `bin/okvutil` utility for downloading and uploading the OKV wallets.

There are two options to specify the OKV endpoint passwords to the ZDM migration job:

- If OKV endpoint password and the TDE wallet password are different, provide the `-okvkeystorepasswd` input parameter to specify the OKV endpoint password in the source DB or provide the -tgtokvkeystorepasswd input parameter to specify the OKV endpoint password in the target DB.
- If OKV endpoint password and the TDE wallet password are the same, provide the -`tdekeystorepasswd` input parameter to specify the OKV endpoint password in the source DB or provide the -`tgttdekeystorepasswd` input parameter to specify the OKV endpoint password in the target DB.

ZDM will download or upload the keys from/to the default OKV wallet configured for the endpoint. If you need to download the wallet from a non-default wallet, provide the ZDM_SRC_DB_OKV_VIRTUAL_WALLET_NAME parameter in the RSP file to specify the correct OKV wallet from which ZDM will download the keys.

If you need to upload the keys to a wallet other than the default, provide the ZDM_TGT_DB_OKV_VIRTUAL_WALLET_NAME parameter in the RSP file to specify the correct OKV wallet where ZDM will upload the keys.

OKV: Oracle Key vault is a full-stack, security-hardened software appliance built to centralize the management of keys and security objects within the enterprise.

### 4.20 Migration Using PDB Clone

You can migrate an Oracle database using Pluggable Database (PDB) cloning in a streamlined approach that leverages Oracle's multi-tenant architecture. This method involves cloning either a PDB from a source CDB or a non-CDB into a target CDB, where the target PDB can be refreshed periodically to keep it up-to-date, allowing for a flexible and efficient migration process. Depending on the allowed downtime, you can select one of the three PDB clone methods.

Note:

Refreshable PDB using switchover requires matching credentials and database link.
You can either use the steps listed in Migration, Upgrade, and Conversion of a Non-CDB to a PDB Database or refer to the Migration Using PDB Clone.

Select the first option if you have larger databases and it uses RMAN method for backup and restore.

However, you can select the second option as you can migrate a single container at once over DBLINK. The following two options are two available:

- Offline PDB clone methods create a point-in-time PDB copy of a source PDB. Set `MIGRATION_METHOD=OFFLINE_PHYSICAL` to use any of the offline PDB clone methods:
  - Cold Clone PDB
    - Best for backups or when a precise point-in-time is needed and no source database activity is required.
    - The PDB must be in read-only mode.
    - Oracle Database 12.1.0.2 or higher is required.
    - Set `ZDM_PDB_CLONE_METHOD=COLD` to use this method.
  - Hot Clone PDB
    - The source and target platforms must share the same endianness.
    - Requires both source CDB and target CDB to be in ARCHIVELOG mode and have LOCAL UNDO enabled.
    - The database options on the source platform must either match or be a subset of those on the target platform.
    - Creates up-to-date copy of a PDB without stopping user activity.
    - The source PDBs can remain in read-write mode during the cloning.
    - Oracle Database 12.2 or higher is required.
    - Set `ZDM_PDB_CLONE_METHOD=HOT` to use this method.

  Note:

  A database link is required at the target CDB pointing to the source PDB or to the non-CDB for the cloning (created automatically by ZDM).
- Online PDB Clone method creates a PDB copy that can be continuously updated with redo data from the source PDB or from the source non-CDB. Set `MIGRATION_METHOD=ONLINE_PHYSICAL` to use the online PDB clone method:
  Refreshable PDB clone:
  - The source and target platforms must share the same endianness.
  - Requires both source CDB and target CDB to be in ARCHIVELOG mode and have LOCAL UNDO enabled.
  - The database options on the source platform must either match or be a subset of those on the target platform.
  - Provides near-real-time replica of a source PDB that can be automatically updated.
  - Requires source PDB to be in read-write mode.
  - Oracle Database 12.2 or higher is required.
  - Set `ZDM_PDB_CLONE_METHOD=REFRESHABLE` to use this method.
  - The refresh interval can set using `ZDM_PDB_REFRESH_INTERVAL=<interval in minutes>`. By default, the refresh interval is 60 minutes.
  - A database link is required at the target CDB pointing either to the source PDB or to the non-CDB for the cloning (created automatically by ZDM).
  - PDB switchover is also supported from Oracle Database 18c. You can enable it by setting `ZDM_SWITCHOVER=TRUE`.

  Note:

  Key considerations for Refreshable PDB clone using switchover:

  - Oracle Database 18c or higher is required.
  - A Secure External Password Store (SEPS) wallet is required at the source CDB. See the Setting up the SEPS Wallet section for information about SEPS wallet setup.
  - A database link is required at the source CDB pointing to the target CDB. The source database link name must share the same name and credentials with the target CDB database link. Both the database links are created automatically by ZDM.

  All the supported PDB clone methods use a database link to copy the database files during the cloning. For any PDB clone method set DATA_TRANSFER_MEDIUM=DBLINK.

  Once the PDB clone method has been selected, you must specify both the source and the target PDB names:

  - `ZDM_SRC_PDB_NAME`: Name of the source PDB. For non-CDB, leave this parameter blank.
  - `ZDM_TGT_PDB_NAME`: Name of the new target PDB to be cloned.

A new phase `ZDM_CLONE_PDB_TGT` is also introduced for this functionality along with the following new parameter: `ZDM_PDB_CLONE_METHOD`.

By default, ZDM creates a database link at the target CDB pointing to the source database using TCP protocol. Provide an existing database link by setting the `ZDM_TGT_DBLINK_NAME=<name of the existing database link>` parameter.

ZDM also creates the credentials used by the database link. For Hot, Cold and Refreshable PDB clone methods, the user is created at the source PDB or at the non-CDB. For Refreshable PDB clone method using switchover, a common user is created at the source CDB or a regular user is created at the non-CDB.

Provide the existing credentials to be used by the database link created by ZDM.

`ZDM_TGT_DBLINK_USERNAME=<database username>`

`ZDM_TGT_DBLINK_PASSWORD_WALLET=<absolute path of the wallet containing the password>`

For Refreshable PDB clone method using switchover, by default ZDM creates a second database link at the source CDB pointing to the target CDB. When you enter an existing database link for the target database and if there is no matching database link for the source database then the credentials are required for ZDM to create the second database link. Database link credentials are provided using the ZDM_TGT_DBLINK_USERNAME and ZDM_TGT_DBLINK_PASSWORD_WALLET parameters.

Database user creation for Cold, Hot, and Refreshable PDB clone methods:

    ALTER SESSION SET CONTAINER = <source_pdb>;
    CREATE USER <pdb_clone_user> IDENTIFIED BY <secure_password>;
    GRANT CREATE SESSION, SET CONTAINER, CREATE PLUGGABLE DATABASE TO <pdb_clone_user>;

Database user creation for Refreshable PDB clone method using switchover:

    CREATE USER c##<pdb_clone_user> IDENTIFIED BY <secure_password>;
    GRANT CREATE SESSION, RESOURCE, CREATE ANY TABLE, UNLIMITED TABLESPACE, CREATE PLUGGABLE DATABASE, SYSOPER TO c##<pdb_clone_user>;

Database link creation:

    CREATE DATABASE LINK ZDM_DBLINK CONNECT TO <pdb_clone_user> IDENTIFIED BY <secure_password> USING '<TNS alias pointing to the database>';
    SELECT count(*) FROM dual@ZDM_DBLINK;

Key considerations:

- Source database: The PDB clone can be either from a PDB or from a non-CDB. When the source database is a non-CDB, ZDM automatically handles the non-CDB to PDB conversion.
- Database version: The source database version can be lower than the target CDB version. When direct upgrade is supported between the source database and the target CDB, ZDM automatically handles the PDB upgrade by leveraging Oracle AutoUpgrade Tool. See the Table 2 to check if direct upgrade is supported by your specific scenario. If direct upgrade is not supported for your source database release and the required target CDB release, you can upgrade to an intermediate database release that is supported for direct upgrade.
- Character sets: If the character set of the CDB to which the PDB is being cloned is not `AL32UTF8`, then the source and target must have compatible character sets and national character sets.
- If the source PDB has encrypted data or a TDE master encryption key has been set, you must provide the target keystore password using the `-tgttdekeystorepasswd` CLI parameter.

Note:

ZDM re-keys the master encryption key of the cloned PDB during the `ZDM_POST_DATABASE_OPEN_TGT` phase as it will eventually follow its own course and have its own data and security policies.

Note:

PDB clone method represents an alternative method to the unplug or plug method (already supported by ZDM) for non-CDB to PDB migration.
Comparison between PDB clone methods

Clone Type | Required Source Mode | Minimum Required Database Version | Allow Updates
--- | --- | --- | ---
Cold | Read-Only | 12.1.0.2 | No
Hot | Read-Write | 12.2 | No
Refreshable | Read-Write | 12.2 | Yes
Refreshable + Switchover | Read-Write | 18 | Yes

Supported Direct Upgrade Paths

Source Oracle Database version | Target Oracle Database version
--- | ---
12.1.0.1, 12.1.0.2, 11.2.0.3 or later | 12.2
12.2.0.1, 12.1.0.1, 12.1.0.2, 11.2.0.3, 11.2.0.4 | 18c
18c (all releases), 12.2.0.1, 12.1.0.2, 11.2.0.4 | 19c
19c (all releases), 18c (all releases), 12.2.0.1 | 21c
21c, 19c (all releases) | 26ai

### 4.21 Setting up the SEPS Wallet

The refreshable PDB along with switchover use case requires you to configure the Secure External Password Store (SEPS) wallet in the source CDB.

Perform the following steps:

1. Query the wallet root directory:

       SQL> show parameter root

       NAME                 TYPE       VALUE
       ------------------------------------ ----------- --------------------
       wallet_root      string      /var/opt/oracle/dbaas_acfs/db/wallet_root/

2. Create the SEPS wallet directory:``

   `$ mkdir /var/opt/oracle/dbaas_acfs/db/wallet_root/tde_seps`

3. Set the `EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION` parameter:

   `SQL> alter system set EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION = '/var/opt/oracle/dbaas_acfs/db/wallet_root/tde_seps' scope=spfile;`

4. Bounce the database:

       SQL> shutdown immediate;
       SQL> startup;

5. Create the SEPS wallet:

   ``

       SQL> administer key management ADD SECRET '<Source TDE keystore password>' for client 'TDE_WALLET' using TAG 'TDE keystore password' to auto_login keystore'/var/opt/oracle/dbaas_acfs/db/wallet_root/tde_seps';