Upgrading Oracle Database Releases Using Replay Upgrade

To upgrade from an earlier release, you can use the Oracle Multitenant Replay Upgrade (Replay Upgrade) procedure to adopt a non-CDB to a PDB, or upgrade a PDB.

Upgrading CDBs or PDBs Using Replay Upgrade
You can upgrade an entire container database (CDB) and its pluggable databases (PDBs) using a Replay Upgrade, or you can upgrade individual PDBs.
How to Disable or Enable Replay Upgrade
By default, the Oracle Multitenant Replay Upgrade (Replay Upgrade) method is enabled for upgrades on PDBs and CDBs. However, you can enable or disable the use of the Replay Upgrade method.
About Upgrading Non-CDBs to PDBs Using Replay Upgrade
You can automate some of the steps to upgrade non-CDB Oracle Database software to the multitenant architecture by using the Oracle Multitenant Replay Upgrade (Replay Upgrade) method.
Adopting and Upgrading a Non-CDB as a PDB with Replay Upgrade
To simplify your upgrades, you can adopt (move) and upgrade a non-CDB into a PDB by using the Oracle Multitenant Replay Upgrade (Replay Upgrade) method.
How the Replay Upgrade Procedure is Enabled or Disabled on CDBs and PDBs
Learn how you can use the default Replay Upgrade, or choose to perform a classic script-based upgrade.
Failure and Recovery Scenarios for Replay Upgrade Processes
Learn how to check for errors and issues in log files and trace files for an Oracle Multitenant Replay Upgrade (Replay Upgrade).

Parent topic: Upgrading Oracle Database Using Parallel Upgrade Utility or Replay Upgrade

Upgrading CDBs or PDBs Using Replay Upgrade

You can upgrade an entire container database (CDB) and its pluggable databases (PDBs) using a Replay Upgrade, or you can upgrade individual PDBs.

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.

Note:

When you plug in PDBs and upgrade the PDBs on PDB open using Replay Upgrade, Oracle recommends that you upgrade a number of PDBs equivalent to no more than one-fourth (¼) of the value of the Oracle Database initialization parameter CPU_COUNT, which specifies the number of CPU core (processors) available for Oracle Database to use. With traditional upgrades, the default number of PDBs upgraded at a time is no more than one-half (½) of the value of CPU_COUNT.

You can complete an upgrade using the Oracle Multitenant Replay Upgrade (Replay Upgrade) method either by using classic upgrade tools, or with the AutoUpgrade Utility.

Replay Upgrade Using Classic Upgrade Tools

To upgrade the entire CDB, including CDB$ROOT and all hosted PDBs, run the Parallel Upgrade Utility (catctl.pl) manually or implicitly, or use the dbupgrade script. The procedure is the same as in previous releases. However, starting with Oracle Database 21c, the upgrade utilities by default use the Replay Upgrade procedure. There is no change in command syntax.

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. This optimization avoids opening the PDB in restricted mode, exposing the error in the PDB_PLUG_IN_VIOLATIONS view, so that you are not required to correct the error manually.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade

How to Disable or Enable Replay Upgrade

By default, the Oracle Multitenant Replay Upgrade (Replay Upgrade) method is enabled for upgrades on PDBs and CDBs. However, you can enable or disable the use of the Replay Upgrade method.

To disable the Parallel Upgrade Utility (catctl.pl) default of performing a Replay Upgrade, run the following command, on either CDB$ROOT or a particular PDB:

ALTER DATABASE UPGRADE SYNC OFF

To re-enable the Replay Upgrade behavior, enter the following command

ALTER DATABASE UPGRADE SYNC ON

You can also select a non-replay upgrade by setting the Parallel Upgrade Utility (catctl.pl) parameter -t, which forces a non-replay upgrade that uses the classic scripting method.

Note:

You can manage use of the Replay Upgrade method on the entire CDB, or on individual PDBs, depending on whether you are connected to CDB$ROOT, or to a particular PDB:

If UPGRADE SYNC is set to OFF in CDB$ROOT, then the Replay Upgrade method is not used for any PDBs plugged into the CDB.
If UPGRADE SYNC is set to ON in CDB$ROOT, but set to OFF for a PDB, then the Replay Upgrade method is not used for the PDB where UPGRADE SYNC is OFF, but the Replay Upgrade method is used for all other PDBs plugged into the CDB.
If UPGRADE SYNC is set to ON in CDB$ROOT, and set to ON for all PDBs (the default), then the Replay Upgrade method is used for all PDBs plugged into the CDB.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade

About Upgrading Non-CDBs to PDBs Using Replay Upgrade

You can automate some of the steps to upgrade non-CDB Oracle Database software to the multitenant architecture by using the Oracle Multitenant Replay Upgrade (Replay Upgrade) method.

The Replay Upgrade method is enabled by default for upgrades from earlier Oracle Database releases that are supported for direct upgrade to this Oracle Database release. The Replay Upgrade process is different from the classic method of running scripts, such as noncdb_to_pdb.sql. For non-CDBs, after you describe the non-CDB by running DBMS_PDB.DESCRIBE, you plug in the non-CDB in to the new Oracle Database CDB. The Replay Upgrade method for upgrade is completed in two steps:

