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

How to Upgrade and Convert

I’ve already prepared my database and installed a new Oracle home. I’ve also created a new container database or decided to use an existing one.

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

1. This is my AutoUpgrade config file:

   global.global_log_dir=/home/oracle/autoupgrade/logs/FTEX-CDB26
   upg1.source_home=/u01/app/oracle/product/19
   upg1.target_home=/u01/app/oracle/product/26
   upg1.sid=FTEX
   upg1.target_cdb=CDB26
   upg1.export_rman_backup_for_noncdb_to_pdb=yes
   upg1.target_pdb_name=PDBFTEX
   upg1.target_pdb_copy_option=file_name_convert=none
   

   • I specify the source and target Oracle homes. I’ve already installed the target Oracle home.
   • sid contains the SID of my database.
   • target_cdb specifies the SID of the container where I plug into.
   • export_rman_backup_for_noncdb_to_pdb instructs AutoUpgrade to export RMAN metadata using DBMS_PDB.EXPORTRMANBACKUP. This makes it easier to use pre-plugin backups (see appendix).
   • target_pdb_name tells AutoUpgrade to rename the PDB.
   • target_pdb_copy_option instructs AutoUpgrade to copy the data files on plug-in and generate new OMF names. If I omit the parameter, AutoUpgrade reuses the data files. See the appendix for more details on copying or re-using data files.
   • Check the appendix for additional parameters.

2. I start AutoUpgrade in deploy mode:

   java -jar autoupgrade.jar -config FTEX-CDB26.cfg -mode deploy
   

   • AutoUpgrade starts by analyzing the database for upgrade readiness and executes the pre-upgrade fixups.
   • Next, it creates a manifest file and shuts down the non-CDB.
   • Finally, it plugs the database in and follows with an upgrade and non-CDB to PDB 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/logs/FTEX-CDB26/cfgtoollogs/upgrade/auto/status/status.html
   /home/oracle/autoupgrade/logs/FTEX-	CDB26/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/logs/FTEX-CDB26/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. AutoUpgrade removes the non-CDB entry from /etc/oratab and Grid Infrastructure.

   • However, AutoUpgrade doesn’t remove:
     • Database files, like PFile, SPFile, password file, control file, and redo logs.
     • Database directory, like diagnostic_dest, adump, or db_recovery_file_dest.
     • Data files or temp files
   • I can remove the above file and directories when I’m sure that I won’t need a rollback.
   • If I plug in and reuse the data files (omit target_pdb_copy_option), the data files remain in the non-CDB location. Take care you don’t delete them by mistake; they are now used by the PDB.

That’s It!

With AutoUpgrade, you can easily upgrade your non-CDB and convert it to a PDB. For maximum flexibility, AutoUpgrade lets me copy or reuse the data files.

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

Happy upgrading!

Appendix

Rollback Options

When you convert a non-CDB to a PDB, you can’t use Flashback Database as a rollback method. You need to rely on other methods, like:

• Copy data files by using target_pdb_copy_option.
• RMAN backups.
• Storage snapshots.

In this blog post, I copied the data files (using target_pdb_copy_option). This means the original data files are left untouched. In case of a rollback, I just need to reinstate the non-CDB instance (FTEX).

java -jar autoupgrade.jar -config cdb1.cfg -restore -jobs 101

• In the jobs parameter, I specify the job ID that originally upgraded the database.
• AutoUpgrade now recreates the FTEX instance using the original files (data files, control file, redo logs, and so on).

Copy or Re-use Data Files

When you plug into a CDB and convert your database to a PDB, you must decide what to do with the data files.

	Copy	Re-use
Plug-in Time	Slow, needs to copy data files	Fast, re-uses existing data files
Disk space	Need room for a full copy of the data files	No extra disk space
Rollback	Source data files are left untouched. Re-open source database	Source database unusable. Rely on other rollback method.
AutoUpgrade	Default. Omit parameter target_pdb_copy_option	Enable using target_pdb_copy_option
Location after plug-in	The data files are left in the non-CDB location. Don’t delete them by mistake. Consider moving them using online data files move	The data files are copied to the desired location

target_pdb_copy_option

Use this parameter only when you want to copy the data files.

• target_pdb_copy_option=file_name_convert=('/u02/oradata/FTEX', '/u02/oradata/PDBFTEX','search-1','replace-1') When you have data files in a regular file system. The value is a list of pairs of search/replace strings.
• target_pdb_copy_option=file_name_convert=none When you want data files in ASM or use OMF in a regular file system. The database automatically generates new file names and puts data files in the right location.
• target_pdb_copy_option=file_name_convert=('+DATA/FTEX', '+DATA/PDBFTEX') This is a very rare configuration. Only when you have data files in ASM, but don’t use OMF. If you have ASM, I strongly recommend using OMF.

You can find further explanation in the documentation.

Move

The CREATE PLUGGABLE DATABASE statement also has a MOVE clause in addition to COPY and NOCOPY. In a regular file system, the MOVE clause works as you would expect. However, in ASM, it is implemented via copy-and-delete, so you might as well use the COPY option.

AutoUpgrade doesn’t support the MOVE clause.

Pre-plugin Backups

After converting a non-CDB to PDB, you can restore a PDB using a combination of backups from before and after the plug-in operation. Backups from before the plug-in is called pre-plugin backups.

A restore using pre-plugin backups is more complicated; however, AutoUpgrade eases that by exporting the RMAN backup metadata (config file parameter export_rman_backup_for_noncdb_to_pdb).

I suggest that you:

• Start a backup immediately after the upgrade, so you don’t have to use pre-plugin backups.
• Practice restoring with pre-plugin backups.

What If My Database Is A RAC Database?

There are no changes to the procedure if you have an Oracle RAC database. AutoUpgrade detects this and sets CLUSTER_DATABASE=FALSE at the appropriate time. It also removes the non-CDB from the Grid Infrastructure configuration.

What If I Use Oracle Restart?

No changes. AutoUpgrade detects this and automatically removes the non-CDB from the Grid Infrastructure configuration.

What If My Database Is Encrypted

AutoUpgrade fully supports upgrading an encrypted database.

You’ll need to input the non-CDB database keystore password into the AutoUpgrade keystore. You can find the details in a previous blog post.

In the container database, AutoUpgrade always adds the database encryption keys to the unified keystore. After the conversion, you can switch to an isolated keystore.

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.

• raise_compatible: If you want to raise the initialization parameter COMPATIBLE immediately after the upgrade, you can use this parameter. Don’t use it if you have standby databases, because there’s a specific procedure for raising COMPATIBLE in a Data Guard configuration. Don’t use it if you want to keep the option of downgrading.

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