When you upgrade a PDB to Oracle Database 23ai, there is a new method for performing the upgrade. It’s called Replay Upgrade.

I would call it a convenience feature. You simply plug in to a higher release CDB and open the PDB. The CDB detects the lower-release PDB and performs the upgrade. You don’t have to invoke AutoUpgrade.

Here’s how to do it.

A Few Words on Replay Upgrade

In Oracle Database 23ai, you can upgrade the data dictionary in two ways:

• Parallel Upgrade – Has been around for quite a few releases. It’s what you’ve used before and can still use.
• Replay Upgrade – The new thing that enables you to upgrade the data dictionary by simplying plugging in a lower-release PDB and allowing the CDB to perform the upgrade – without using AutoUpgrade.

I suggest you watch this video about the fundamental differences between the two methods.

Replay Upgrade is not a substitute for the entire upgrade project. Even with Replay Upgrade, you must still run the pre-upgrade and post-upgrade tasks. The version of the PDB must be one that allows for a direct upgrade to Oracle Database 23ai: 19c or 21c.

AutoUpgrade uses Parallel Upgrade. You can force AutoUpgrade to use Replay Upgrade in your config file:

upg1.replay=yes

How To Upgrade Using Replay Upgrade

1. You must perform the pre-upgrade tasks while the PDB is in the lower-release CDB.
2. One of such tasks is to analyze the PDB for upgrade readiness:

   java -jar autoupgrade.jar ... -mode analyze
   

3. If needed, run the pre-upgrade fixups:

   java -jar autoupgrade.jar ... -mode fixups
   

4. Plug in a lower-release PDB into a higher-release CDB. It doesn’t matter whether you plugged in from a manifest file, using refreshable clone PDBs or any other method.
5. Open the PDB:

   alter pluggable database PDB1 open;
   

   • When you open the PDB in normal mode, Replay Upgrade starts.
   • The open command doesn’t complete until the upgrade completes. The command is not hanging; it’s simply upgrading in the background.
   • If you open the PDB in upgrade mode, Replay Upgrade does not start.
6. During the open command, you can see in the alert log that the CDB upgrades the PDB:

   2025-03-31T14:02:37.955470+00:00
   ORANGE(6):Starting Upgrade on PDB Open
   

7. When the open command completes, the PDB will be upgraded. But it will open in restricted mode until you run Datapatch. From alert.log:

   ORANGE(6) Error Violation: SQL Patch, Cause: '23.5.0.24.07 Release_Update2407102158' is installed in the CDB but no release updates are installed in the PDB, Action: Call datapatch to install in the PDB or the CDB
   2025-03-31T14:11:03.803899+00:00
   ORANGE(6):Opening pdb with no Resource Manager plan active
   Violations: Type: 1, Count: 1
   Completed: Pluggable database ORANGE opened read write
   Completed:    alter pluggable database orange open
   

8. Run Datapatch:

   $ORACLE_HOME/OPatch/datapatch -pdbs PDB1
   

9. Restart the PDB to remove restricted mode:

   alter pluggable database PDB1 close immediate;
   alter pluggable database PDB1 open;
   

10. Run post-upgrade tasks.

Want To Try It?

In our upgrade lab, Hitchhiker’s Guide for Upgrading to Oracle Database 23ai, there is no lab on Replay Upgrade.

You can still perform a Replay Upgrade if you want. I’ve created instructions in the appendix that you can use. The lab takes 15 minutes to complete.

My Database Is A Non-CDB

Replay Upgrade performs an upgrade-on-open. Interestingly, it can also perform a convert-on-open. The latter will run the same commands you’ll find in noncdb_to_pdb.sql, which you normally run to convert a non-CDB to a PDB.

So, you can simply plug a 19c non-CDB into a 23ai CDB. When you open the PDB, the CDB upgrades and converts to a PDB.

My Recommendation

I recommend using AutoUpgrade. It ensures that you run all the tasks and automates them completely, giving you the safest upgrade.

Replay Upgrade does look a lot easier at first glance, but you still need to remember all the pre-upgrade and post-upgrade tasks. When there’s something you must run manually, there’s always the risk that you forget one or two of the tasks.

