Example 4-4 Upgrading and Converting a Non-CDB to Oracle Database 19c Using Multitenant Architecture

During the Deploy conversion and upgrade workflow, AutoUpgrade creates a GRP, and runs the Prefixup stage. If any part of the Deploy workflow up to the Prefixup stage completion fails, then AutoUpgrade can restore the database back to the GRP created at the start of the deployment,

However, after the Prefixup stage is complete, the upgraded database is plugged in to the target release Oracle Database container database (CDB) to complete conversion. As soon as the non-CDB is plugged into the CDB, the GRP is no longer valid, and is dropped.

If anything goes wrong during the plug-in, and you did not choose to use the target_pdb_copy_option in your configuration file to create copies of your data files, then be aware that AutoUpgrade cannot recover and restore the database. In that event, you must restore the database manually.

Example 4-7 Upgrading an Encrypted PDB with an Unplug Plug Upgrade Using AutoUpgrade

In the following example, an Oracle Database 12c Release 2 (12.2) PDB using Transparent Data Encryption (TDE) is upgraded to Oracle Database 19c, using the AutoUpgrade load_password command option with the AutoUpgrade configuration file keystore parameter to provide a secure store for the TDE keys during the upgrade.

1. Ensure that you have the latest version of AutoUpgrade:

   $ java -jar autoupgrade.jar -version
   

   If the AutoUpgrade version is an earlier release, then download the most recent version of AutoUpgrade from My Oracle Support AutoUpgrade Tool (Doc ID 2485457.1)

2. Create your AutoUpgrade configuration file. In this example, the configuration file PDB1.cfg is created with the path to the keystore, which is specified in the admin folder under the Oracle base directory, in the path /u01/app/oracle/admin/autoupgrade/keystore. The source CDB is CDB1,and the target CDB is CDB2:

   global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade
   global.keystore=/u01/app/oracle/admin/autoupgrade/keystore
   upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/DB12
   upg1.source_home=/u01/app/oracle/product/12.2.0/dbhome_1
   upg1.target_home=/u01/app/oracle/product/19.1.0/dbhome_1
   upg1.sid=CDB1
   upg.pdbs=PDB1
   upg1.target_cdb=CDB2
   

   Note:

   If you do not specify a keystore location, and an AutoUpgrade keystore has not been created previously, then AutoUpgrade creates the AutoUpgrade keystore for you.

