Let me show you how to upgrade an encrypted non-CDB to Oracle AI Database 26ai. Since this release only supports the multitenant architecture, you must also convert it to a PDB.

To preserve the source database for rollback and to minimize downtime, I’ll use AutoUpgrade and refreshable clone PDBs.

How to Upgrade and Convert

AutoUpgrade and refreshable clone PDBs give you the option of moving the database to a different host. If you want to stay on the same host, just imagine source and target hosts are the same.

Start by familiarizing yourself with the restrictions on refreshable clone PDB for non-CDBs.

1. Preparations

I’ve already prepared my database.

I’ve also installed a new Oracle home and created a new CDB, or decided to use an existing one. The CDB can be on the same or a different system than the source non-CDB.

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;
   

   • I need the user so I can connect from the CDB via a database link.
   • I’ll drop it after the upgrade.
2. In my target CDB, as SYS, I create a database link connecting to my source non-CDB:

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

2. Analyze

I must run the pre-upgrade analysis on the source system.

1. I create an AutoUpgrade config file for the analysis. I call it upgrade26-analyze.cfg:

   global.global_log_dir=/home/oracle/autoupgrade/upgrade26-analyze
   upg1.source_home=/u01/app/oracle/product/19
   upg1.target_version=26
   upg1.sid=FTEX
   upg1.target_cdb=CDB26
   upg1.target_is_remote=yes
   

   • Since the target Oracle home doesn’t exist on my source system, I omit target_home.
   • Without the target Oracle home, AutoUpgrade can’t deduce the version I’m upgrading to, so I must specify target_version=26.
   • I specify target_is_remote=yes because the CDB is on another system. This causes AutoUpgrade to skip a few checks that it would normally run.
2. I start AutoUpgrade in analyze mode:

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

3. I check the pre-upgrade summary report:

   cd /home/oracle/autoupgrade/kraken/cfgtoollogs/upgrade/auto/status
   vi status.log
   

3. Initial Clone

1. I create a config file on my target system. I call it upgrade26.cfg:

   global.global_log_dir=/home/oracle/autoupgrade/upgrade26
   global.keystore=/home/oracle/autoupgrade/keystore
   upg1.source_home=/tmp
   upg1.source_base=/u01/app/oracle
   upg1.target_home=/u01/app/oracle/product/26
   upg1.sid=FTEX
   upg1.target_cdb=CDB26
   upg1.source_dblink.FTEX=CLONEPDB 1800
   upg1.target_pdb_name.FTEX=PDB1
   upg1.start_time=19/01/2038 03:14:07
   upg1.parallel_pdb_creation_clause.FTEX=2
   upg1.target_pdb_copy_option.FTEX=file_name_convert=NONE
   upg1.drop_dblink=yes
   

   • I set source_home to /tmp because it doesn’t exist on the target system. I set source_base to the Oracle base of my target system.
   • sid is the database that I want to upgrade and convert.
   • target_cdb is the SID of the database where the non-CDB ends up.
   • source_dblink.<sid> is the name of the database link and the refresh rate in seconds.
   • target_pdb_name.<sid> allows me to rename the database. I strongly recommend that you rename the database if your CDB is on the same system. Otherwise, you’ll have a service name collision to deal with.
   • start_time is when AutoUpgrade performs the final refresh and starts the upgrade/conversion. I set it far out in the future, so I can better control the final refresh using the proceed command. Leave a comment if you know what happens at the specified time. :-)
   • parallel_pdb_creation_clause.<sid> limits the number of parallel processes used by the CDB to make the initial copy. Set it at a reasonable level that doesn’t overload the source database.
   • target_pdb_copy_option.<sid> allows me to specify the location of the data files. I use OMF and let the database decide where to put the files.
   • drop_dblink instructs AutoUpgrade to drop the database link when it’s no longer needed.
2. I start the AutoUpgrade password console to load the target CDB keystore password:

   java -jar autoupgrade.jar -config upgrade26.cfg -load_password
   

   • This is required because my database is encrypted.
   • AutoUpgrade prompts me for the AutoUpgrade keystore password. This is a password to protect the AutoUpgrade keystore; not the database keystore.
3. I want to add the database keystore password of the target CDB:

   TDE> add CDB26
   

   • CDB26 is the SID of the database and matches the target_cdb parameter in the config file.
   • I must enter the database keystore password.
4. I save the database keystore password in the AutoUpgrade keystore:

   TDE> save
   

   • I agree to create an auto-login keystore and enter yes when prompted.
5. Exit from the password console:

   TDE> exit
   

6. Next, I start AutoUpgrade in deploy mode:

   java -jar autoupgrade.jar -config upgrade26.cfg -mode deploy
   

   • AutoUpgrade copies the data files over the database link.
   • Rolls the copies of the data files forward with redo from the source non-CDB.
   • There’s no outage. The source database remains open.