For me, Replay Upgrade is a convenience feature you can use in a lab or demo environment or if you think it’s easier to incorporate in your automation. But even with automation, you can still use AutoUpgrade with the -noconsole command line option.

But the choice is yours.

Happy upgrading!

Appendix

Replay Upgrade Queries and Commands

• Here’s how you can tell whether Replay Upgrade (Upgrade on Open and Convert On Open) is enabled:

  select property_name, property_value 
  from   database_properties
  where  property_name like '%OPEN%';
  

  You can set the property in the root container and in the PDB.
• Here’s how to disable Replay Update:

  alter database upgrade sync off;
  

Hands-On Lab

Here are the instructions for trying a Replay Upgrade in our Hands-On Lab.

The below steps perform a Replay Upgrade of the ORANGE PDB from CDB19 to CDB23.

1. Start by provisioning a new lab and connecting to it. The lab runs in Oracle LiveLabs and is completely free. No installation is required.
2. Start the CDB19 database. It’s a container database on Oracle Database 19c:

   . cdb19
   env | grep ORA
   sqlplus / as sysdba<<EOF
      startup;
   EOF
   

3. Create an AutoUpgrade config file:

   cd /home/oracle/scripts
   cat > orange-replay.cfg <<EOF 
   global.autoupg_log_dir=/home/oracle/logs/orange-replay
   upg1.source_home=/u01/app/oracle/product/19
   upg1.target_home=/u01/app/oracle/product/23
   upg1.sid=CDB19
   upg1.target_cdb=CDB23
   upg1.pdbs=ORANGE
   upg1.target_pdb_copy_option.ORANGE=file_name_convert=none
   upg1.timezone_upg=NO
   EOF
   

4. Run AutoUpgrade in analyze mode:

   cd
   java -jar autoupgrade.jar -config scripts/orange-replay.cfg -mode analyze
   

   • AutoUpgrade analyzes the ORANGE PDB for upgrade readiness.
5. Check the preupgrade summary report:

   cat /home/oracle/logs/orange-replay/cfgtoollogs/upgrade/auto/status/status.log
   

   • The report states Check passed and no manual intervention needed.
6. Run the preupgrade fixups:

   java -jar autoupgrade.jar -config scripts/orange-replay.cfg -mode fixups
   

   • AutoUpgrade runs pre-upgrade fixups, if any.
7. Unplug ORANGE from the 19c CDB:

   . cdb19
   sqlplus / as sysdba<<EOF
       alter pluggable database ORANGE close;
   	alter pluggable database ORANGE unplug into '/home/oracle/orange.xml';
   	drop pluggable database ORANGE keep datafiles;
   EOF
   

8. Plug into the 23ai CDB and open ORANGE:

   . cdb23
   env | grep ORA
   sqlplus / as sysdba<<EOF
      set timing on
      create pluggable database ORANGE using '/home/oracle/orange.xml' nocopy;
      alter pluggable database orange open;
   EOF
   

   • The open command upgrades the PDB. The command runs for several minutes.
   • In the end, the command completes but prints Warning: PDB altered with errors.
9. Run Datapatch on the ORANGE PDB:

   $ORACLE_HOME/OPatch/datapatch -pdbs ORANGE
   

10. Restart ORANGE:

    sqlplus / as sysdba<<EOF
    	alter pluggable database orange close;
    	alter pluggable database orange open;
    	select open_mode, restricted from v\$pdbs where name='ORANGE';
    EOF
    

    • The PDB now opens normally (READ WRITE) and unrestricted.
11. Run the post-upgrade fixups:

    java -jar autoupgrade.jar \
       -preupgrade "dir=/home/oracle/logs/orange-replay/fixups,inclusion_list=ORANGE" \
       -mode postfixups
    
    

12. That’s it. ORANGE has now been upgraded:

    sqlplus / as sysdba<<EOF
    	select open_mode, restricted from v\$pdbs where name='ORANGE';
    	alter session set container=ORANGE;
    	select version_full from v\$instance;
    EOF