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

You must perform the pre-upgrade tasks while the PDB is in the lower-release CDB.
One of such tasks is to analyze the PDB for upgrade readiness:
```
java -jar autoupgrade.jar ... -mode analyze
```

If needed, run the pre-upgrade fixups:

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

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

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

Run Datapatch:

$ORACLE_HOME/OPatch/datapatch -pdbs PDB1

Restart the PDB to remove restricted mode:

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

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.

Start by provisioning a new lab and connecting to it. The lab runs in Oracle LiveLabs and is completely free. No installation is required.
Start the CDB19 database. It’s a container database on Oracle Database 19c:
```
. cdb19
env | grep ORA
sqlplus / as sysdba<<EOF
   startup;
EOF
```

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

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

Run the preupgrade fixups:

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

AutoUpgrade runs pre-upgrade fixups, if any.

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

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.

Run Datapatch on the ORANGE PDB:

$ORACLE_HOME/OPatch/datapatch -pdbs ORANGE

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.

Run the post-upgrade fixups:

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

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

Tag: replay upgrade

Upgrade a PDB to Oracle Database 23ai Using Replay Upgrade