AutoUpgrade relies on out-of-place patching, thus, it creates a new Oracle home. After installing a new Oracle home, you must execute root.sh as the root user.
AutoUpgrade now does this for you under the following circumstances:
oracle user has sudo privileges.
The sudo command doesn’t require a password.
AutoUpgrade handles root.sh in the ROOTSH stage, and writes log messages to <autoupgrade_log_dir>/<sid>/<job-no>/rootsh/rootsh.log.
Sudo Privileges
If oracle has sudo privileges, no configuration is needed. AutoUpgrade sees this and automatically executes root.sh after installing the Oracle home and applying the desired patches.
What If
If AutoUpgrade can’t execute root.sh, you must do it manually. AutoUpgrade writes a message into the rootsh.log:
2025-03-24 07:39:22.297 INFO Root Script Path : /u01/app/oracle/product/19_25/root.sh - RootScript.executePatchStage#66
2025-03-24 07:39:22.305 INFO Executing Root Script - RootScript.updateAndLogInfoMessage#91
sudo: a password is required
2025-03-24 07:39:22.327 INFO Root script execution failed sudo: a password is required
- RootScript.executeRootScript#112
2025-03-24 07:39:22.327 INFO AutoUpgrade Patching has not run /u01/app/oracle/product/19_25/root.sh for the newly installed ORACLE_HOME. This needs to be performed manually after AutoUpgrade Patching completes. - RootScript.executePatchStage#83
If AutoUpgrade can’t run the root.sh for you, you shouldn’t use the one-button approach, where it handles everything in one operation. Instead, you should follow this approach:
Install the new Oracle home using -mode create_home.
Manually run root.sh.
Patch the database using -mode deploy. AutoUpgrade sees that you’ve already created the new Oracle home, and skips that part.
Why do you need to do it in multiple steps?
Some functionality in the database requires that you run root.sh. Also, there are certain patches that require you to run root.sh before starting the database. One example is patch 34672698, ORA-00800: SOFT EXTERNAL ERROR, ARGUMENTS: [SET PRIORITY FAILED], [VKTM] , DISM(16). Suppose you haven’t set the proper file permissions with root.sh before starting the database, the database won’t be able to elevate the priority of some of the most critical background processes.
The Special Patches
As mentioned above, there are some special patches that require that you fiddle with file system permissions during the apply.
Using AutoUpgrade, installing such a patch is very easy. AutoUpgrade takes all that into consideration.
This is how AutoUpgrade creates the new Oracle home:
Unzip the Oracle home.
Installs the Oracle home using runInstaller, but doesn’t run root.sh.
Applies patches using OPatch, including such special patches.
Executes root.sh, which applies all the required file permissions.
The execution of root.sh in the end takes care of all the extra work with permissions.
Someone made incorrect claims about Oracle Database on LinkedIn to draw attention. According to sources (himself), Connor tried to resist the urge to jump in but failed. We all know that Resistance is futile.
Connor wrote a good blog post showing that the attention-seeking author of the LinkedIn post is wrong!
Upgrades Are Risky and Complex
One of the false claims was that:
Upgrades are risky and complex. Want to upgrade? Prepare for a long, nerve-wracking process where something will break.
Connor replied:
Upgrades are now editing a 10 line configuration file and running autoupgrade. One line command and you’re good to go.
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.
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;
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.
. 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.
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
The other day, I found myself praising refreshable clone PDBs to a customer (which I often do because it’s a killer feature). They liked the feature too but asked:
> We are concerned about the impact on the source database. When AutoUpgrade connects to the source database and clones the database, can we offload the work to a standby database?
Refreshable clone PDBs can eat up your resources if you don’t constrain the target CDB. So, let’s see what we can do.
Mounted Standby Database
This won’t work, because you must be able to connect to the database via a regular database link. Further, AutoUpgrade and the cloning process must be able to execute queries in the source database, which is not possible on a mounted database.
Open Standby Database / Active Data Guard
What if you stop redo apply and open the standby database? Or if you have Active Data Guard?
In this case, the database would be open in read-only mode, and those queries would work. However, the refreshable clone PDB feature was developed to work in and require a read-write database, so this won’t work either – Not even if you enable automatic redirection of DML operations (ADG_REDIRECT_DML).
Even if this case would work, we wouldn’t recommend it. Because, we recommend that you run analyze and fixups mode on the source database, which wouldn’t be possible on a read-only database.
You could run analyze and fixups on the primary database. But is that really an option? If you’re worried about affecting your primary and want to offload to the standby, would running those commands on the primary be an option?
Snapshot Standby Database
What about a snapshot standby? That’s a read-write database. Let’s give it a try.
Convert the source standby to a snapshot standby:
DGMGRL> convert database '...' to snapshot standby;
The standby must remain a snapshot standby for the entire duration of the job. If you need to switch over or fail over to the standby, you must restart the entire operation.
Ensure the PDB is open on the source standby.
alter pluggable database ... open;
Otherwise, you will run into ORA-03150 when querying the source database over the database link.
In the source standby, create the user used by the database link and grant appropriate permissions:
create user dblinkuser identified by ...;
grant create session, create pluggable database, select_catalog_role to dblinkuser;
grant read on sys.enc$ to dblinkuser;
In the target CDB, create a database link that points to the PDB in source standby:
create database link clonepdb
connect to dblinkuser identified by ...
using '';
Convert the source standby back to a physical standby:
DGMGRL> convert database '...' to physical standby;
Is It Safe?
Using a standby database for anything else than your DR strategy, is sometimes perceived as risky. But it is not, as I explain in this blog post (section What Happens If I Need to Switch Over or Fail Over?).
Oracle just released new Release Updates, so it’s time to patch your Oracle Database again. As much as I love patching, the part about finding and downloading patches is not that much fun.
Luckily, I can use AutoUpgrade to download the Release Update and other patches with just a few commands.
How to Download Release Updates
I can do the following on any computer. I just need Java 8 or 11 to run AutoUpgrade.
I want to download 19.27 Release Update and supporting patches for Linux and I specify that using the platform parameter.
I’ve already used AutoUpgrade to download patches, so my My Oracle Support credentials are already stored in the AutoUpgrade keystore. If you’ve never used AutoUpgrade to download patches, follow the instructions below (see Creating an AutoUpgrade Keystore).
I download the patches by starting AutoUpgrade in download mode:
OPatch 12.2.0.1.46 for DB 19.0.0.0.0 (Apr 2025) – p6880880_190000_Linux-x86-64.zip
Is it really that easy? Yes, it is…
Happy patching!
What About the Other Platforms
At the time of writing, Oracle has only released the Linux patches. Once the other platforms are available, you can easily download them as well. Check the Patch Availability Document for details. Add the following to your config file:
AutoUpgrade prompts for a password to protect its keystore. AutoUpgrade uses the password to encrypt the keystore, which stores my My Oracle Support credentials.
This is not the database keystore password that you use for TDE Tablespace Encryption.
Processing config file ...
Starting AutoUpgrade Patching Password Loader - Type help for available options
Creating new AutoUpgrade Patching keystore - Password required
Enter password:
Enter password again:
I specify my MOS username. AutoUpgrade then prompts me for the MOS password:
MOS> add -user <mos-username-or-email>
Enter your secret/Password:
Re-enter your secret/Password:
I save the changes, and I choose to create an auto-login keystore so I don’t have to enter the AutoUpgrade keystore password every time AutoUpgrade starts:
MOS> save
Convert the AutoUpgrade Patching keystore to auto-login [YES|NO] ? YES
Suppose you need to connect through a proxy server to reach My Oracle Support and get the patches. AutoUpgrade now supports several ways to use a proxy.
Set https_proxy in lowercase. At least on Linux, environment variables are case-sensitive and although some programs can handle any case, it’s better to use the official case.
AutoUpgrade automatically picks up and uses the proxy.
Other Proxy Types
You can set https_proxy to a value matching this specification:
This error message indicates that you forgot to set the https_proxy environment variable or set it correctly:
There were conditions found preventing AutoUpgrade Patching from successfully running
*Downloading Oracle Patch files
Patch query failed
*login-ext.identity.oraclecloud.com*
This error message indicates that your proxy doesn’t allow connections to all the required servers:
There were conditions found preventing AutoUpgrade Patching from successfully running
*Downloading Oracle Patch files
Patch query failed
*Unable to tunnel through proxy. Proxy returns "HTTP/1.1 403 Forbidden"*
The source database is Oracle Database 19c. They configured AutoUpgrade to upgrade to Oracle Database 23ai using refreshable clone PDBs. However, this test measured only the initial copy of the data files – the CLONEDB stage in AutoUpgrade.
Parallel
Time
Throughput
Source CPU %
Default
269s
3,6 GB/s
3%
Parallel 4
2060
0,47 GB/s
1%
Parallel 8
850
1,14 GB/s
1%
Parallel 16
591
1,65 GB/s
2%
A few observations:
Cloning a 1 TB database in just 5 minutes.
Very little effect on CPU + I/O on source, entirely network-bound.
The throughput could scale almost up to the limit of the network.
By the way, this corresponds with reports we’ve received from other customers.
Learnings
The initial cloning of the database is very fast and efficient.
You should be prepared for the load on the source system. Especially since the network is a shared resource, it might affect other databases on the source system, too.
The target CDB determines the default parallel degree based on its own CPU_COUNT. If the target system is way more powerful than the source, this situation may worsen.
Use the AutoUpgrade config file entry parallel_pdb_creation_clause to select a specific parallel degree. Since the initial copy happens before the downtime, you might want to set it low enough to prevent overloading the source system.
Any piece of software has errors. It’s just a fact of life.
Should you encounter problems with AutoUpgrade, you can help us by compiling a zip package. This package contains valuable information that we need to troubleshoot.
Are You Using the Latest Version
Before generating a zip package, check that you’re using the latest version of AutoUpgrade… Perhaps the issue is already fixed:
When you migrate or upgrade with refreshable clone PDBs, you sometimes want to decide when the final refresh happens. Perhaps you must finish certain activities in the source database before moving on.
I’ve discussed this in a previous post, but now there’s a better way.
The Final Refresh Dilemma
In AutoUpgrade, the final refresh happens at the time specified by the config file parameter start_time. This is the cut-over time where no further changes to the source database, gets replicated in the target database.
You specify start_time in the config file, and then you start the job. Typically, you start it a long time before start_time to allow the creation of the new PDB.
So, you must specify start_time in the config file and that’s when you believe the final refresh should happen. But things might change in your maintenance window. Perhaps it takes a little longer to shut down your application or there’s a very important batch job that must finish. Or perhaps you can start even earlier.
In that case, a fixed start time is not very flexible.
The Solution
You can use the proceed command in the AutoUpgrade console to adjust the start time, i.e., the final refresh.
Start the job in deploy mode as you normally would:
java -jar autoupgrade.jar ... -mode deploy
AutoUpgrade now starts the CLONEPDB stage and begins to copy the database.
Wait until the job reaches the REFRESHPDB stage:
+----+-------+----------+---------+-------+----------+-------+--------------------+
|Job#|DB_NAME| STAGE|OPERATION| STATUS|START_TIME|UPDATED| MESSAGE|
+----+-------+----------+---------+-------+----------+-------+--------------------+
| 100| CDB19|REFRESHPDB|EXECUTING|RUNNING| 14:10:29| 4s ago|Starts in 54 minutes|
+----+-------+----------+---------+-------+----------+-------+--------------------+
Total jobs 1
In this stage, AutoUpgrade is waiting for start_time to continue the migration. It refreshes the PDB with redo from the source at the specified refresh interval.
I must start well before the maintenance window, so AutoUpgrade has enough time to copy the database.
You can now change the start time. If you want to perform the final refresh and continue immediately, use the proceed command:
Or, you can change the start time to a relative value, example 1 hour 30 min from now:
proceed -job 100 -newStartTime +1h30m
After the final refresh, AutoUpgrade disconnects the refreshable clone PDB, turns it into a regular PDB, and moves on with the job.
Wrapping Up
AutoUpgrade offers complete control over the process. You define a start time upfront, but as things change, you can adjust it in flight.
Refreshable clone PDBs are a fantastic method for non-CDB to PDB migrations and for upgrades of individual PDBs.
There are a few quirks to be aware of, and if you are using Data Guard bear in mind that you can only plug in with deferred recovery. Other than that – it’s just to say…
Here’s a blog post series about patching Oracle Data Guard in single instance configuration. For simplicity, I am patching with Oracle AutoUpgrade to automate the process as much as possible.
You need an outage until you’ve patched all databases.
You need to do more work during the outage.
You turn off redo transport while you patch.
Standby-first with restart
All the patches you apply must be standby-first installable (see appendix).
You need an outage to stop the primary database and restart it in the target Oracle home.
During the outage, you have to do less work to do compared to all at once and less work overall compared to standby-first with switchover.
The primary database remains the same. It is useful if you have an async configuration with a much more powerful primary database or just prefer to have a primary database at one specific location.
Standby-first with switchover
All the patches you apply must be standby-first installable (see appendix).
You need an outage to perform a switchover. If your application is well-configured, users will just experience it as a brownout (hanging for a short period while the switchover happens).
During the outage, you have little to do, but overall, there are more steps.
After the outage, if you switch over to an Active Data Guard, the workload from the read-only workload has pre-warmed the buffer cache and shared pool.
Summary
All at one
Standby-first with restart
Standby-first with switchover
Works for all patches
Works for most patches
Works for most patches
Bigger interruption
Bigger interruption
Smaller interruption
Downtime is a database restart
Downtime is a database restart
Downtime/brownout is a switchover
Slightly more effort
Least effort
Slightly more effort
Cold database
Cold database
Pre-warmed database if ADG
Here’s a decision tree you can use to find the method that suits you.
What If
RAC
These blog posts focus on single instance configuration.
Conceptually, patching Data Guard with RAC databases is the same; you can’t use the step-by-step guides in this blog post series. Further, AutoUpgrade doesn’t support all methods of patching RAC databases (yet).
I suggest that you take a look at these blog posts instead:
You can use these blog posts if you’re using Oracle Restart. You can even combine patching Oracle Restart and Oracle Database into one operation using standby-first with restart.
We’re Really Sensitive To Downtime?
In these blog posts, I choose the easy way – and that’s using AutoUpgrade. It automates many of the steps for me and has built-in safeguards to ensure things don’t go south.
But this convenience comes at a price: sligthly longer outage. Partly, because AutoUpgrade doesn’t finish a job before all post-upgrade tasks are done (like Datapatch and gathering dictionary stats).
If you’re really concerned about downtime, you might be better off with your own automation, where you can open the database for business as quickly as possible while you run Datapatch and other post-patching activities in the background.
Datapatch
Just a few words about patching Data Guard and Datapatch.
You always run Datapatch on the primary.
You run Datapatch just once, and the changes to the data dictionary propagates to the standby via redo.
You run Datapatch when all databases are running out of the new Oracle home or when redo transport is turned off. The important part is that the standby that applies the Datapatch redo must be on the same patch level as the primary.
Happy patching
Appendix
Standby-First Installable
You can only perform standby-first patch apply if all the patches are marked as standby-first installable.
Standby-first patch apply is when you patch the standby database first, and you don’t disable redo transport/apply.
You can only use standby-first patch apply if all the patches are classified as standby-first installable. For each of the patches, you must:
Examine the patch readme file.
One of the first lines will tell if this specific patch is standby-first installable. It typically reads:
> This patch is Data Guard Standby-First Installable
Release Updates are always standby-first installable, and so are most of the patches for Oracle Database.
In rare cases, you find a non-standby-first installable patch, so you must patch Data Guard using all at once.
Databases Are Fun 