3. Run AutoUpgrade in Analyze mode:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
   

   The summary report indicates that TDE keystore passwords are needed before starting the upgrade (TDE_PASSWORDS_REQURED):

   [Stage Name]    PRECHECKS
   [Status]        FAILURE
   [Start Time]    2022-03-29 07:58:52
   [Duration]       
   [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks
   [Detail]        /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks/cdb1_preupgrade.log
   		Check failed for PDB1, manual intervention needed for the below checks
   		[TDE_PASSWORDS_REQUIRED]

4. Add the TDE keystore passwords into the AutoUpgrade keystore:

   $ java -jar autoupgrade.jar -config PDB1.cfg -load_password
   

   The first time you run AutoUpgrade with the -load_password command option, you are prompted to create a password for the AutoUpgrade keystore, where TDE passwords can be stored securely:

   
   Starting AutoUpgrade Password Loader - Type help for available options
   Creating new keystore - Password required
   Enter password:       
   Enter password again: 
   Keystore was successfully created

   If do not use a SEPS keystore, then AutoUpgrade prompts you to add the TDE keystore passwords for the databases specified with source_home in your configuration file to AutoUpgrade's own keystore, where that database requires a TDE keystore password. This is what we have specified in the configuration file example.

   In the following example, the source and target TDE keystore passwords are loaded:

   TDE> ADD CDB1
   Enter your secret/Password:
   Re-enter your secret/Password:
   
   TDE> ADD CDB2
   Enter your secret/Password:
   Re-enter your secret/Password:

   Confirm that the passwords are loaded:

   TDE> LIST
   +---------------+-----------------+-----------------+--------------+----------------------+
   |ORACLE_SID     |Action Required  |TDE Password     |SEPS Status   |Active Wallet Type    |
   +---------------+-----------------+-----------------+--------------+----------------------+
   | CDB1          |                 | Verified        | Inactive     | Auto-login           |
   | CDB2          |                 | Verified        | Inactive     | Any                  |
   +---------------+-----------------+-----------------+--------------+----------------------+

   When the Action Required column is empty, the TDE passwords are available for the upgrade.

   If you use a SEPS keystore on the source CDB or target CDB, then AutoUpgrade automatically detects the SEPS keystore as the source for the TDE password. AutoUpgrade uses the IDENTIFIED BY EXTERNAL STORE clause, and does not need to load the TDE keystore passwords to the AutoUpgrade keystore. Again, the TDE LIST command should show an empty Action Required column:

   TDE> LIST
   +--------------+------------------+-------------------------+--------------+---------------------+
   |ORACLE_SID    |Action Required    | TDE Password           |SEPS Status   |Active Wallet Type   |
   +--------------+-------------------+------------------------+--------------+---------------------+
   | CDB1         |                   |No password loaded      | Verified     | Any                 |
   | CDB2         |                   |No password loaded      | Verified     | Any                 |
   +--------------+-------------------+------------------------+--------------+---------------------+

   Both options can be used in the same configuration file. For example, if you do not use a SEPS keystore for the source non-CDB database, but you do use a SEPS keystore for the target CDB, then you only need to load a password for the source non-CDB.

5. Save the TDE passwords into the AutoUpgrade keystore. (Optional): In this example, we will convert the keystore to an auto-login keystore:

   TDE> save
   Convert the keystore to auto-login [YES|NO] ? YES
   TDE> exit

6. Analyze the PDB again:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze

   Review the report and confirm all issues are resolved.

7. Start the upgrade and conversion:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode deploy
   

8. AutoUpgrade proceeds to upgrade PDB1 on the target Oracle Database, using the TDE passwords as needed to complete the upgrade. Because in this example we have configured AutoUpgrade to create an AutoUpgrade auto-login keystore, and access the TDE passwords using its own secure keystore, you are not prompted to provide TDE passwords during the upgrade.

Example 4-8 Upgrading a Database Using TDE and Converting from Non-CDB to PDB

In the following example, an Oracle Database 12c Release 2 (12.2) non-CDB database using Transparent Data Encryption (TDE) is upgraded to Oracle Database 19c and converted to a PDB, using the AutoUpgrade load_password command option with the AutoUpgrade configuration file keystore parameter to provide a secure store for the TDE keys during PDB conversion and upgrade.

1. Ensure that you have the latest version of AutoUpgrade:

   $ java -jar autoupgrade.jar -version
   

   If the AutoUpgrade version is an earlier release, then download the most recent version of AutoUpgrade from My Oracle Support AutoUpgrade Tool (Doc ID 2485457.1)

2. Create your AutoUpgrade configuration file. In this example, the path to the keystore is specified in the admin folder under the Oracle base directory, in the path /u01/app/oracle/admin/autoupgrade/keystore:

   global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade
   global.keystore=/u01/app/oracle/admin/autoupgrade/keystore
   upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/DB12
   upg1.source_home=/u01/app/oracle/product/12.2.0
   upg1.target_home=/u01/app/oracle/product/19.1.0
   upg1.sid=DB12
   upg1.target_cdb=CDB2
   

3. Run AutoUpgrade in Analyze mode:

   $ java -jar autoupgrade.jar -config DB12.cfg -mode analyze
   

   The summary report indicates that no additional preupgrade tasks need to be completed before starting the upgrade:

   [Stage Name]    PRECHECKS
   [Status]        SUCCESS
   [Start Time]    2022-03-30 10:28:38
   [Duration]       
   [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/DB12/DB12/100/prechecks
   [Detail]        /u01/app/oracle/cfgtoollogs/autoupgrade/DB12/DB12/100/prechecks/db12_preupgrade.log
   				Check passed and no manual intervention needed
   

   If the TDE_PASSWORDS_REQUIRED check fails, then load the TDE password:

   $ java -jar autoupgrade.jar -config DB12.cfg -load_password
   

   The first time you run AutoUpgrade with the -load_password command option, if AutoUpgrade requires a TDE password to perform the upgrade, then you are prompted to create a password for the AutoUpgrade keystore, where the TDE password can be stored securely:

   
   Starting AutoUpgrade Password Loader - Type help for available options
   Creating new keystore - Password required
   Enter password:       
   Enter password again: 
   Keystore was successfully created

   If do not use a SEPS keystore, then AutoUpgrade prompts you to add the TDE keystore passwords for the databases specified with source_home in your configuration file to AutoUpgrade's own keystore, where that database requires a TDE keystore password. This is what we have specified in the configuration file example.

   In the following example, the source and target TDE keystore passwords are loaded:

   TDE> ADD DB12
   Enter your secret/Password:
   Re-enter your secret/Password:
   
   TDE> ADD CDB2
   Enter your secret/Password:
   Re-enter your secret/Password:

4. To check the TDE configuration, you can run AutoUpgrade again using the -load_password command parameter. This time, because the password is already loaded, the TDE console prompt appears. Run the TDE console list command to check the TDE configuration:

   $ java -jar autoupgrade.jar -config DB12.cfg -load_password
   	
   TDE> list
   +----------+---------------+------------------+-----------+------------------+
   |ORACLE_SID|Action Required|   TDE Password   |SEPS Status|Active Wallet Type|
   +----------+---------------+------------------+-----------+------------------+
   |      CDB2|               |No password loaded|   Verified|               Any|
   |      DB12|               |No password loaded|    Unknown|        Auto-login|
   +----------+---------------+------------------+-----------+------------------+
   

   In the table output for the list command, the Action Required column is empty. This result verifies that you have provided the TDE keystore password. In the SEPS Status column, AutoUpgrade reports that it checked the password storage access on the target Oracle Database, CDB2, and confirms that the password works. Because the TDE console functionality to check the password was a feature added in Oracle Database 19c, AutoUpgrade is unable to confirm the password check for TDE on Oracle Database 12c Release 2 (12.2), so the result Unknown is expected.

   If you use a SEPS keystore on the source CDB or target CDB, then AutoUpgrade automatically detects the SEPS keystore as the source for the TDE password. AutoUpgrade uses the IDENTIFIED BY EXTERNAL STORE clause, and does not need to load the TDE keystore passwords to the AutoUpgrade keystore. Again, the TDE LIST command should show an empty Action Required column.

   Both options can be used in the same configuration file. For example, if you do not use a SEPS keystore for the source non-CDB database, but you do use a SEPS keystore for the target CDB, then you only need to load a password for the source non-CDB.

5. Start the upgrade and conversion:

   $ java -jar autoupgrade.jar -config DB12.cfg -mode deploy
   

6. AutoUpgrade proceeds to upgrade and convert the source non-CDB Oracle Database to a PDB on the target Oracle Database, using the TDE passwords as needed to complete the upgrade.

Example 4-9

1. Convert the source standby database to a snapshot standby database:

   DGMGRL> convert database '...' to snapshot standby;

   Note:

   If you don't manage your Oracle Data Guard configuration using Data Guard broker, then you can use the equivalent SQL commands instead to convert the source standby database to a snapshot standby database.

2. If you perform an unplug-plug upgrade, then ensure the PDB is open on the source snapshot standby database.

   alter pluggable database ... open;

   If you perform non-CDB to PDB conversions, then you can skip this step.

   Note:

   If the PDB is not open on the source standby database, then you receive an ORA-03150 error when querying the source database over the database link (ORA-03150: end-of-file on communication channel for database link).

3. In the source standby database, create the user account used by the database link, and grant appropriate permissions:

   create user dblinkuser identified by ...;
   grant create session, create pluggable database, select_catalog_role to
   dblinkuser;
   grant read on sys.enc$ to dblinkuser;

   Note:

   If you perform unplug-plug upgrades, then you must perform this operation in the source PDB, not in CDB$ROOT.

4. In the target CDB, create a database link that points to the source standby database, where alias-to-source-standby is the alias to the soruce standby database:

   create database link clonepdb
   connect to dblinkuser identified by ...
   using 'alias-to-source-standby';

   Note:

   If you perform unplug-plug upgrades, then the alias must point directly into the source PDB on the snapshot standby database.

5. Create an AutoUpgrade configuration file.

   The following example shows an unplug-plug upgrade:

   global.global_log_dir=/home/oracle/autoupgrade/log
   global.keystore=/home/oracle/autoupgrade/keystore
   upg1.source_home=/u01/app/oracle/product/19.0.0.0/dbhome_1
   upg1.target_home=/u01/app/oracle/product/23.0.0/dbhome_1
   upg1.sid=CDB19
   upg1.target_cdb=CDB23
   upg1.pdbs=PDB1
   upg1.source_dblink.PDB1=CLONEPDB 300
   upg1.target_pdb_copy_option.PDB1=file_name_convert=none
   upg1.start_time=+12h

6. Start AutoUpgrade in deploy mode:

   java -jar autoupgrade.jar ... -mode deploy

   AutoUpgrade starts to create a clone of the source database, and then proceeds to apply redo at the specified refresh rate. In the REFRESHPDB stage, you can change the start time (as specified in the configuration file) by using the PROCEED command.

7. After the entire process is completed, you convert the source standby database back to a physical standby database:

   DGMGRL> convert database '...' to physical standby;