1. Runbook: Move On-Premise Databases and Oracle Cloud Infrastructure Classic Instances to Oracle Cloud Infrastructure
  2. Migrate the Database

4 Migrate the Database

The following topics instruct you on running the migration job.

4.1 Evaluate the Database Migration Process

Requirement Description Comments
Verify prechecks and setup

To evaluate the database migration process, use the -eval option with the ZDMCLI migrate database command.

Have the completed response file available, and have the necessary credentials ready, such as the source database SYS password, Object Store (Bucket) swift authentication token, and, if the source server is accessed through the root user, then root user password.

If connectivity to the source database server users root credentials, then the command is

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb source_db_unique_name_value -sourcenode source_database_server_name -srcroot -targetnode target_database_server_name -targethome target_database_ORACLE_HOME -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:/usr/bin/sudo -eval

If connectivity to the source database server uses an SSH key, then the command is:

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb source_db_unique_name_value -sourcenode source_database_server_name -srcauth zdmauth -srcarg1 user:source_database_server_login_user_name -srcarg2 identity_file:ZDM_installed_user_private_key_file_location -srcarg3 sudo_location:/usr/bin/sudo -targetnode target_database_server_name -targethome target_database_ORACLE_HOME_value -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:/usr/bin/sudo -eval

Note that if a source single instance database is deployed without a Grid Infrastructure home, then in the above command use -sourcesid in place of -sourcedb.

Also, if a source database is configured for a PASSWORD based wallet, then add the -tdekeystorepasswd option to the command above, and for the prompt, specify the source database TDE keystore password value.

The migrate database command checks for connectivity to the source and target database servers.

The migrate database command also checks for patch compatibility between the source and target home patch level, and expects the target home patch level to be equal to or higher than the source. If the target home patch level is not as expected, then the migration job is stopped and missing patches are reported. You can either patch the target home with the necessary patches, or you can force continue the migration by appending the –ignore PATCH_CHECK or -ignore ALL option to the migration command.

It is highly recommended that for each migration you run migrate database in evaluation mode first. The evaluation allows you to correct any potential problems in the setup and configuration before performing the actual migration. In evaluation mode, the migration process runs without effecting the changes to source and target databases. It is safe to run the command with the -eval option as many times as needed before running the actual migration.

Zero Downtime Migration performs the following pre-checks.

  • Discovers information about the source database
  • Discovers information about the target database
  • Sets up Zero Downtime Migration helper modules on the source database server
  • Sets up Zero Downtime Migration helper modules on the target database server
  • Generates random password for encrypting RMAN backup

    This password is required to take a backup of the source database onto the Object Store.

  • Validates the source database
    • Archive log mode check
    • TDE setup
    • SYS password
    • Patch level
  • Validates the target database
    • Patch level
    • Data files storage locations (ASM disk group or ACFS file system)
  • Validates Object Store credentials

Example

For the prompts, specify the source database SYS password. If the backup destination is Object Store (Bucket), then specify the your swift authentication token. If the backup destination is Storage Classic (Container), then specify your tenancy login password. If the source server is accessed using the root user, then specify the root user password.

If connectivity to the source database server uses the root credentials then command would be

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcroot -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -ignore ALL -eval

Enter source database ZDM12201_phx1sp SYS password:

Enter source user "root" password:

Enter user "backup_user@example.com" password:

Then the following message is displayed with the job ID number. Make note of the job ID number for later use.

Operation "zdmcli migrate database" scheduled with the job ID "5".

If connectivity to the source database server uses an SSH key, then command is

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcauth zdmauth -srcarg1 user:opc -srcarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -srcarg3 sudo_location:/usr/bin/sudo -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -ignore ALL -eval

Enter source database ZDM12201_phx1sp SYS password:

Enter user "backup_user@example.com" password:

Then the following message is displayed with the job ID number. Make note of the job ID number for later use.

Operation "zdmcli migrate database" scheduled with the job ID "5".

See Prechecks Verification for sample command output.

Parent topic: Migrate the Database

4.2 Query the Migration Job Status

Requirement Description Comments
Query the migration job status

You can query the migration job status while the job is running.

Query the status of a database migration job using the ZDMCLI query job command, specifying the job ID. The job ID is shown in the command output when the database migration job is submitted.

zdmuser>$ZDM_HOME/bin/zdmcli query job -jobid job-id

