At the recent Oracle DatabaseWorld at CloudWorld I spoke to several customers that had to upgrade to Oracle Database 19c and convert their non-CDB into the multitenant architecture.

Here is how to do it using Refreshable Clone PDBs.

My source database is:

• A non-CDB
• On Oracle Database 12.2 or newer

I want to:

• Upgrade to Oracle Database 19c
• Convert the database to a PDB
• Plug it into an existing CDB

The Problem With PDB Conversion

The conversion to multitenant does not offer the same rollback options as an upgrade. Normally, when you upgrade a database, you rely on Flashback Database as the primary rollback option. However, that does not work for conversion to multitenant.

When you plug your non-CDB into a CDB, the CDB makes changes to the data file headers. Those changes are irreversible and prevents you from ever using those data files in a non-CDB. Not even Flashback Database can revert the changes.

So, what are your rollback options?

• Restore a backup It might take longer than your organization can accept.
• Make a copy of the data files before conversion It requires disk space and a longer downtime window to copy the data files.

This is where Refreshable Clone PDBs come into play.

Refreshable Clone PDBs

Here is an overview of what AutoUpgrade does for you:

1. AutoUpgrade creates a PDB in the target CDB as a refreshable clone PDB of the source non-CDB.
2. The target CDB starts to copy the data files from the source non-CDB.
3. The target CDB refreshes the PDB. In other words, it rolls forward the data files using the redo from the source non-CDB.
4. Now, downtime starts. AutoUpgrade issues a final refresh to bring over the latest changes.
5. AutoUpgrade disconnects the refreshable clone PDB from its source. Now, the PDB is a real, stand-alone PDB. AutoUpgrade upgrades the PDB and converts it into a proper PDB.

If something happens during the upgrade or conversion and you want to roll back, simply start the original non-CDB. It is left completely untouched.

You can learn about the concept in detail in our AutoUpgrade 2.0 webinar:

Refreshable clone PDBs does not work for cross-endian migrations (like AIX to Linux), but cross-platform should work fine (like Windows to Linux).

How To

1. In the source non-CDB, I create a user:

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

2. In my target CDB, I create a database link connecting to my source non-CDB:

   create database link clonepdb 
      connect to dblinkuser identified by ...
      using 'source-db-alias';
   

   You can drop the database link after the migration.
3. I create an AutoUpgrade config file called noncdb1.cfg:

   upg1.source_home=/u01/app/oracle/product/12.2.0.1
   upg1.target_home=/u01/app/oracle/product/19
   upg1.sid=NONCDB1
   upg1.target_cdb=CDB1
   upg1.source_dblink.NONCDB1=CLONEPDB 600
   upg1.target_pdb_name.NONCDB1=PDB1
   upg1.start_time=25/09/2023 06:30:00
   

   • source_home and target_home is the Oracle Home of the source non-CDB and target CDB respectively.
   • sid is the source non-CDB that I want to upgrade and convert.
   • target_cdb is the CDB into which I want to plug in the non-CDB. You must create the CDB in advance or use an existing one.
   • source_dblink has the name of the database link (CLONEPDB) and the rate at which the target CDB brings over redo and rolls forward the copy (600 seconds or 10 minutes).
   • target_pdb_name specifies that I want to rename the non-CDB to PDB1 when I plug it in. You can leave this out if you want to keep the name.
   • start_time specifies when downtime starts. At this point, AutoUpgrade refreshes the PDB for the last time and then moves on with upgrade and PDB conversion.
4. Start AutoUpgrade in analyze mode on the source system:

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

5. Run AutoUpgrade in fixups mode on the source system:

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

   • This runs the fixups identified by AutoUpgrade in analyze mode. You can run this task even after you start AutoUpgrade in deploy mode. Just ensure that the fixups complete before the final refresh (as specified in the start_time paramter).
6. If there are no errors found in the analysis, I start AutoUpgrade in deploy mode:

   java -jar autoupgrade.jar -mode deploy noncdb1.cfg
   

   • AutoUpgrade copies the data files over the database link.
   • Rolls the copies of the data files forward with redo from the source non-CDB.
   • At one point, issues a final refresh and disconnects the PDB from the source non-CDB.
   • Upgrades and converts the database to a PDB.

Here’s a demo of it:

Words of Caution

Disconnect Users from Source Database

Right before the upgrade and conversion starts, AutoUpgrade executes a final refresh. The last redo from the source non-CDB is applied to ensure no data is lost. You must ensure that no users are connected to the source non-CDB after this time. Otherwise, that data will be lost.

AutoUpgrade starts the final refresh at the start time specified in the config file:

upg1.start_time=25/09/2023 06:30:00

You must be careful about disconnecting users from the source non-CDB. Remember, AutoUpgrade connects to the source non-CDB over a database link as a regular user (not SYS). This means the listener must be available, and you can’t enable restricted session or similar means.

Data Guard

If the target CDB is protected by Data Guard, special attention is needed to handle the standby databases. I explain the details in our AutoUpgrade 2.0 webinar:

Redo

The procedure relies on redo from the source non-CDB. Ensure that redo is kept in the Fast Recovery Area of the source non-CDB until it has been applied on the target PDB. Either postpone your archive backups or change the archive log deletion policy so the archive logs remain on disk.

Final Refresh

Check this blog post if you want to be in control over when the final refresh happens.

Services

You must recreate the services used in your connect strings.

Appendix

Further Reading

• Migrate to Multitenant with Refreshable Clones using AutoUpgrade