Upgrade Oracle Database 19c PDB to 26ai

Upgrade 6 Minutes

Let me show you how to upgrade a single PDB to Oracle AI Database 26ai.

This is called an unplug-plug upgrade and is much faster than a full CDB upgrade.

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/SALES-CDB26
upg1.source_home=/u01/app/oracle/product/19
upg1.target_home=/u01/app/oracle/product/26
upg1.sid=CDB19
upg1.pdbs=SALES
upg1.target_cdb=CDB26
upg1.target_pdb_copy_option.SALES=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 current CDB.
    • target_cdb specifies the SID of the container where I plug into.
    • pdbs is the PDB that I want to upgrade. I can specify additional PDBs in a comma-separated list.
    • 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 SALES-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 unplugs from source CDB.
    • Finally, it plugs into the target CDB and upgrades the PDB.

  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 100 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/SALES-CDB26/cfgtoollogs/upgrade/auto/status/status.html
/home/oracle/autoupgrade/logs/SALES-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/SALES-CDB26/cfgtoollogs/upgrade/auto/status/status.log

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

  7. AutoUpgrade drops the PDB from the source CDB.

    • However, AutoUpgrade doesn’t remove the data files, so you must do this manually.
    • If I plug in and reuse the data files (omit target_pdb_copy_option), the data files remain in the source CDB location. Take care you don’t delete them by mistake; they are now used by the target CDB.

That’s It!

With AutoUpgrade, you can easily upgrade a single PDB using an unplug-plug upgrade. An unplug-plug upgrade is always a lot faster than a CDB upgrade, because you upgrade just that single PDB instead of a full CDB.

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

Happy upgrading!

Appendix

Rollback Options

When you perform an unplug-plug upgrade, 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 can use AutoUpgrade and the -restore parameter to recreate and restart the PDB in the source CDB.

java -jar autoupgrade.jar -config SALES-CDB26.cfg -restore -jobs 101
  • In the jobs parameter, I specify the job ID that originally upgraded the database.
  • AutoUpgrade now recreates the SALES PDB using the original data files.

Copy or Re-use Data Files

When you perform an unplug-plug upgrade, 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 PDB in source CDB. PDB in source CDB unusable. Rely on other rollback method.
AutoUpgrade Enable using target_pdb_copy_option. Default. Omit parameter target_pdb_copy_option.
Location after plug-in The data files are copied to the desired location. The data files are left in the source CDB location. Don’t delete them by mistake. Consider moving them using online data files move.
Syntax used CREATE PLUGGABLE DATABASE ... COPY CREATE PLUGGABLE DATABASE ... NOCOPY

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/SALES', '/u02/oradata/NEWSALES','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/SALES', '+DATA/NEWSALES') 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.

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. However, since you raise compatible, it means that 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.

Pre-plugin Backups

After doing an unplug-plug upgrade, 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 automatically.

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 handles it transparently. You must manually recreate services in the target CDB using srvctl.

What If I Use Oracle Restart?

No changes. You must manually recreate services in the target CDB using srvctl.

What If My Database Is Encrypted

AutoUpgrade fully supports upgrading an encrypted PDB.

You’ll need to input the source and target CDB keystore passwords 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 PDB time zone file after the actual upgrade. This 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. In multitenant, a PDB can use a different time zone file than the CDB.

  • target_pdb_name: AutoUpgrade renames the PDB. I must specify the original PDB name (SALES) as a suffix to the parameter:

    upg1.target_pdb_name.SALES=NEWSALES

    If I have multiple PDBs, I can specify target_pdb_name multiple times:

    upg1.pdbs=SALES,OLDNAME1,OLDNAME2
upg1.target_pdb_name.SALES=NEWSALES
upg1.target_pdb_name.OLDNAME1=NEWNAME1
upg1.target_pdb_name.OLDNAME2=NEWNAME2

  • keep_source_pdb: This parameter applies only if you copy the data files on plug-in. By default, AutoUpgrade drops the PDB from the source CDB before plugging into the target CDB. You can override that behaviour by setting the parameter to yes. In which case, the PDB is left in the source CDB in a shut down state.

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

Published

Leave a comment