You can find the migration job console output in the file (Result file path:), given in the query job command output. You can see migration progress messages in the specified file, as shown in this sample output.

Result file path: "/u01/app/zdmbase/chkbase/scheduled/job-5-2019-12-16-06:37:04.log"

For example

zdmuser>$ZDM_HOME/bin/zdmcli query job -jobid 5

Parent topic: Migrate the Database

4.3 Migrate the Database

Before submitting the database migration job, ensure that the evaluation migration job is successful to determine how the process may fare with your configuration and settings. If the evaluation migration job is not sucessful, then this migration job will not be successful.

Determine if the migration process needs to be paused and resumed before you start the database migration. Once the migration job is started, the job system runs the job as configured. If the migration job needs to pause and resume at a particular point, then see List Migration Job Phases, Pause and Resume a Migration Job, and Rerun a Migration Job for instructions.

Requirement Description Comments
Migrate the database

To migrate the database, have the completed response file, and keep the necessary credentials ready, such as the source database SYS password, Object Store (Bucket) swift authentication token, and if the source database server is accessed using the root user, then have the root user password.

If connectivity to the source database server uses the root credentials then the command is:

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb source_db_unique_name_value -sourcenode source_database_server_name -srcroot -targetnode target_database_server_name -targethome target_database_ORACLE_HOME -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:/usr/bin/sudo

If connectivity to the source database server uses an SSH key, then the command is:

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb source_db_unique_name_value -sourcenode source_database_server_name -srcauth zdmauth -srcarg1 user:source_database_server_login_user_name -srcarg2 identity_file:ZDM_installed_user_private_key_file_location -srcarg3 sudo_location:/usr/bin/sudo -targetnode target_database_server_name -targethome target_database_ORACLE_HOME_value -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:/usr/bin/sudo

Note that if a source single instance database is deployed without a Grid Infrastructure home, then in the above command use -sourcesid in place of -sourcedb.

Also, if a source database is configured for a PASSWORD based wallet, then add the -tdekeystorepasswd option to the command above, and for the prompt, specify the source database TDE keystore password value.

The migrate database command checks for patch compatibility between the source and target home patch level, and expects the target home patch level to be equal to or higher than the source. If the target home patch level is not as expected, then the migration job is stopped and missing patches are reported. You can either patch the target home with the necessary patches or you can force continue the migration by appending the –ignore PATCH_CHECK or -ignore ALL option to the migrate database command.

Example

For the prompts, specify the source database SYS password. If the backup destination is Object Store (Bucket), then specify your swift authentication token. If the backup destination is Storage Classic (Container), then specify your tenancy login password. If source server is accessed using the root user, then specify the root user password.

If connectivity to the source database server uses root credentials then command is

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcroot -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -ignore ALL

Enter source database ZDM12201_phx1sp SYS password:

Enter source user "root" password:

Enter user "backup_user@example.com" password:

Then the following message is displayed with the job ID number. Make note of the job ID number for later use.

Operation "zdmcli migrate database" scheduled with the job ID "6".

If connectivity to the source database server uses an SSH key, then command is

zdmuser>$ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcauth zdmauth -srcarg1 user:opc -srcarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -srcarg3 sudo_location:/usr/bin/sudo -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -ignore ALL

Enter source database ZDM12201_phx1sp SYS password:

Enter user "backup_user@example.com" password:

Then the following message is displayed with the job ID number. Make note of the job ID number for later use.

Operation "zdmcli migrate database" scheduled with the job ID "6".

Query the migration job status using the following command.

$ZDM_HOME/bin/zdmcli query job -jobid 6

See Migration Job Output for sample command output.

Parent topic: Migrate the Database

4.4 List Migration Job Phases

Requirement Description Comments
List migration job phases

To list the operation phases involved in the migration job, add the -listphases option in the ZDMCLI migrate database command.

For example

zdmuser> $ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcauth zdmauth -srcarg1 user:opc -srcarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -srcarg3 sudo_location:/usr/bin/sudo -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -listphases

 See List Migration Job Phases for sample command output.

Parent topic: Migrate the Database

4.5 Pause and Resume a Migration Job

Requirement Description Comments
Pause and resume a migration job

You can pause a migration job at any point after the ZDM_SETUP_TGT phase, and resume the job at any time.

To pause a migration job, specify the –pauseafter option in the ZDMCLI migrate database command with a valid phase at which to pause. Choose a valid phase that is listed in the -listphases command output.

