Before you start an upgrade, the following steps must be performed:

• Install the new release software for Oracle Database
• Prepare the new Oracle home
• Run AutoUpgrade with the preupgrade parameter.

To adopt a non-CDB as a PDB using the DBMS_PDB package and the Replay Upgrade method, complete the following procedure.

1. Create the CDB if it does not exist.

2. Analyze the database for upgrade readiness. Run AutoUpgrade in analyze mode and check the outcome of the analysis in the summary report. AutoUpgrade prints the location of the summary report upon completion of the check. For example:

   export ORACLE_SID=NCDB
   export ORACLE_HOME=/u01/app/oracle/product/19.0.0/dbhome_1
   export ORACLE_TARGET_HOME=/u01/app/oracle/product/23.0.0/dbhome_1
   java -jar autoupgrade.jar -config_values "target_cdb=CDB23" -mode analyze

3. During the pre-upgrade analysis, AutoUpgrade detects whether any changes are needed to the database before starting the upgrade. Perform those changes by starting AutoUpgrade in fixups mode. For example:

   export ORACLE_SID=NCDB
   export ORACLE_HOME=/u01/app/oracle/product/19.0.0/dbhome_1
   export ORACLE_TARGET_HOME=/u01/app/oracle/product/23.0.0/dbhome_1
   java -jar autoupgrade.jar -config_values "target_cdb=CDB23" -mode fixups

4. Place the non-CDB in read-only mode.

5. Connect to the non-CDB, and run the DBMS_PDB.DESCRIBE procedure to construct an XML file that describes the non-CDB.

   The current user must have SYSDBA administrative privilege. The user must exercise the privilege using AS SYSDBA at connect time.

   For example, to generate an XML file named ncdb.xml in the /disk1/oracle directory, run the following procedure:

   BEGIN
     DBMS_PDB.DESCRIBE(
       pdb_descr_file => '/disk1/oracle/ncdb.xml');
   END;
   /
   

   After the procedure completes successfully, you can use the XML file and the non-CDB data files to plug the non-CDB into a CDB.

6. Run the DBMS_PDB.CHECK_PLUG_COMPATIBILITY function to determine whether the non-CDB is compatible with the CDB.

   When you run the function, set the following parameters:

   • pdb_descr_file - Set this parameter to the full path to the database description XML file.

   • pdb_name - Specify the name of the new PDB. If this parameter is omitted, then the PDB name in the XML file is used.

   For example, to determine whether a non-CDB described by the /disk1/oracle/ncdb.xml file is compatible with the current CDB, run the following PL/SQL block:

   SET SERVEROUTPUT ON
   DECLARE
     compatible CONSTANT VARCHAR2(3) := 
       CASE DBMS_PDB.CHECK_PLUG_COMPATIBILITY(
              pdb_descr_file => '/disk1/oracle/ncdb.xml',
              pdb_name       => 'NCDB')
       WHEN TRUE THEN 'YES'
       ELSE 'NO'
   END;
   BEGIN
     DBMS_OUTPUT.PUT_LINE(compatible);
   END;
   /
   

   If the output is YES, then the non-CDB is compatible, and you can continue with the next step. If the output is NO, then the non-CDB is not compatible. To see why it is not compatible, check the view PDB_PLUG_IN_VIOLATIONS. Before you continue, you must correct all violations. For example, any version or patch mismatches should be resolved by running an upgrade, or running the datapatch utility. After correcting the violations, run DBMS_PDB.CHECK_PLUG_COMPATIBILITY again to ensure that the non-CDB is compatible with the CDB.

7. Shut down the non-CDB.

8. Plug in the non-CDB.

   For example, the following SQL statement plugs in a non-CDB, copies its files to a new location, and includes only the tbs3 user tablespace from the non-CDB:

   CREATE PLUGGABLE DATABASE ncdb USING '/disk1/oracle/ncdb.xml'
     COPY
     FILE_NAME_CONVERT = ('/disk1/oracle/dbs/', '/disk2/oracle/ncdb/')
     USER_TABLESPACES=('tbs3');
   

   If there are no violations, then do not open the new PDB. You will open it in a later step.

   The USER_TABLESPACES clause enables you to separate data that was used for multiple tenants in a non-CDB into different PDBs. You can use multiple CREATE PLUGGABLE DATABASE statements with this clause to create other PDBs that include the data from other tablespaces that existed in the non-CDB.

9. To confirm replay upgrade is turned on, enter the following:

   select property_name, property_value
   from database_properties
   where property_name in('UPGRADE_PDB_ON_OPEN', 'CONVERT_NONCDB_ON_OPEN');

10. Connect to the new PDB, and open it. At the time that the PDB is opened, the database is upgraded, and the non-CDB database data dictionary is converted to a PDB. For example:

    ALTER PLUGGABLE DATABASE OPEN

    You must open the new PDB for Oracle Database to complete upgrading the database. An error is returned if you attempt to open the PDB in read-only mode. When the PDB is opened, the non-CDB is adopted to a PDB, the data dictionary is converted, and the new PDB is integrated into the CDB. Messages from the Replay Upgrade are placed in the trace directory. After the PDB is opened, and the REPLAY UPGRADE is completed, its status is NORMAL.

    To check the status of the upgrade, you can query the following views:

    • To check for Replay Upgrade errors, use the view DBA_REPLAY_UPGRADE_ERRORS
    • To check completeness, use DBA_APPLICATIONS. Check the app_version value for app_name 'APP$CDB$CATALOG' value. This value should be the new version of the PDB.
    • Check the view DBA_APP_ERRORS for statement errors. This view lists the error message and statement text (app_statement) for any errors. In a successful upgrade, this view should not contain any rows for app_name='APP$CDB$CATALOG'.

11. Run datapatch to patch the new PDB:

    datapatch -pdbs ncdb

12. Run postupgrade fixups using AutoUpgrade, and specifying the following:

    • ORACLE_SID specifies the system identifier of the target container database
    • ORACLE_HOME is the Oracle home of the database specified by ORACLE_SID.
    • The inclusion_list contains the name of the PDB (the former non-CDB). You can specify more PDBs if needed.
    • The dir option specifies the directory where AutoUpgrade can store the logs files.

    In the following example, ORACLE_SID is specified as CDB23, ORACLE_HOME is specified as /u01/app/oracle/product/23.0.0/dbhome_1, the log file directory is specified as /u01/app/oracle/cfgtoollogs/autoupgrade, and the inclusion_list is specified as NCDB:

    export ORACLE_SID=CDB23
    export ORACLE_HOME=/u01/app/oracle/product/23.0.0/dbhome_1
    java -jar autoupgrade.jar -preupgrade "dir=/u01/app/oracle/cfgtoollogs/autoupgrade,inclusion_list=NCDB" -mode postfixups
    

13. Back up the PDB.

    A PDB cannot be recovered unless it is backed up.