7. Leave the AutoUpgrade session running.
   • Since the session might run for a while, better start it with tmux, screen, or similar.
   • Don’t use nohup because you must be able to interact with AutoUpgrade.
   • If your session disconnects, just restart AutoUpgrade with the same command.

4. Upgrade And Convert

The maintenance window has started, and users have left the database.

1. On the source system, I run the pre-upgrade fixups on the source database:

   java -jar autoupgrade.jar -config upgrade26-analyze.cfg -mode fixups 
   

   • AutoUpgrade informs me that it can’t run certain preupgrade fixups because the target Oracle home doesn’t exist on the source system. This is expected and ignorable.

2. Next, I switch to the target system. From the AutoUpgrade console, I instruct AutoUpgrade to proceed with the upgrade:

   upg> proceed -job 100
   

   • AutoUpgrade performs a final refresh.
   • Then, it disconnects the PDB from the source.
   • Then, starts the upgrade and conversion.

3. While the job progresses, I monitor it:

   upg> lsj -a 30
   

   • The -a 30 option automatically refreshes the information every 30 seconds.
   • I can also use status -job 100 -a 30 to get detailed information about a specific job.

4. In the end, AutoUpgrade completes the upgrade:

   Job 101 completed
   ------------------- Final Summary --------------------
   Number of databases            [ 1 ]
   
   Jobs finished                  [1]
   Jobs failed                    [0]
   Jobs restored                  [0]
   Jobs pending                   [0]
   
   Please check the summary report at:
   /home/oracle/autoupgrade/upgrade26/cfgtoollogs/upgrade/auto/status/status.html
   /home/oracle/autoupgrade/upgrade26/cfgtoollogs/upgrade/auto/status/status.log
   

   • This includes the post-upgrade checks and fixups.

5. I review the Autoupgrade Summary Report. The path is printed to the console:

   vi /home/oracle/autoupgrade/upgrade26/cfgtoollogs/upgrade/auto/status/status.log
   

6. I take care of the post-upgrade tasks.

7. I update any profiles or scripts that use the database.

8. I ensure that the source non-CDB is shut down.

   • If source non-CDB and target CDB are on the same system, AutoUpgrade stops the source non-CDB. You can override this using the parameter close_source.
   • When I’m sure I won’t need the source non-CDB anymore, I can delete it.

9. I can remove the database link user:

   drop user dblinkuser cascade;
   

10. Recreate the connection services.

11. If you’ve configured Data Guard on your target CDB, you must restore the PDB on all standbys. Check the appendix for details.

That’s It!

With AutoUpgrade, you can easily upgrade your encrypted non-CDB and convert it to a PDB. For maximum protection, AutoUpgrade lets me preserve the source non-CDB in case I need to roll back.

Check the other blog posts related to upgrade to Oracle AI Database 26ai.

Happy upgrading!

Appendix

What If I Have Data Guard

Refreshable clone PDB doesn’t propagate fully to the standbys. The plug-in operation happens with deferred recovery.

After plug-in on the primary database, the standbys don’t protect the PDB. You must first restore the PDB to each standby database.

Also, check pages 210-221 in Move to Oracle Database 23ai – Everything you need to know about Oracle Multitenant – part 1.

Draining the Source Non-CDB

When your maintenance window starts, you must kick users off.

In a previous blog post, I gave an idea on how you can do that. Whatever you do, don’t restart the source database. It’ll break the refreshable clone PDB.

Does It Work Cross-Platform

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

What If My Database Is A RAC Database?

• Ensure that all instances can resolve the database link connection identifier and that the database link works from all instances. The CREATE PLUGGABLE DATABASE statement scales out on all instances for the initial cloning.
• In your config file, when specifying the sid parameter you must use the SID on the node where AutoUpgrade runs. If my database is called DB19 and it runs on host1 which is instance 1 in my cluster, I’d specify:

  upg1.sid=DB191
  

• Recreate services in the target CDB using srvctl. If you have many services, consider export/import of the services.

Other Config File Parameters

The config file shown above is a basic one. Let me address some of the additional parameters you can use.

• timezone_upg: AutoUpgrade upgrades the database time zone file after the actual upgrade. This requires an additional restart of the database and might take significant time if you have lots of TIMESTAMP WITH TIME ZONE data. If so, you can postpone the time zone file upgrade or perform it in a more time-efficient manner.

• before_action / after_action: Extend AutoUpgrade with your own functionality by using scripts before or after the job.

Compatible

During plug-in, the PDB automatically inherits the compatible setting of the target CDB. You don’t have to raise the compatible setting manually.

Typically, the target CDB has a higher compatible and the PDB raises it on plug-in. This means you don’t have the option of downgrading.

If you want to preserve the option of downgrading, be sure to set the compatible parameter in the target CDB to the same value as the source CDB.