Pausing after the ZDM_SETUP_TGT phase is recommended.

For example, if you specify -pauseafter ZDM_CONFIGURE_DG_SRC, the migration job will pause after completing the ZDM_CONFIGURE_DG_SRC phase.

zdmuser> $ZDM_HOME/bin/zdmcli migrate database -sourcedb ZDM12201_phx1sp -sourcenode zdm122011 -srcauth zdmauth -srcarg1 user:opc -srcarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -srcarg3 sudo_location:/usr/bin/sudo -targetnode ocitarget1 -targethome /u02/app/oracle/product/12.2.0/dbhome_3 -backupuser backup_user@example.com -rsp /u01/app/zdmhome/rhp/zdm/template/zdm_template_ZDM12201.rsp -tgtauth zdmauth -tgtarg1 user:opc -tgtarg2 identity_file:/home/zdmuser/.ssh/zdm_service_host.ppk -tgtarg3 sudo_location:/usr/bin/sudo -pauseafter ZDM_CONFIGURE_DG_SRC

A paused job can be resumed any time by running the ZDMCLI resume job command, and specifying the job ID.

To schedule another pause, specify the –pauseafter option in the resume job command with a valid phase at which to pause. Choose a valid phase later than phase the job is currently paused at, and that is listed in the -listphases command output.

The resume job command sytax is

zdmuser> $ZDM_HOME/bin/zdmcli resume job -jobid Job_ID [-pauseafter valid-phase]

Note that the -pauseafter option allows only one phase to be specified.

Note: After the phase ZDM_CONFIGURE_DG_SRC completes, a standby is created on the target and sync will happen from source to target. You can monitor and decide to resume the operation for the role change.

For example, to pause at another place when resuming the migration job:

zdmuser> $ZDM_HOME/bin/zdmcli resume job -jobid 6 -pauseafter ZDM_SWITCHOVER_TGT

Parent topic: Migrate the Database

4.6 Rerun a Migration Job

Requirement Description Comments
Rerun a migration job

If there are unexpected errors in the migration workflow, you can correct them and rerun the migration job.

The errors are recorded in the job output, which can be queried using the ZDMCLI query job command. When the error is resolved, the failed job can be continued from the point of failure.

Rerun the migration job by running the ZDMCLI resume job command, specifying the job ID of the job to be rerun, as shown here.

zdmuser> $ZDM_HOME/bin/zdmcli resume job -jobid Job_ID

For example:

$ZDM_HOME/bin/zdmcli resume job -jobid 6

Parent topic: Migrate the Database

4.7 Post-Migration Tasks

Requirement Description Comments
Run the datapatch utility on the target database

After you complete the database migration job, if the target database environment is at a higher patch level than the source database, you must run the datapatch utility on the target database.

For example, if your source database is at Oct 2018 PSU/BP and the target is at Jan 2019 PSU/BP), you must run the datapatch utility.

Before running datapatch on the target, ensure you apply the target patch level to the binaries at the source (standby) database.

If you are running a multitenant architecture, open the PDBs.

SQL> alter pluggable database all open;

It is recommended that you run datapatch on all of the PDBs; however, if you only want to open a subset of the PDBs in the CDB, you can use the following command instead. Datapatch only runs on the CDB and opened PDBs.

SQL> alter pluggable database PDB_NAME open;

To run datapatch on a PDB later (previously skipped or newly plugged in), open the database using the AlTER PLUGGABLE DATABASE command and rerun the datapatch utility.

Go to the OPatch directory in ORACLE_HOME and run the datapatch utility.

% cd $ORACLE_HOME/OPatch

% ./datapatch -verbose

The datapatch utility runs the necessary apply scripts to load the modified SQL files into the database. An entry is added to the dba_registry_sqlpatch view indicating the patch application.

Check for errors. Error logs are located in the $ORACLE_BASE/cfgtoollogs/sqlpatch/patch#/unique patch ID directory in the following format:

patch#_apply_database_SID_CDB_name_timestamp.log

where database_SID is the database SID, CDB_name is the name of the multitenant container database, and timestamp is in the format YYYYMMMDD_HH_MM_SS

 none
Apply patches Make sure that you can apply the patches to migrated database, using either the console or commands and APIs provided by the target platform. none
Create backups Make sure that you can back up the migrated database, using either the console or commands and APIs provided by the target platform. none

Parent topic: Migrate the Database