Upgrade Oracle Database 19c PDB to 26ai using Refreshable Clone PDB

Upgrade 5 Minutes

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

I’ll use refreshable clone PDB to build a copy of the PDB. This gives me an excellent rollback option. Plus, upgrading a single PDB is always faster than upgrading an entire CDB.

How to Upgrade and Convert

AutoUpgrade and refreshable clone PDB let you move the database to a different host. If you want to stay on the same host, just imagine the source and target hosts are the same.

1. Preparations

I’ve already prepared my database.

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

  1. In the source PDB, 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 target CDB via a database link.
    • I’ll drop it after the upgrade.
  2. In my target CDB, I create a database link connecting to my source PDB:
    create database link clonepdb 
connect to dblinkuser identified by ...
using 'source-db-alias';
  3. I create a config file on my target system. I call it upgrade26.cfg:
    global.global_log_dir=/home/oracle/autoupgrade/upgrade26
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.source_dblink.SALES=CLONEPDB 1800
upg1.target_pdb_name.SALES=NEWSALES
upg1.start_time=19/01/2038 03:14:07
upg1.parallel_pdb_creation_clause.SALES=2
upg1.target_pdb_copy_option.SALES=file_name_convert=NONE
upg1.drop_dblink=yes

    • If the source database is on a different system, set source_home to /tmp.

    • sid is the CDB where my PDB is currently running.

    • pdbs is the PDB that I want to upgrade. I can specify additional PDBs in a comma-separated list.

    • target_cdb is where the database ends up. This must be on 26ai already.

    • source_dblink.SALES is the name of the database link and the refresh rate in seconds.

    • target_pdb_name.SALES allows me to rename the PDB. I strongly recommend that you rename the PDB if your target 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. 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.SALES 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.SALES 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.

  4. 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 CDB.
    • There’s no outage. The source database remains open.
  5. Leave the AutoUpgrade session running.
    • Since the session might run for a while, better start it with tmux, screen, or similar.
    • Don’t use nohop because you must be able to interact with AutoUpgrade.
    • If your session disconnects, just restart AutoUpgrade with the same command.

2. Upgrade And Convert

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

  1. I create a new config file on the source system to run the pre-upgrade fixups. I call it fixups26.cfg:

    global.global_log_dir=/home/oracle/autoupgrade/fixups26
upg1.source_home=/u01/app/oracle/product/19
upg1.target_home=/u01/app/oracle/product/26
upg1.sid=CDB19
upg1.pdbs=SALES
    • If the target_home doesn’t exist because it’s on a remote system, you can use target_version=26 instead.

  2. I run the pre-upgrade fixups on the source database:

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

  3. 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.
    • Finally, starts the upgrade.

  4. 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.

  5. 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.

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

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

  7. I handle the post-upgrade tasks.

  8. I ensure that the source PDB is shut down.

    • If source and target CDBs are on the same system, AutoUpgrade stops the source PDB. You can override this using the parameter close_source.
    • If the source and target CDBs are on different systems, I must manually shut down the source PDB.
    • When I’m sure I won’t need the source PDB anymore, I can drop it.

  9. I can remove the database link user:

    drop user dblinkuser cascade;

  10. Recreate the connection services.

That’s It!

With AutoUpgrade, you can easily upgrade a single PDB. This is a faster option. For maximum protection, AutoUpgrade lets me preserve the source PDB 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 fully propagate 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.

There’s a separate post on that.

What If My Database Is Encrypted

AutoUpgrade fully supports encrypted databases. You must enter the source and target CDB keystore passwords into the AutoUpgrade keystore. You find the instructions here.

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?

There are no changes to the procedure if you have an Oracle RAC database. You must manually recreate services in the target CDB using srvctl.

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 to downgrade, be sure to set the compatible parameter in the target CDB to the same value as the source CDB.

Published

Leave a comment