The other day, I helped a customer with an interesting case:

We have a 19c CDB with 100 PDBs running on old hardware. We need to upgrade and move the PDBs to a new server with Oracle Database 23ai. We would like to move the PDBs in batches.

Here’s how I would do that using AutoUpgrade and refreshable clone PDBs.

How To

In each PDB, you must create a user that you can use for the database link:

create user dblinkuser identified by dblinkuser;
grant create session to dblinkuser;
grant select_catalog_role to dblinkuser;
grant create pluggable database to dblinkuser;
grant read on sys.enc$ to dblinkuser;

Repeat this process for every source PDB.

In the target CDB, create a database link in the root container for every PDB:
```
create database link clonepdb1
connect to dblinkuser
identified by dblinkuser
using 'sourcehost/pdb1';
```
- Repeat this process for each PDB and assign a unique name to the database link.

Create an AutoUpgrade config that upgrades a batch of the PDBs. In this case, PDBs 1-4:

global.global_log_dir=/home/oracle/logs
global.keystore=/home/oracle/keystore

upg1.sid=CDB19
upg1.target_cdb=CDB23
upg1.source_home=/u01/app/oracle/product/19
upg1.target_home=/u01/app/oracle/product/23
upg1.pdbs=PDB1,PDB2,PDB3,PDB4
upg1.source_dblink.PDB1=CLONEPDB1 1800
upg1.source_dblink.PDB2=CLONEPDB2 1800
upg1.source_dblink.PDB3=CLONEPDB3 1800
upg1.source_dblink.PDB4=CLONEPDB4 1800
upg1.target_pdb_copy_option.PDB1=FILE_NAME_CONVERT=NONE
upg1.target_pdb_copy_option.PDB2=FILE_NAME_CONVERT=NONE
upg1.target_pdb_copy_option.PDB3=FILE_NAME_CONVERT=NONE
upg1.target_pdb_copy_option.PDB4=FILE_NAME_CONVERT=NONE
upg1.target_pdb_name.PDB1=PDBNEW1
upg1.target_pdb_name.PDB2=PDBNEW2
upg1.target_pdb_name.PDB3=PDBNEW3
upg1.target_pdb_name.PDB4=PDBNEW4
upg1.parallel_pdb_creation_clause.PDB1=2
upg1.parallel_pdb_creation_clause.PDB2=2
upg1.parallel_pdb_creation_clause.PDB3=2
upg1.parallel_pdb_creation_clause.PDB4=2
upg1.start_time=01/10/2026 02:30:00

In source_dblink you specify the name of the database link that you previously created. You must assign the right database link to the right PDB. The following number (1800) is the refresh rate in seconds. You can adjust that accordingly.
In this example, you’re using Oracle Managed Files, and FILE_NAME_CONVERT=NONE allows the target CDB to automatically generate new file names.
I recommend renaming the PDB to avoid any confusion. You can do that with target_pdb_name.
Also, limit the number of parallel processes that the target CDB can use to copy the PDB over the network. The file copy happens for all PDBs at the same time, so in this case, the target CDB should have at least 8 CPUs. Also, take the resources of the source CDB into consideration.

Run AutoUpgrade in analyze mode on the source database host. This checks the PDBs for upgrade readiness:
```
java -jar autoupgrade.jar -config upgrade.cfg -mode analyze
```
Run AutoUpgrade in deploy mode on the target database host:
```
java -jar autoupgrade.jar -config upgrade.cfg -mode deploy
```
- The target CDB now starts to copy the PDBs over.
- After that, it periodically refreshes the PDBs with redo from the source database.
- It doesn’t proceed with the actual upgrade.
- Instead, it waits until you reach the time specified by the start_time parameter.
Downtime starts now
Run AutoUpgrade in fixups mode on the source database host. This runs recommended and required pre-upgrade fixups in the PDBs:
```
java -jar autoupgrade.jar -config upgrade.cfg -mode fixups
```
Instruct AutoUpgrade to move on with the upgrade even though the start_time hasn’t been reached yet:
```
upg> proceed -job <job-number>
```
AutoUpgrade now performs a final refresh to bring over the latest changes. Then, it upgrades the PDBs concurrently. It will upgrade CPU_COUNT/2 at the same time. You can tweak that using catctl_options.
Be sure to stop the source PDBs that are running in the 19c CDB.

That’s it! You’ve now moved and upgraded the first batch of PDBs. You can repeat the process with the next batch.

In One Batch

Technically, you can put all PDBs into the same configuration file and move/upgrade them all at the same time.

However, you might as well use Data Guard to build a standby database and then perform an upgrade of the entire CDB.

However, if possible, I would recommend moving/upgrading the PDBs in batches.

Final Words

AutoUpgrade and refreshable clones are a perfect match.

What would you recommend? Leave a comment and let me know what you would suggest.

Move to New Server and Transparent Data Encryption

When you upgrade your Oracle Database, you often want to move to new hardware. AutoUpgrade fully supports this use case. Mike Dietrich mentions this in his blog post and video.

When you upgrade an encrypted non-CDB or entire CDB, the database must have an auto-login keystore.

There are no further requirements.

The Instructions

I am using the DB12 database from our hands-on lab. You can provision a lab and try it out yourself (for free). See the appendix for instructions on how to encrypt the DB12 database.

Old Server

Always use the latest version of AutoUpgrade.
Create a config file:
```
upg1.source_home=/u01/app/oracle/product/12.2.0.1
upg1.sid=DB12
upg1.target_version=19
```
- I don’t specify target_home because it does not exist on the old server. Instead, I specify target_version, so AutoUpgrade knows which checks to execute.