The non-CDB database is upgraded to the new Oracle Database release.
The non-CDB data dictionary is converted to a PDB data dictionary

Both of these steps are triggered when you run ALTER PLUGGABLE DATABASE OPEN. Both steps automatically replay SQL statements stored in the dictionary and complete the task of adopting the non-CDB to a PDB, and upgrading the database to the new release.

The benefit of using the Replay Upgrade method is to greatly simplify the upgrade workflow that you need to perform for PDB upgrades and conversions. The implicit non-CDB to PDB conversion simplifies the process of adopting and upgrading both non-CDB and PDB Oracle Database releases earlier than Oracle Database 21c to PDBs in a new release CDB.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade

Adopting and Upgrading a Non-CDB as a PDB with Replay Upgrade

To simplify your upgrades, you can adopt (move) and upgrade a non-CDB into a PDB by using the Oracle Multitenant Replay Upgrade (Replay Upgrade) method.

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.

Create the CDB if it does not exist.
Ensure that the non-CDB is in a transactionally-consistent state.
Place the non-CDB in read-only mode.
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.
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.
Shut down the non-CDB.
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.
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';
```
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'.
Run datapatch to patch the new PDB:
```
datapatch -pdbs ncdb
```

Run postupgrade fixups:

java -jar autoupgrade.jar -preupgrade "target_home=/u01/app/oracle/product/21.0.0/dbhome_1,dir=/autoupgrade/test/log,inclusion=ncdb" –mode postfixups

Back up the PDB.

A PDB cannot be recovered unless it is backed up.

Note:

If an error is returned during PDB creation, then the PDB being created might be in an UNUSABLE state. You can check the state of a PDB by querying the views CDB_PDBS or DBA_PDBS. You can learn more about PDB creation errors by checking the alert log. An unusable PDB can only be dropped. If the PDB is unusable, then it must be dropped before a PDB with the same name as the unusable PDB can be created.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade

How the Replay Upgrade Procedure is Enabled or Disabled on CDBs and PDBs

Learn how you can use the default Replay Upgrade, or choose to perform a classic script-based upgrade.

By default, when you run the Parallel Upgrade Utility (catctl.pl) manually, a Replay Upgrade is performed. When a PDB or a non-CDB is plugged into a new release container database (CDB). the PDB open detects whether the PDB or non-CDB requires an upgrade to be compatible with the CDB. If you have opened the database, and for non-CDBs, run the DBMS_PDB.DESCRIBE procedure to construct an XML file that describes the non-CDB, then the upgrade automatically occurs when the PDB is opened. For example, using the Replay Upgrade method, you can relocate an earlier release PDB from an earlier release CDB to an Oracle Database 21c CDB PDB on plugging in the PDB, without needing to run the Parallel Upgrade Utility script catctl.pl, or using AutoUpgrade, Database Upgrade Assistant (DBUA), or using the dbupgrade command.

To perform a classic script-based upgrade, you can run catctl.pl with the option -t. When you plug in a non-CDB, you can also turn off or turn on the Replay Upgrade process by running ALTER DATABASE UPGRADE SYNC OFF; to turn Replay Upgrade off, or ALTER DATABASE UPGRADE SYNC ON; to turn Replay Upgrade on. This syntax modifies the 'PDB_UPGRADE_SYNC' property, which is a number that is set to 2 for ON and 0 for OFF. If the number is positive, then catctl.pl uses the Replay Upgrade process. This property can be set in CDB$ROOT, or in the PDB. When disabled in ROOT, catctl.pl does not use the Replay Upgrade process for any PDBs. When enabled in ROOT, the PDB can either inherit this value, or set its own value.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade

Failure and Recovery Scenarios for Replay Upgrade Processes

Learn how to check for errors and issues in log files and trace files for an Oracle Multitenant Replay Upgrade (Replay Upgrade).

If a Replay Upgrade fails, then the PDB_UPGRADE_SYNC property is decremented by 1 for the PDB. If the Replay Upgrade fails twice, then catctl.pl falls back to using the classic script-based Parallel Upgrade Procedure method for completing the upgrade.

To determine the cause of Replay Upgrade errors, review the upgrade logs for statements that encounter errors. After a Replay Upgrade procedure runs, whether it is successful or unsuccessful, the query DBA_APP_ERRORS is run. Review the results of that query to see statement text and error messages for any statements that encounter errors. To see specific errors in the logs, you can also query the upgrade logs by using a grep command to locate any text strings of '^ORA-'.

Another recovery option is to review the trace files (.trc) . The trace files contain output for each statement run during the Replay Upgrade procedure. The files show statement text, whether statements succeeded or failed, error messages (if applicable), and the amount of time elapsed during the process. Look for lines that contain the prefix string Replay Upgrade, PDB ID where the variable ID is the PDB ID. For example: Replay Upgrade, PDB 15.

Parent topic: Upgrading Oracle Database Releases Using Replay Upgrade