Replay Upgrade Using Automatic Upgrade on PDB Plug-In To a New Release CDB

If you plug in an earlier release PDB to a new release CDB, then the CDB detects on opening the PDB that the PDB is an earlier release than the CDB, and automatically starts a Replay Upgrade process. Upgrade on PDB Open automatically upgrades the PDB using the Replay Upgrade synchronization feature.

General Prerequisites

• Complete the prerequisites described in "General Prerequisites for PDB Creation" in Oracle Multitenant Administrator's Guide

• Either the XML file that describes the PDB or the .pdb archive file must exist in a location that is accessible to the CDB.

  The USING clause must specify the XML file or the .pdb archive file. If the PDB's XML file is unusable or cannot be located, then use the DBMS_PDB.RECOVER procedure to generate an XML file using the PDB's data files.

• If an XML file (not a .pdb file) is specified in the USING clause, then the files associated with the PDB (such as the data files and wallet file) must exist in a location that is accessible to the CDB.

• If the target database for the plugin operation is the primary database in an Oracle Data Guard configuration, then ensure that the standby database can locate the files for the plugged-in PDB.

  On the standby database, set the STANDBY_PDB_SOURCE_FILE_DIRECTORY initialization parameter to a location that contains the source data files for instantiating the PDB. If the files are not found, then the standby database tries to locate the files in the OMF location. If not found in the OMF location, then you must copy the data files to the OMF location on the standby database, and restart redo apply on the standby database.

• The source and target CDB platforms must meet the following requirements:

  • They must have the same endianness.

  • The database options installed on the source platform must be the same as, or a subset of, the database options installed on the target platform.

• If you are creating an application PDB, then the application name and version of the unplugged PDB must match the application name and version of the application container into which the application PDB is being plugged.

Character Set Prerequisites

You must meet the following prerequisites for matching the character sets:

• If the character set of the CDB into which the PDB is being plugged is not AL32UTF8, then the CDB that contained the unplugged PDB and the target CDB must have compatible character sets and national character sets. To be compatible, the character sets and national character sets must meet the requirements specified in Oracle Database Globalization Support Guide.

  If the character set of the CDB into which the PDB is being plugged is AL32UTF8, then this requirement does not apply.

  Note:

  Oracle Multitenant does not support a LOB in one container from being accessed by a container with a different character set using data links, extended data links, or the CONTAINERS() clause. For example, if the CDB root and salespdb have different character sets, then a CONTAINERS() query run in the CDB root should not access LOBs stored in salespdb.

• If you are creating an application PDB, then the application PDB must have the same character set and national character set as the application container.

  If the database character set of the CDB is AL32UTF8, then the character set and national character set of the application container can be different from the CDB. However, all application PDBs in an application container must have same character set and national character set, matching that of the application container.

To determine whether the preceding requirements are met, use the DBMS_PDB.CHECK_PLUG_COMPATIBILITY function. Step 2 in the following procedure describes using this function.

1. In SQL*Plus, ensure that the current container is the CDB root or application root of the target CDB.

   When the current container is the CDB root, the PDB is created in the CDB. When the current container is an application root, the application PDB is created in the application container.

2. (Optional) Run the DBMS_PDB.CHECK_PLUG_COMPATIBILITY function to determine whether the unplugged PDB is compatible with the CDB.

   1. If the PDB is not yet unplugged, then run the DBMS_PDB.DESCRIBE procedure to produce an XML file that describes the PDB.

      If the PDB is already unplugged, then proceed to Step 2b.

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

      BEGIN
        DBMS_PDB.DESCRIBE(
          pdb_descr_file => '/disk1/oracle/salespdb.xml',
          pdb_name       => 'SALESPDB');
      END;
      /
      

      If the PDB is in a remote CDB, then you can include @database_link_name in the pdb_name parameter, where database_link_name is the name of a valid database link to the remote CDB or to the PDB. For example, if the database link name to the remote CDB is rcdb, then set the pdb_name value to SALESPDB@rcdb.

   2. Run the DBMS_PDB.CHECK_PLUG_COMPATIBILITY function.

      When you run the function, set the following parameters:

      • pdb_descr_file - Set this parameter to the full path to the 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 PDB described by the /disk1/usr/salespdb.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/usr/salespdb.xml',
                 pdb_name       => 'SALESPDB')
          WHEN TRUE THEN 'YES'
          ELSE 'NO'
      END;
      BEGIN
        DBMS_OUTPUT.PUT_LINE(compatible);
      END;
      /
      

      If the output is YES, then the PDB is compatible, and you can continue with the next step. If the output is NO, then the PDB is not compatible: check the PDB_PLUG_IN_VIOLATIONS view to see why it is not compatible.

   Note:

   You can specify a .pdb archive file in the pdb_descr_file parameter.

3. If the PDB is not unplugged, then unplug it.

4. Run the CREATE PLUGGABLE DATABASE ... USING statement, specifying the XML file or the .pdb archive file in the USING clause. Specify other clauses when they are required.

   After you create the PDB, it is in mounted mode, and its status is NEW. You can view the open mode of a PDB by querying the OPEN_MODE column in the V$PDBS view. You can view the status of a PDB by querying the STATUS column of the CDB_PDBS or DBA_PDBS view.

   A new default service is created for the PDB. The service has the same name as the PDB and can be used to access the PDB. Oracle Net Services must be configured properly for clients to access this service.

5. Open the new PDB in read/write mode.

   You must open the new PDB in read/write mode for Oracle Database to complete the integration of the new PDB into the CDB. An error is returned if you attempt to open the PDB in read-only mode. After the PDB is opened in read/write mode, its status is NORMAL.

   Opening a PDB upgrades it automatically when a version mismatch occurs between the PDB and the CDB root. The Replay Upgrade on PDB Open optimization, which is the default, avoids manual error correction by re-executing statements stored in capture tables. The mechanism is the same used in application synchronization.

   When the PDB is opened, the database automatically performs a Replay Upgrade.

6. After the replay upgrade is complete, back up the PDB.

   Caution:

   A PDB cannot be recovered unless it is backed up. For more information about PDB and application containers, see Oracle Multitenant Administrator's Guide