Check the database for upgrade readiness:

java -jar autoupgrade.jar -config DB12.cfg -mode analyze

Downtime starts.

Run the preupgrade fixups:

java -jar autoupgrade.jar -config DB12.cfg -mode fixups

Perform a clean shutdown of the database
```
shutdown immediate
```

New Server

There is only one server in the lab environment, so I can’t physically move to a new server. But by moving the instance manually to the new home, I can simulate the same behavior.

Move SPFile and password file to the new Oracle home on the new server. The below instructions work in the hands-on lab only:
```
export OLD_ORACLE_HOME=/u01/app/oracle/product/12.2.0.1
export NEW_ORACLE_HOME=/u01/app/oracle/product/19
export ORACLE_SID=DB12
cp $OLD_ORACLE_HOME/dbs/spfile$ORACLE_SID.ora $NEW_ORACLE_HOME/dbs
cp $OLD_ORACLE_HOME/dbs/orapw$ORACLE_SID $NEW_ORACLE_HOME/dbs
```
- If you copy over sqlnet.ora, you can remove encryption_wallet_location from it, because you will configure TDE using a newer method.
- There might be other database configuration files. The blog post on files to move during out-of-place patching gives you can overview of the files to move.

export NEW_ORACLE_HOME=/u01/app/oracle/product/19
export ORACLE_SID=DB12   
cp /etc/oratab /tmp/oratab
sed '/^'"$ORACLE_SID"':/d' /tmp/oratab > /etc/oratab
echo "$ORACLE_SID:$NEW_ORACLE_HOME:N" >> /etc/oratab
cat /etc/oratab

Use srvctl as well if you have Oracle Grid Infrastructure.

Move the database files (control files, redo logs, and data and temp files) to the new server.
- If you need to change any of the paths, see the appendix.
- Alternatively, unmount the storage from the old server and mount it on the new one.

I want to use the new wallet_root parameter to configure TDE. I copy the keystore files to a new location that matches the naming requirements of wallet_root:

export OLD_KEYSTORE=$ORACLE_BASE/admin/$ORACLE_SID/wallet
export NEW_KEYSTORE=$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde
mkdir -p $NEW_KEYSTORE
cp $OLD_KEYSTORE/cwallet.sso $NEW_KEYSTORE
cp $OLD_KEYSTORE/ewallet.p12 $NEW_KEYSTORE

You should consider moving any backup keystore files as well.

I start a new instance of the database in the new Oracle home and configure TDE using the new parameters:

export ORACLE_HOME=/u01/app/oracle/product/19
export PATH=$ORACLE_HOME/bin:$PATH
sqlplus / as sysdba<<EOF
   startup nomount
   alter system set wallet_root='$ORACLE_BASE/admin/$ORACLE_SID/wallet' scope=spfile;
   shutdown immediate
   startup nomount
   alter system set tde_configuration='KEYSTORE_CONFIGURATION=FILE' scope=both;
EOF

Start the instance in upgrade mode:

sqlplus / as sysdba<<EOF
   alter database mount;
   alter database open upgrade;
EOF

Create an AutoUpgrade config file:

upg1.target_home=/u01/app/oracle/product/19
upg1.sid=DB12

Start AutoUpgrade in upgrade mode:

java -jar autoupgrade.jar -config DB12.cfg -mode upgrade

That’s it! I just upgraded my encrypted Oracle Database and moved it to a new server.

Appendix

Keystore Type

You must have an auto-login database keystore to upgrade it on the new server. Check the keystore type in the source database:

select wrl_type, wallet_type from v$encryption_wallet;

AUTOLOGIN – You can copy the auto-login keystore file (cwallet.sso) from the old to the new server.
LOCAL_AUTOLOGIN – The keystore file is bound to the old server. You must create a new auto-login keystore on the new server.

To create a new local auto-login keystore:

startup mount
administer key management create local auto_login keystore ...;
shutdown immediate
startup upgrade

Hands-on Lab

If you want to try the procedure in our hands-on lab, you can use these instructions to encrypt the DB12 database.

Add TDE configuration to sqlnet.ora:

echo 'ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=$ORACLE_BASE/admin/$ORACLE_SID/wallet)))' >> $ORACLE_HOME/network/admin/sqlnet.ora

Create keystore directory:

mkdir -p $ORACLE_BASE/admin/$ORACLE_SID/wallet

Create the keystore and complete the TDE configuration:

sqlplus / as sysdba <<EOF
   --Restart to re-read sqlnet.ora with keystore setting
   shutdown immediate
   startup
   
   --Configure TDE
   ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '$ORACLE_BASE/admin/$ORACLE_SID/wallet' IDENTIFIED BY "<tde-keystore-pwd>";
   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<tde-keystore-pwd>";
   ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<tde-keystore-pwd>" WITH BACKUP;
   ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '$ORACLE_BASE/admin/$ORACLE_SID/wallet' IDENTIFIED BY "<tde-keystore-pwd>";

   --Create data
   create tablespace users2 encryption encrypt;
   grant dba to appuser identified by oracle;  
   create table appuser.t1 tablespace users2 as select * from all_objects;
EOF

Locations

In the instructions, I am using the same paths for the database files. If you need to change the location of the control file or redo logs, then it might be easier to create a PFile on the source and use that instead of the SPFile.

If you need to change the location of data or temp files, it might be easier to re-create the control file. In this case, you need an alter database backup controlfile to '/tmp/ctl.txt' on the source database. Edit the trace file to generate the create controlfile statement.

Tag: new server

How To Upgrade 100 PDBs And Move Them To Another Server