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. Ensure that the non-CDB is in a transactionally-consistent state.

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

4. 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 database files to plug the non-CDB into a CDB.

5. 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.

6. Shut down the non-CDB.

7. 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.

8. To enable the database open command to perform the Replay Upgrade, enter ALTER DATABASE PROPERTY SET UPGRADE_PDB_ON_OPEN='true'. For example:

   ALTER DATABASE PROPERTY SET UPGRADE_PDB_ON_OPEN='true';

9. 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'.

10. Back up the PDB.

    A PDB cannot be recovered unless it is backed up.