Upgrade Oracle Database PDB 19c to 26ai with Data Guard and Re-using Data Files (Enabled Recovery)

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.

But what about Data Guard? I want to reuse the data files and plug in using enabled recovery. This ensures that my standby protects the PDB immediately.

Let’s see how it works.

Environment

The demo environment:

Two servers:
- COPENHAGEN (primary)
- AARHUS (standby)
Source CDB:
- SID: CDB19
- Primary unique name: CDB19_COPENHAGEN
- Standby unique name: CDB19_AARHUS
Target CDB:
- SID: CDB26
- Primary unique name: CDB26_COPENHAGEN
- Standby unique name: CDB26_AARHUS
PDB to upgrade: SALES

1. Prepare Standby

I’ve already prepared my database (SALES) and installed a new Oracle home. I’ve also created a new container database (CDB26) and configured it for Data Guard.

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

If I use Active Data Guard, I close my PDB (SALES) on the source standby (CDB19_AARHUS):
```
alter pluggable database SALES close instances=all;
```
I stop redo apply in my target standby (CDB26_AARHUS):
```
edit database cdb26_aarhus set state='apply-off';
```
- I turn off redo apply, so I can control when the target standby should claim the PDB data files.
- I must ensure the source standby (CDB19_AARHUS) has released the PDB data files before doing the plug-in on the target standby (CDB26_AARHUS).

2. Upgrade On Primary

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.manage_standbys_clause=standbys=all
```
- I specify the source and target Oracle homes.
- 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.
- I want to reuse the existing data files, so I omit target_pdb_copy_option.
- To plug in with enabled recovery, I set manage_standbys_clause=all.
- Check the appendix for additional parameters.
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 (CDB19_COPENHAGEN).
- Then, it plugs into the target CDB with enabled recovery (CDB26_COPENHAGEN).
- The plug-in doesn’t happen on the target standby (CDB26_AARHUS), because I stopped redo apply.
- Finally, it upgrades the PDB (SALES).
I wait until AutoUpgrade reaches the DBUPGRADE phase. I monitor progress:
```
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.
When AutoUpgrade is on the DBUPGRADE phase, it means that the PDB has been unplugged from the source CDB (CDB19_COPENHAGEN) and plugged into the target CDB (CDB26_COPENHAGEN).

3. Check Standby

I must ensure the source standby (CDB19_AARHUS) has applied the redo, which unplugs the PDB.

On the standby, I look in the source standby alert log:

tail -100f $ORACLE_BASE/diag/rdbms/cdb19_aarhus/CDB1/trace/alert_CDB19.log

I look for proof that SALES PDB has been unplugged:

2026-03-23T07:50:44.450680+00:00
SALES(3):Recovery deleting file #16:'/u02/oradata/CDB19_AARHUS/4DAD2FA764C642E4E0638338A8C0A72D/datafile/o1_mf_users_nw1vs832_.dbf' from controlfile.
SALES(3):Recovery dropped tablespace 'USERS'
SALES(3):Recovery dropped temporary tablespace 'TEMP'
SALES(3):Recovery deleting file #15:'/u02/oradata/CDB19_AARHUS/4DAD2FA764C642E4E0638338A8C0A72D/datafile/o1_mf_undotbs1_nw1vrgby_.dbf' from controlfile.
SALES(3):Recovery dropped tablespace 'UNDOTBS1'
SALES(3):Recovery deleting file #14:'/u02/oradata/CDB19_AARHUS/4DAD2FA764C642E4E0638338A8C0A72D/datafile/o1_mf_sysaux_nw1vrgbx_.dbf' from controlfile.
SALES(3):Recovery dropped tablespace 'SYSAUX'
SALES(3):Recovery deleting file #13:'/u02/oradata/CDB19_AARHUS/4DAD2FA764C642E4E0638338A8C0A72D/datafile/o1_mf_system_nw1vrgbg_.dbf' from controlfile.
SALES(3):Recovery dropped tablespace 'SYSTEM'
SALES(3):Recovery dropped pluggable database 'SALES'

Notice the last line informing me that the SALES PDB has been unplugged from my source standby.
The redo from the ALTER PLUGGABLE DATABASE ... UNPLUG command on the primary has been applied on the standby.
All PDB data files are now consistent and available for the target standby.

4. Standby Data Files

I must ensure the target standby (CDB26_AARHUS) can find the PDB data files.

The plug-in operation happens on the primary. AutoUpgrade uses a manifest file for the plug-in. The manifest file contains a list of all the data files on the primary, but there’s no information about the standby database.

How does the standby find the data files to use for the plug-in?

1. Regular File System

The standby (CDB26_AARHUS) expects to find the data files in the same location as on the primary (CDB26_COPENHAGEN).

During plug-in, I reused the data files. So, the primary data files are in the location of the source CDB (CDB19_COPENHAGEN):

/u02/oradata/CDB19_COPENHAGEN/SALES/system01.dbf
/u02/oradata/CDB19_COPENHAGEN/SALES/sysaux01.dbf
/u02/oradata/CDB19_COPENHAGEN/SALES/undo01.dbf
/u02/oradata/CDB19_COPENHAGEN/SALES/users01.dbf

However, on the standby (CDB19_AARHUS), the data files are here:

/u02/oradata/CDB19_AARHUS/SALES/system01.dbf
/u02/oradata/CDB19_AARHUS/SALES/sysaux01.dbf
/u02/oradata/CDB19_AARHUS/SALES/undo01.dbf
/u02/oradata/CDB19_AARHUS/SALES/users01.dbf

On the standby, I move the data files to the correct location:

mv /u02/oradata/CDB19_AARHUS/SALES /u02/oradata/CDB26_AARHUS/SALES

And use DB_FILE_NAME_CONVERT to redirect the files to the new location:
```
alter system set db_file_name_convert='/u02/oradata/CDB19_COPENHAGEN','/u02/oradata/CDB26_AARHUS' scope=both;
```
- Notice how I translate the source primary location to the target standby location.
- The plug-in operation only knows where the primary data files are, and expects the standby use the exact same location (which it doesn’t).

2. OMF In Regular File System

The standby (CDB26_AARHUS) expects to find the data files in the OMF location (db_create_file_dest).
On standby, I create the OMF location for the PDB in the target CDB (CDB26_AARHUS):
```
mkdir -p /u02/oradata/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A
```
- 4DB38AE91A244341E0638338A8C0934A is the GUID of the PDB.
- It doesn’t change when you move the PDB.
- You can find the GUID of the PDB in the primary: select name, guid from v$containers;.

I move the PDB data files from the source OMF location to the target OMF location:

mv /u02/oradata/CDB19_AARHUS/4DB38AE91A244341E0638338A8C0934A/datafile \
   /u02/oradata/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A/datafile

3. ASM

The standby (CDB26_AARHUS) expects to find the data files in the OMF location (db_create_file_dest).

On standby, I connect to the ASM instance:

export ORACLE_SID=+ASM1
sqlplus / as sysasm

I create the OMF location for the PDB in the target CDB (CDB26_AARHUS):
```
alter diskgroup data add directory '+DATA/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A';
alter diskgroup data add directory '+DATA/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A/DATAFILE';
```
- 4DB38AE91A244341E0638338A8C0934A is the GUID of the PDB.
- It doesn’t change when you move the PDB.
- You can find the GUID of the PDB in the primary: select name, guid from v$containers;.
For each data file in my PDB (including undo, excluding temp files), I must create an ASM alias, for instance:
```
alter diskgroup data add alias
'+DATA/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A/DATAFILE/users_273_1103046827'
for '+DATA/CDB19_AARHUS/4DB38AE91A244341E0638338A8C0934A/DATAFILE/users.273.1103046827';
```
- I must create an alias for each data file. I create the alias in the OMF location of the PDB in the target standby.
- The alias must not contain dots/punctuation (.). That would violate the OMF naming standard. Notice how I replaced those with an underscore.
- The alias points to the location of the data file in the source standby location.
- You can find a script to create the aliases in MOS note KB106558.

5. Standby Redo Apply

At this point:

The PDB data files are consistent and unplugged from the source standby (CDB19_AARHUS).
I’ve ensured that the target standby (CDB26_AARHUS) can find the data files.

I can now re-enable redo apply in my target standby (CDB26_AARHUS).

On the standby, I re-enable redo apply:

edit database cdb26_aarhus set state='apply-on';

I monitor the alert log (CDB26_AARHUS):

cd $ORACLE_BASE/diag/rdbms/cdb26_aarhus/CDB26/trace
tail -100f alert_CDB26.log

I ensure that the target standby (CDB26_AARHUS) finds and plugs in the PDB data files:

2026-03-23T07:52:26.550343+00:00
PR00 (PID:26567): Media Recovery Log /u01/app/oracle/CDB26_AARHUS/archivelog/2026_03_23/o1_mf_1_30_nw1w78oo_.arc [krd.c:10255]
Recovery created pluggable database SALES
SALES(3):Recovery scanning directory +DATA/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A/DATAFILE/ for any matching files
SALES(3):Successfully added datafile 12 to media recovery
SALES(3):Datafile #12: '+DATA/CDB26_AARHUS/4DB38AE91A244341E0638338A8C0934A/DATAFILE/o1_mf_system_nw1vrgbg_.dbf'

There should be one entry for each PDB data file.

6. Complete Upgrade

As the upgrade progresses, the redo is shipped to the target standby and applied.

I wait until 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.

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

I take care of the post-upgrade tasks.
AutoUpgrade unplugs the PDB from the source CDB.
- On the primary, the PDB data files are in the original location. In the directory structure of the source CDB.
- Take care you don’t delete them by mistake; they are now used by the target CDB.
- Optionally, move them into the correct location using online datafile move.
- The same applies to the standby if I use ASM. For regular file system, I moved the PDB data files to the correct location.

7. Check Standby

At this point, the standby (CDB26_AARHUS) protects my PDB.
I check the Data Guard config:
```
validate database CDB26_AARHUS;
```
Once my standby is in sync, I can do a switchover as the ultimate test:
```
switchover to CDB26_AARHUS;
```

Now, I connect to the new primary (CDB26_AARHUS) and ensure the PDB opens in read write mode and unrestricted:

select open_mode, restricted
from v$pdbs
where name='SALES';

OPEN_MODE     RESTRICTED
_____________ _____________
READ WRITE    NO

You can find the full procedure in (KB106558) Reusing the Source Standby Database Files When Plugging a PDB into the Primary Database of a Data Guard Configuration.

That’s It!

With AutoUpgrade, you can easily upgrade a single PDB using an unplug-plug upgrade. For maximum protection and to minimize downtime, you can reuse the data files on both primary and standby.

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:

RMAN backups.
Storage snapshots.
If you have multiple standbys, you can leave one behind.

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

Before starting redo apply on the standby, you must copy the keystore from the primary to the standby. Check (KB106558) Reusing the Source Standby Database Files When Plugging a PDB into the Primary Database of a Data Guard Configuration for details.

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: (default: Yes) 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
```
before_action / after_action: Extend AutoUpgrade with your own functionality by using scripts before or after the job.
Check the documentation for the full list.

Upgrade Oracle Database 19c PDB to 26ai with Data Guard and Restoring Data Files (Deferred Recovery)

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.

But what about Data Guard? I use deferred recovery, meaning I must restore the PDB after the upgrade.

Let’s see how it works.

1. Upgrade On Primary

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 new container database is configured for Data Guard.

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

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.
- I want to reuse the existing data files, so I omit target_pdb_copy_option.
- To plug in with deferred recovery, I can either omit manage_standbys_clause or set manage_standbys_clause=none.
- Check the appendix for additional parameters.
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.
- Then, it plugs into the target CDB with deferred recovery. At this point, the standby is not protecting the new PDB.
- Finally, it upgrades the PDB.
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.

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]

The following PDB(s) were created with standbys=none option. Refer to the postcheck result CDB19_COPENHAGEN_postupgrade.log for more details on manual actions needed.
SALES

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.
AutoUpgrade informs me that it plugged in with deferred recovery. To protect the PDB on the standby, I must restore it.

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

I take care of the post-upgrade tasks.
AutoUpgrade drops the PDB from the source CDB.
- The data files used by the target CDB are in the original location. In the directory structure of the source CDB.
- Take care you don’t delete them by mistake; they are now used by the target CDB.
- Optionally, move them into the correct location using online datafile move.

2. Restore PDB On Standby

I execute all commands on the same host – the standby system.

On the standby, I verify that recovery status is disabled:

SQL> select open_mode, recovery_status
     from v$pdbs where name='SALES';

OPEN_MODE    RECOVERY_STATUS
____________ __________________
MOUNTED      DISABLED

This means that I plugged in with deferred recovery.
The standby is not protecting this PDB.

Next, I connect to the standby using RMAN, and I restore the PDB:

connect target /
run{
   allocate channel disk1 device type disk;
   allocate channel disk2 device type disk;

   set newname for pluggable database SALES to new;

   restore pluggable database SALES
      from service <primary_service>
      section size 64G;
}

You can add more channels depending on your hardware.
Replace SALES with the name of your PDB.
<primary_service> is a connect string to the primary database.

Next, I connect to the standby database using Data Guard broker and turn off redo apply:
```
edit database <stdby_unique_name> set state='apply-off';
```
Back in RMAN, still connected to the standby, I switch to the newly restored data files:
```
switch pluggable database SALES to copy;
```
Then, I connect to the standby and generate a list of commands that will online all the data files:
```
alter session set container=SALES;
select 'alter database datafile '||''''||name||''''||' online;' from v$datafile;
```
- Save the commands for later.
- There should be one row for each data file.

If my standby is an Active Data Guard, I must restart it into MOUNT mode.

alter session set container=CDB$ROOT;
shutdown immediate
startup mount

Now, I can re-enable recovery and online the data files:

alter session set container=SALES;
alter pluggable database enable recovery;
alter database datafile <file1> online;
alter database datafile <file2> online;
...
alter database datafile <filen> online;

I must connect to the PDB.
I must execute the alter database datafile ... online command for each data file.

I turn on redo apply:

edit database <stdby_unique_name> set state='apply-on';

At this point, the standby protects my PDB.
After a minute or two, I check the Data Guard config:
```
validate database <stdby_unique_name>;
```
Once my standby is in sync, I can do a switchover as the ultimate test:
```
switchover to <stdby_unique_name>;
```

Now, I connect to the new primary and ensure the PDB opens in read write mode and unrestricted:

select open_mode, restricted
from v$pdbs
where name='SALES';

OPEN_MODE     RESTRICTED
_____________ _____________
READ WRITE    NO

You can find the full procedure in Making Use Deferred PDB Recovery and the STANDBYS=NONE Feature with Oracle Multitenant (KB90519). Check sections Steps for Preparing to enable recovery of the PDB and Steps required for enabling recovery on the PDB after the files have been copied.

That’s It!

With AutoUpgrade, you can easily upgrade a single PDB using an unplug-plug upgrade. The easiest way to handle the standby is to restore the pluggable database after the upgrade.

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 reuse the data files, so I must have an alternate rollback plan.

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.

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.

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.

Before restoring the pluggable database on the standby, you must copy the keystore from the primary to the standby.

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
```
before_action / after_action: Extend AutoUpgrade with your own functionality by using scripts before or after the job.
Check the documentation for the full list.

Multiple Standby Databases

You must restore the PDB to each standby database.

If you have multiple standby databases, it’s a lot of work for the primary to handle the restore pluggable database command from all standbys.

Imagine we have three standby databases. Here’s an alternative approach:

First, Standby 1 restores from primary.
Next, standby 2 restores from standby 1.
At the same time, standby 3 restores from primary.
This spreads the load throughout your databases, allowing you to complete faster.

Upgrade Oracle Database 19c CDB to 26ai with Data Guard – Standby Offline Method

Here’s how to upgrade an entire CDB to Oracle AI Database 26ai, including a standby database.

I’m using the Standby Offline Method (see appendix). The standby database is offline during the upgrade. This requires a little more downtime but adds an additional layer of safety.

1. Preparations

I’ve already prepared my database and installed a new Oracle home on both servers. The maintenance window has started, and users have left the database.

This is my AutoUpgrade config file:
```
global.global_log_dir=/home/oracle/autoupgrade/logs/CDB19
upg1.source_home=/u01/app/oracle/product/19
upg1.target_home=/u01/app/oracle/product/26
upg1.sid=CDB19
upg1.defer_standby_log_shipping=yes
```
- sid contains the name or SID of my database.
- I specify the source and target Oracle homes. I’ve already installed the target Oracle home.
- I use defer_standby_log_shipping to instruct AutoUpgrade to disable redo transport. This prevents the primary from transporting any upgrade redo to the standby.
- Check the appendix for additional parameters.
I disable Fast-Start Failover using Data Guard broker:
```
disable fast_start failover;
```

2. Prepare Standby

I stop redo apply:

edit database <stdby_unique_name> set state=apply-off;

I create a guaranteed restore point on the standby database.

create restore point stdby_before_upg
   guarantee flashback database;

3. Upgrade Primary

I update listener.ora on the primary host (see appendix). I change the ORACLE_HOME parameter in the static listener entry (suffixed _DGMGRL) so it matches my target Oracle home.
I reload the listener:
```
lsnrctl reload
```
I start AutoUpgrade in deploy mode:
```
java -jar autoupgrade.jar -config CDB19.cfg -mode deploy
```
- AutoUpgrade first sets a guaranteed restore point, then proceeds with the upgrade.
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.

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]

---- Drop GRP at your convenience once you consider it is no longer needed ----
Drop GRP from CDB1: drop restore point AUTOUPGRADE_9212_CDB1_COPENHAGEN1924000

---- Data Guard broker configuration is disabled. Enable it once ready to sync up standby database  ----
Enable log shipping against CDB1_COPENHAGEN, job100 using the following DGMGRL command: EDIT DATABASE CDB1_COPENHAGEN SET STATE=TRANSPORT-ON;

Please check the summary report at:
/home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.html
/home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.log

This includes the post-upgrade checks and fixups, incl. updating /etc/oratab and Grid Infrastructure configuration.
AutoUpgrade instructs me to re-enable redo transport when I’m satisfied with the upgrade.

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

vi /home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.log

I take care of the post-upgrade tasks.
I update any profiles or scripts that use the primary.

4. Upgrade Standby

I only proceed with this step if I’m happy about the upgrade on the primary.

I update listener.ora on the standby host (see appendix). I change the ORACLE_HOME parameter in the static listener entry (suffixed _DGMGRL) so it matches my target Oracle home.
I reload the listener:
```
lsnrctl reload
```
I remove the defer_standby_log_shipping from my AutoUpgrade config file. It doesn’t make any sense during the upgrade of the standby.
I start AutoUpgrade in deploy mode:
```
java -jar autoupgrade.jar -config CDB19.cfg -mode deploy
```
- AutoUpgrade restarts the standby in the new Oracle home.
- It also takes care of all config files.
- Plus, update /etc/oratab and Grid Infrastructure configuration.
I update any profiles or scripts that use the standby.

I re-enable redo transport and redo apply using Data Guard broker:

edit database <prmy_unique_name> set state=transport-on;
edit database <stdby_unique_name> set state=apply-on;

It will take a few minutes for the standby to catch up. I monitor using:

show database <stdby_unique_name>;
validate database <stdby_unique_name>;

When there is no transport and apply lag, my standby has caught up, and the overall upgrade is complete.

5. Finalizing

When I’m done testing the database – including application testing – and I decide that a rollback is not needed, I drop the restore points – from primary and standby.
I re-enable Fast-Start Failover using Data Guard broker:
```
enable fast_start failover;
```

That’s It!

With AutoUpgrade, you can easily upgrade your entire CDB even when you use Data Guard.

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

Happy upgrading!

Appendix

Different Methods

When upgrading with Data Guard, there are two approaches:

Standby Offline – Before the upgrade starts on the primary database, you shut down the standby database. You keep it shut down until the upgrade has completed on the primary database and you have finished your tests. When you are sure you will stay on the new release, the standby database is restarted and synchronized with the primary database. It will take some time before you can go live because the standby database must apply all the redo generated during the upgrade.
- If you need to fall back, you can use Flashback Database on the primary database. In addition, no matter what happens to the primary database, you still have the standby database immediately ready in the pre-upgrade state.
- My team recommends this method. We prefer to sacrifice a little downtime to achieve even better protection.
Maximum Availability Architecture (MAA) – The standby database is open and applies redo while the primary database is upgraded. This means that the standby database is closely following the primary database. You can go live very soon after the upgrade completes because there is little or very little apply lag.
- The downside is when you must fall back. In that case, you have two databases to bring back in time with Flashback Database. In the very unlikely event that something happens during flashback on both databases, you may need to restore your backup.
- The MAA team recommends this method as it guarantees the lowest downtime.

Standby Offline	MAA
Maximum protection	Minimum downtime
Upgrade team recommendation	MAA recommendation
Redo transport deferred	Redo transport enabled
Redo apply stopped	Redo apply active
Protected by offline standby and guaranteed restore point	Protected by guaranteed restore point
	AutoUpgrade default

Static Listener Entry

In this blog post, I update the static listener entries required by Data Guard broker (suffixed DGMGRL). My demo environment doesn’t use Oracle Restart or Oracle Grid Infrastructure, so this entry is mandatory.

If you use Oracle Restart or Oracle Grid Infrastructure, such entry is no longer needed.

Oracle Data Guard Broker and Static Service Registration (KB142582)

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 updates the Grid Infrastructure configuration.

For warp-speed upgrades, take a look at distributed upgrade.

What If I Use Oracle Restart?

No changes. AutoUpgrade detects this and automatically updates the Grid Infrastructure configuration.

What If My Database Is Encrypted

You must use an auto-login keystore. AutoUpgrade checks this during the pre-upgrade analysis.

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.
em_target_name: Allow AutoUpgrade to create blackouts before restarting the database and to update the target configuration after the upgrade. Requires a local installation of emcli. See this blog post for details.
rman_catalog_connect_string: Relevant for databases that store backup metadata in a recovery catalog. Upgrades the recovery catalog schema following an upgrade. See this blog post for details.

Upgrade Oracle Database 19c CDB to 26ai with Data Guard – MAA Method

Here’s how to upgrade an entire CDB to Oracle AI Database 26ai, including all standby databases.

I’m using the MAA Method (see appendix). The standby database is up during the upgrade and continuously applies redo. This gives me shorter downtime compared to the alternative.

1. Preparations

I’ve already prepared my database and installed a new Oracle home on both servers. The maintenance window has started, and users have left the database.

This is my AutoUpgrade config file:
```
global.global_log_dir=/home/oracle/autoupgrade/logs/CDB19
upg1.source_home=/u01/app/oracle/product/19
upg1.target_home=/u01/app/oracle/product/26
upg1.sid=CDB19
```
- sid contains the name or SID or my database.
- I specify the source and target Oracle homes. I’ve already installed the target Oracle home.
- Check the appendix for additional parameters.
I disable Fast-Start Failover using Data Guard broker:
```
disable fast_start failover;
```

2. Upgrade Standby

I update listener.ora on the standby host (see appendix). I change the ORACLE_HOME parameter in the static listener entry (suffixed _DGMGRL) so it matches my target Oracle home.
I reload the listener:
```
lsnrctl reload
```

I create a guaranteed restore point on the standby database.

alter database recover managed standby database cancel;
create restore point stdby_before_upg guarantee flashback database;
alter database recover managed standby database disconnect from session;

I don’t want to rely on restore point propagation.

I start AutoUpgrade in deploy mode:
```
java -jar autoupgrade.jar -config CDB19.cfg -mode deploy
```
- AutoUpgrade restarts the standby in the new Oracle home.
- It also takes care of all config files.
- Plus, update /etc/oratab and Grid Infrastructure configuration.
I update any profiles or scripts that use the standby.
I use Data Guard broker to ensure that my standby is still applying logs:
```
validate database <stdby_unique_name>;
```

3. Upgrade Primary

I update listener.ora on the primary host (see appendix). I change the ORACLE_HOME parameter in the static listener entry (suffixed _DGMGRL) so it matches my target Oracle home.
I reload the listener:
```
lsnrctl reload
```
I start AutoUpgrade in deploy mode:
```
java -jar autoupgrade.jar -config CDB19.cfg -mode deploy
```
- AutoUpgrade starts by setting a guaranteed restore point and then proceeds with the upgrade.
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.

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]

---- Drop GRP at your convenience once you consider it is no longer needed ----
Drop GRP from CDB19: drop restore point AUTOUPGRADE_9212_CDB191927000

Please check the summary report at:
/home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.html
/home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.log

This includes the post-upgrade checks and fixups, incl. updating /etc/oratab and Grid Infrastructure configuration.

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

vi /home/oracle/autoupgrade/logs/CDB19/cfgtoollogs/upgrade/auto/status/status.log

I take care of the post-upgrade tasks.
I update any profiles or scripts that use the primary.

4. Finalizing

When I’m done testing the database – including application testing – and I decide that a rollback is not needed, I drop the restore points – from primary and standby.
I re-enable Fast-Start Failover using Data Guard broker:
```
enable fast_start failover;
```

That’s It!

With AutoUpgrade, you can easily upgrade your entire CDB even when you use Data Guard.

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

Happy upgrading!

Appendix

Different Methods

When upgrading with Data Guard, there are two approaches:

Standby Offline – Before the upgrade starts on the primary database, you shut down the standby database. You keep it shut down until the upgrade has completed on the primary database and you have finished your tests. When you are sure you will stay on the new release, the standby database is restarted and synchronized with the primary database. It will take some time before you can go live because the standby database must apply all the redo generated during the upgrade.
- If you need to fall back, you can use Flashback Database on the primary database. In addition, no matter what happens to the primary database, you still have the standby database immediately ready in the pre-upgrade state.
- My team recommends this method. We prefer to sacrifice a little downtime to achieve even better protection.
Maximum Availability Architecture (MAA) – The standby database is open and applies redo while the primary database is upgraded. This means that the standby database is closely following the primary database. You can go live very soon after the upgrade completes because there is little or very little apply lag.
- The downside is when you must fall back. In that case, you have two databases to bring back in time with Flashback Database. In the very unlikely event that something happens during flashback on both databases, you may need to restore your backup.
- The MAA team recommends this method as it guarantees the lowest downtime.

Standby Offline	MAA
Maximum protection	Minimum downtime
Upgrade team recommendation	MAA recommendation
Redo transport deferred	Redo transport enabled
Redo apply stopped	Redo apply active
Protected by offline standby and guaranteed restore point	Protected by guaranteed restore point
	AutoUpgrade default

Static Listener Entry

If you use Oracle Restart or Oracle Grid Infrastructure, such entry is no longer needed.

Oracle Data Guard Broker and Static Service Registration (KB142582)

What If I Have Multiple Standbys?

Repeat step Upgrade Standby for each standby before moving on with the next step Upgrade Primary.
This also applies if you have cascading standbys or use far-sync instances.

What About Rolling Upgrades?

This is a very different technique. You can learn more in Virtual Classroom #10: Zero Downtime Operations of Oracle Database.

What If My Database Is A RAC Database?

For warp-speed upgrades, take a look at distributed upgrade.

What If I Use Oracle Restart?

No changes. AutoUpgrade detects this and automatically updates the Grid Infrastructure configuration.

What If My Database Is Encrypted

You must use an auto-login keystore. AutoUpgrade checks this during the pre-upgrade analysis.

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.
em_target_name: Allow AutoUpgrade to create blackouts before restarting the database and to update the target configuration after the upgrade. Requires a local installation of emcli. See this blog post for details.
rman_catalog_connect_string: Relevant for databases that store backup metadata in a recovery catalog. Upgrades the recovery catalog schema following an upgrade. See this blog post for details.

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

I’ve already shown you how to upgrade a single PDB to Oracle AI Database 26ai using refreshable clone PDB.

But what about Data Guard? Refreshable clone PDB supports only deferred recovery, which means I must restore the PDB after the upgrade.

Let’s see how it works.

Upgrade

For the upgrade, I follow the procedure for a non-Data Guard upgrade.

In my AutoUpgrade config file, I must either:
- Omit manage_standbys_clause.
- Or, set it to manage_standbys_clause=none.
Both methods trigger AutoUpgrade to plug in with deferred recovery, which is the only supported option when using refreshable clone PDB.

Once the upgrade completes, I can proceed and restore the PDB to my standby database.

Standby Database

I execute all commands on the same host – the standby system.

On the standby, I verify that recovery status is disabled:

SQL> select open_mode, recovery_status
     from v$pdbs where name='NEWPDB1';

OPEN_MODE    RECOVERY_STATUS
____________ __________________
MOUNTED      DISABLED

This means that I plugged in with deferred recovery.
The standby is not protecting this PDB.

Next, I connect to the standby using RMAN, and I restore the PDB:

connect target /
run{
   allocate channel disk1 device type disk;
   allocate channel disk2 device type disk;

   set newname for pluggable database NEWPDB1 to new;

   restore pluggable database NEWPDB1
      from service <primary_service>
      section size 64G;
}

You can add more channels depending on your hardware.
Replace NEWPDB1 with the name of your PDB.
<primary_service> is a connect string to the primary database.

Next, I connect to the standby database using Data Guard broker and turn off redo apply:
```
edit database <stdby_unique_name> set state='apply-off';
```
Back in RMAN, still connected to the standby, I switch to the newly restored data files:
```
switch pluggable database NEWPDB1 to copy;
```
Then, I connect to the standby and generate a list of commands that will online all the data files:
```
alter session set container=NEWPDB1;
select 'alter database datafile '||''''||name||''''||' online;' from v$datafile;
```
- Save the commands for later.
- There should be one row for each data file.

If my standby is an Active Data Guard, I must restart it into MOUNT mode.

alter session set container=CDB$ROOT;
shutdown immediate
startup mount

Now, I can re-enable recovery and online the data files:

alter session set container=NEWPDB1;
alter pluggable database enable recovery;
alter database datafile <file1> online;
alter database datafile <file2> online;
...
alter database datafile <filen> online;

I must connect to the PDB.
I must execute the alter database datafile ... online command for each data file.

I turn on redo apply:

edit database <stdby_unique_name> set state='apply-on';

At this point, the standby protects my PDB.
After a minute or two, I check the Data Guard config:
```
validate database <stdby_unique_name>;
```
Once my standby is in sync, I can do a switchover as the ultimate test:
```
switchover to <stdby_unique_name>;
```

Now, I connect to the new primary and ensure the PDB opens in read write mode and unrestricted:

select open_mode, restricted
from v$pdbs
where name='NEWPDB1';

OPEN_MODE     RESTRICTED
_____________ _____________
READ WRITE    NO

You can find the full procedure in Making Use Deferred PDB Recovery and the STANDBYS=NONE Feature with Oracle Multitenant (KB90519). Check sections Steps for Preparing to enable recovery of the PDB and Steps required for enabling recovery on the PDB after the files have been copied.

That’s It!

Refreshable clone PDB is a great way of upgrading a single PDB. It’s very easy, but you must take care of your standby afterward.

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

Happy upgrading!

Appendix

Multiple Standby Databases

You must restore the PDB to each standby database.

If you have multiple standby databases, it’s a lot of work for the primary to handle the restore pluggable database command from all standbys.

Imagine we have three standby databases. Here’s an alternative approach:

First, Standby 1 restores from primary.
Next, standby 2 restores from standby 1.
At the same time, standby 3 restores from primary.
This spreads the load throughout your databases, allowing you to complete faster.

What If My Database Is Encrypted

AutoUpgrade handles the keys in the primary database.

After the upgrade, but before you begin the restore, you must copy the database keystore from the primary to the standby.

What If My Database Is A RAC Database?

Works on Oracle RAC Database as well.

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

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.

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.

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';

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

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.

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

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

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

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.

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

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

I handle the post-upgrade tasks.
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.
I can remove the database link user:
```
drop user dblinkuser cascade;
```
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.

Upgrade Oracle Database 19c PDB to 26ai

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.

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

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.

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

I take care of the post-upgrade tasks.
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

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.

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.

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.

Upgrade Oracle Database 19c Non-CDB to 26ai and Convert to PDB with Data Guard and Reusing Data Files (Enabled Recovery)

Let me show you how to upgrade an Oracle Database 19c non-CDB with Data Guard to Oracle AI Database 26ai.

I reuse data files on the primary database.
I also reuse the data files on the standby database (enabled recovery).
This is a more complex produced compared to deferred recovery. However, the PDB is immediately protected by the standby after plug-in.

The demo environment:

Two servers:
- COPENHAGEN (primary)
- AARHUS (standby)
Source non-CDB:
- SID: DB19
- Primary unique name: DB19_COPENHAGEN
- Standby unique name: DB19_AARHUS
- Oracle home: /u01/app/oracle/product/dbhome_19_27
Target CDB:
- SID: CDB26
- Primary unique name: CDB26_COPENHAGEN
- Standby unique name: CDB26_AARHUS
- Oracle home: /u01/app/oracle/product/dbhome_26_1
Data Guard broker manages the Data Guard configuration.
Oracle Restart (Grid Infrastructure) manages the databases.

You can still use the procedure if you don’t use Data Guard broker or Grid Infrastructure. Just be sure to change the commands accordingly.

1. Preparations On Primary

I’ve already prepared my database and installed a new Oracle home. I’ve also created a new CDB or decided to use an existing one. The CDB is also configured for Data Guard.

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

I create an AutoUpgrade config file. I call it upgrade26.cfg:
```
global.global_log_dir=/home/oracle/autoupgrade/upgrade26
upg1.source_home=/u01/app/oracle/product/dbhome_19_27
upg1.target_home=/u01/app/oracle/product/dbhome_26_1
upg1.sid=DB19
upg1.target_cdb=CDB26
upg1.manage_standbys_clause=standbys=all
upg1.export_rman_backup_for_noncdb_to_pdb=yes
```
- I specify the source and target Oracle homes. These are the Oracle homes of the source non-CDB and target CDB, respectively.
- sid contains the name of my database.
- target_cdb is the name of the CDB where I want to plug in.
- manage_standbys_clause=standbys=all instructs AutoUpgrade to plug the PDB in with enabled recovery.
- 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).

2. Preparations On Standby

My standby database uses ASM. This complicates the plug-in on the primary because the standby database doesn’t know where to find the data files.

I solve this with ASM aliases. This allows the standby CDB to find the data files from the standby non-CDB and reuse them.

On the standby, I connect to the non-CDB and get a list of all data files:
```
select name from v$datafile;
```
I also find the GUID of my non-CDB:
```
select guid from v$containers;
```
- The GUID doesn’t change in a Data Guard environment. It’s the same in all database.
Then I switch to the ASM instance on the standby host:
```
export ORACLE_SID=+ASM1
sqlplus / as sysasm	  
```
Here, I create the directories for the OMF location of the future PDB (the non-CDB you are about to plug-in). I insert the GUID found above:
```
alter diskgroup data add directory '+DATA/CDB26_AARHUS/<GUID>';
alter diskgroup data add directory '+DATA/CDB26_AARHUS/<GUID>/DATAFILE';
```
- Notice how the CDB database unique name (CDB26_AARHUS) is part of the path.
- During plug-in, the database keeps its GUID. It never changes.
For each data file in my source non-CDB (including undo, excluding temp files), I must create an ASM alias, for instance:
```
alter diskgroup data add alias
   '+DATA/CDB26_AARHUS/<GUID>/DATAFILE/users_273_1103046827'
   for '+DATA/DB19_AARHUS/DATAFILE/users.273.1103046827';
```
- I must create an alias for each data file. I create the alias in the OMF location of the future PDB in the standby CDB.
- The alias must not contain dots/punctuation (.). That would be a violation of the OMF naming standard. Notice how I replaced those with an underscore.
- The alias points to the location of the data file in the standby non-CDB location.
- You can find a script to create the aliases in MOS note KB117147.

I stop redo apply in the standby non-CDB:

edit database 'DB19_AARHUS' set state='apply-off';

If my standby is open (Active Data Gurd), I restart in MOUNT:

srvctl stop db -d DB19_AARHUS -o immediate
srvctl start db -d DB19_AARHUS -o mount

3. Upgrade Primary

On the primary, I start the upgrade:
```
java -jar autoupgrade.jar -mode deploy -config upgrade26.cfg
```
- AutoUpgrade re-analyzes my non-CDB and executes the pre-upgrade fixups.
- Next, AutoUpgrade mounts the non-CDB and flushes redo to all standbys.
- Then, it opens the non-CDB in read-only, generates the manifest file and shuts down.
- Finally, AutoUpgrade stops the job.

AutoUpgrade prints the following message:

----------------- Continue with the manual steps -----------------
There is a job with manual steps pending.
The checkpoint change number is 2723057 for database DB19.
For the standby database <DB19_AARHUS>, use the checkpoint number <2723057> to recover the database.

You can find the SCN information in:
/home/oracle/autoupgrade/upgrade26/DB19/101/drain/scn.json
Once these manual steps are completed, you can resume job 101
------------------------------------------------------------------

At this point, all data files on the primary non-CDB is consistent at a specified SCN, 2723057.
I must recover the standby data files to the same SCN.

On the standby host, I connect to the non-CDB:
```
alter database recover managed standby database
until change 2723057;
```
- until change is set to the SCN provided by AutoUpgrade.
- The standby now recovers all data files to the exact same SCN as the primary. This is a requirement for re-using the data files on plug-in.
I verify that no data files are at a different SCN:
```
select file#
from v$datafile_header
where checkpoint_change# != 2723057;
```
- checkpoint_change# is the SCN specified by AutoUpgrade.
- The query should return no rows.
I shut down the standby non-CDB and removes the database configuration:
```
srvctl stop database -d DB19_AARHUS -o immediate
srvctl remove database -d DB19_AARHUS -noprompt
```
- I remove the database from /etc/oratab as well.
- From this point, the standby non-CDB must not start again.
- The standby CDB will use the data files.
Back on the primary, in the AutoUpgrade console, I instruct AutoUpgrade to continue the plug-in, upgrade and conversion.
```
upg> resume -job 101
```
- AutoUpgrade plugs the non-CDB into the CDB.
- The plug-in operation propagates via redo to the standby.

On the standby, I verify that the standby CDB found the data files on plug-in. I find the following in the alert log:

2025-12-18T16:08:28.772125+00:00
Recovery created pluggable database DB19
DB19(3):Recovery scanning directory +DATA/CDB26_AARHUS/<GUID>/DATAFILE for any matching files.
DB19(3):Recovery created file +DATA/CDB26_AARHUS/<GUID>/DATAFILE/system_289_1220179503
DB19(3):Successfully added datafile 12 to media recovery
DB19(3):Datafile #12: '+DATA/CDB26_AARHUS/<GUID>/DATAFILE/system_289_1220179503'
DB19(3):Recovery created file +DATA/CDB26_AARHUS/<GUID>/DATAFILE/sysaux_291_1220179503
DB19(3):Successfully added datafile 13 to media recovery
DB19(3):Datafile #13: '+DATA/CDB26_AARHUS/<GUID>/DATAFILE/sysaux_291_1220179503'

I can see that the standby CDB scans the OMF location (+DATA/CDB26_AARHUS/<GUID>/DATAFILE) for the data files.
However, the data files are in the non-CDB location (+DATA/DB19_AARHUS/DATAFILE).
For each of the data files, the standby finds the alias that I created, and plugs it with those.

Back on the primary, I wait for AutoUpgrade to complete the plug-in, upgrade and PDB conversion. In the end, AutoUpgrade prints the following:

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

The non-CDB (DB19) is now a PDB in my CDB (CDB26).
AutoUpgrade removes the non-CDB (DB19) registration from /etc/oratab and Grid Infrastruction on the primary. I’ve already done that for the standby.

4. Check Data Guard

On the standby CDB, ensure that the PDB is MOUNTED and recovery status is ENABLED:

--Should be MOUNTED, ENABLED
select open_mode, recovery_status 
from   v$pdbs 
where  name='DB19';

I also ensure that the recovery process is running:

--Should be APPLYING_LOG
select process, status, sequence# 
from   v$managed_standby
where  process like 'MRP%';

Next, I use Data Guard broker (dgmgrl) to validate my configuration:
```
validate database "CDB26_COPENHAGEN"
validate database "CDB26_AARHUS"
```
- Both databases must report that they are ready for switchover.
Optionally, but strongly recommended, I perform a switchover:
```
switchover to "CDB26_AARHUS"
```

The former standby (CDB26_AARHUS) is now primary. I verify that my PDB opens:

alter pluggable database DB19 open;

--Must return READ WRITE, ENABLED, NO
select open_mode, recovery_status, restricted
from   v$pdbs
where  name='DB19';

If something went wrong previously in the process, the PDB won’t open.

5. Post-upgrade Tasks

I take care of the post-upgrade tasks.
I update any profiles or scripts that use the database.
I clean up and remove the old source non-CDB (DB19). On both primary and standby, I remove:
- Database files, like PFile, SPFile, password file, control file, and redo logs.
- Database directory, like diagnostic_dest, adump, or db_recovery_file_dest.
- Since I reused the data files in my CDB, I don’t delete those.

Final Words

I’m using AutoUpgrade for the entire upgrade; nice and simple. AutoUpgrade helps me recover the non-CDB standby database, so I can reuse the data files on all database in my Data Guard config.

When I reuse the data files, I no longer have the non-CDB for rollback. Be sure to plan accordingly.

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

Happy upgrading!

Appendix

What Happens If I Make a Mistake?

If the standby database fails to find the data files, the recovery process stops. Not only for the recently plugged-in PDBs, but for all PDBs in the CDB.

This is, of course, a critical situation!

I ensure to perform the operation correctly and double-check afterward (and then check again).
If I have Active Data Guard and PDB Recovery Isolation turned on, recovery stops only in the newly plugged-in PDB. The CDB continues to recover the other PDBs.

Data Files in ASM or OMF in Regular File System

Primary Database

When I create the PDB, I’m re-using the data files. The data files are in the OMF location of the non-CDB database, e.g.:
```
+DATA/DB19_COPENHAGEN/DATAFILE
```
However, the proper OMF location for my PDB is:
```
+DATA/CDB26_COPENHAGEN/<PDB GUID>/DATAFILE
```
The CDB doesn’t care about this anomaly. However, if I want to conform to the OMF naming standard, I must move the data files. Find the data files:
```
select file#, name from v$datafile;
```
Use online datafile move to move those files in the wrong location. The database automatically generates a new OMF name:
```
alter database move datafile <file#>;
```
- Online data file move creates a copy of the data files before switching to the new file and dropping the old one. So, I need additional disk space, and the operation takes time while the database copies the file.

Standby Database

The data files are in the wrong OMF location, like on the primary.

I can use online data file move on the standby database as well. However, I must stop redo apply and open the standby database to do that. If I don’t have a license for Active Data Guard, I must stop redo apply before opening the database.

Stop redo apply:

edit database 'CDB26_AARHUS' set state='apply-off';

Open the standby CDB and PDB:

alter database open;
alter pluggable database DB19 open;

Find the data files:

alter session set container=DB19;
select file#, name from v$datafile;

Move those data files that are in the wrong location. This command also removes the original file and the alias:
```
alter database move datafile <file#>;
```
Restart the standby CDB in mount mode. If I have Active Data Guard, I leave the standby database in OPEN mode:
```
srvctl stop database -d CDB26_AARHUS
srvctl start database -d CDB26_AARHUS -o mount
```

Restart redo apply:

edit database 'CDB26_AARHUS' set state='apply-on';

There are two things to pay attention to:

I must open the standby database. If redo apply is turned off, I can open the standby database with a license for Active Data Guard. Be sure not to violate your license.
I must turn off redo apply while I perform the move. Redo transport is still active, so the standby database receives the redo logs. However, apply lag increases while I move the files. In case of a switchover or failover, I need more time to close the apply gap.

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:

RMAN backups
Storage snapshots
Additional standby database (another source non-CDB standby, which you leave behind)
Refreshable clone PDB

What If I Have Multiple Standby Databases?

You must repeat the relevant steps for each standby database.

You can mix and match standbys with deferred and enabled recovery. Let’s say that you want to use enabled recovery on DR standbys and deferred recovery on the reporting standbys.

Role	Name	Method
Local DR	CDB26_COPENHAGEN2	Enabled recovery
Local reporting	CDB26_COPENHAGENREP	Deferred recovery
Remote DR	CDB26_AARHUS	Enabled recovery
Remote reporting	CDB26_AARHUSREP	Deferred recovery

You would set the following in your AutoUpgrade config file:

upg1.manage_standbys_clause=standbys=CDB26_COPENHAGEN2,CDB26_AARHUS

You would need to merge the two procedures together. This is left as a reader’s exercise.

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.

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.

Transparent Data Encryption (TDE)

AutoUpgrade fully supports upgrading an encrypted database. I can still use the above procedure with a few changes.

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.
At one point, you must copy the keystore to the standby database, and restart it. Check the MOS note KB117147 for additional details.

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.

Upgrade Oracle Database 19c Non-CDB to 26ai and Convert to PDB with Data Guard and Restoring Data Files (Deferred Recovery)

Let me show you how to upgrade an Oracle Database 19c non-CDB with Data Guard to Oracle AI Database 26ai.

I reuse data files on the primary database.
But restore the data files on the standby database after the migration (deferred recovery).

The demo environment:

Two servers:
- COPENHAGEN (primary)
- AARHUS (standby)
Source non-CDB:
- SID: DB19
- Primary unique name: DB19_COPENHAGEN
- Standby unique name: DB19_AARHUS
- Oracle home: /u01/app/oracle/product/dbhome_19_27
Target CDB:
- SID: CDB26
- Primary unique name: CDB26_COPENHAGEN
- Standby unique name: CDB26_AARHUS
- Oracle home: /u01/app/oracle/product/dbhome_26_1
Data Guard broker manages the Data Guard configuration.
Oracle Restart (Grid Infrastructure) manages the databases.

You can still use the procedure if you don’t use Data Guard broker or Grid Infrastructure. Just be sure to change the commands accordingly.

1. Upgrade and Convert

I’ve already prepared my database and installed a new Oracle home. I’ve also created a new CDB or decided to use an existing one. The CDB is also configured for Data Guard.

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

I ensure my standby database has received and applied all changes. Then, I stop it:
```
srvctl stop database -d DB19_AARHUS
```
- I won’t need the non-CDB standby database anymore.
- For now, I shut it down and keep it just in case I need to roll back.
On the primary, I create an AutoUpgrade config file. I call it upgrade26.cfg:
```
global.global_log_dir=/home/oracle/autoupgrade/upgrade26
upg1.source_home=/u01/app/oracle/product/dbhome_19_27
upg1.target_home=/u01/app/oracle/product/dbhome_26_1
upg1.sid=DB19
upg1.target_cdb=CDB26
upg1.manage_standbys_clause=standbys=none
upg1.export_rman_backup_for_noncdb_to_pdb=yes
```
- sid contains the name or SID of my database.
- I specify the source and target Oracle homes. These are the Oracle homes of the source non-CDB and target CDB, respectively.
- manage_standbys_clause=standbys=none instructs AutoUpgrade to plug the PDB in with deferred recovery.
- 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).
On the primary host, I start AutoUpgrade to plug in, upgrade, and convert:
```
java -jar autoupgrade.jar -mode deploy -config upgrade26.cfg
```
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.

When the upgrade completes, check the summary report for details:

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

The summary report lists the following details from the POSTCHECKS stage:

The following PDB(s) were created with standbys=none option. Refer to the postcheck result /home/oracle/autoupgrade/upgrade26/DB19/100/postchecks/db19_copenhagen_postupgrade.log for more details on manual actions needed. DB19
I find additional details in the referenced log file:

[action] Manual steps need to be performed after upgrade to copy the files to the standby database and enable recovery of the PDB from PRIMARY to STANDBY. Refer to MOS document Doc ID 1916648.1 for detailed steps. [broken rule] The following PDB(s) [DB19] were created with standbys=none option. [rule] On a Data Guard configuration, the CREATE PLUGGABLE DATABASE statement needs to be executed with clause STANDBYS=NONE to avoid impacting redo apply. That clause allows for deferral of file instantiation on the standby and the physical standby database to continue to protect existing pluggable databases. The clause allows the general structure of the PDB to be created on all physical standbys but all files belonging to the PDB are marked as OFFLINE/RECOVER at the standby.
- I deal with this issue in the next chapter.

2. Restore PDB on Standby

On the standby database, stop redo apply in the standby CDB using dgmgrl:
```
edit database CDB26_AARHUS set state='apply-off';
```
Use RMAN to connect to the standby CDB:
```
rman target sys@CDB26_AARHUS
```

Restore the PDB and switch to the new data files:

run {
   allocate channel d1 device type disk;
   allocate channel d2 device type disk;
   set newname for pluggable database DB19 to new;
   restore pluggable database DB19 from service CDB26_COPENHAGEN;
}

Connect to the standby CDB and enable recovery of the PDB:

alter session set container=DB19;
alter pluggable database enable recovery;

Then, online all the data files in the PDB:

select file#, status from v$datafile;
alter database datafile <file#> online;
alter database datafile <file#> online;
...
alter database datafile <file#> online;

Restart redo apply in the standby CDB:

edit database CDB26_AARHUS set state='apply-on';

Connect to the standby CDB and verify the PDB’s recovery status (should be ENABLED). Ensure that the recovery process is running (should be APPLYING_LOG):
```
select recovery_status 
from   v$pdbs 
where  name='DB19';

select process, status, sequence# 
from   v$managed_standby
where  process like 'MRP%'; 
```
Optionally, but strongly recommended, perform a switchover as the ultimate test. Connect to dgmgrl using username and password:
```
dgmgrl sys as sysdba
```

Perform the switchover:

validate database "CDB26_AARHUS";
switchover to "CDB26_AARHUS";

Then, finally, I connect to the new primary CDB, CDB26_AARHUS. I ensure the PDB is open in READ WRITE mode and unrestricted. I check the status of all data files is SYSTEM or ONLINE:
```
alter pluggable database DB19 open;

alter session set container=DB19;

select open_mode, restricted, recovery_status 
from   v$pdbs;

select name, status 
from   v$datafile;
```

3. Post-upgrade Tasks

I take care of the post-upgrade tasks.
I update any profiles or scripts that use the database.
I remove the non-CDB entry from /etc/oratab and Grid Infrastructure on the standby. AutoUpgrade takes care of the primary.
I clean up and remove the old source non-CDB. On both primary and standby, I remove: * Database files, like PFile, SPFile, password file, control file, and redo logs. * Database directory, like diagnostic_dest, adump, or db_recovery_file_dest.
On the standby, I remove the source non-CDB data files using asmcmd:
```
cd DATA
rm -rf DATA/DB19_AARHUS/DATAFILE
```
- Important: I don’t do that on the primary because I reused the data files during the plug-in.

That’s It!

I’m using AutoUpgrade for the entire upgrade; nice and simple. I must take care of the standby database after the migration.

When I reuse the data files on the primary database, I no longer have the non-CDB for rollback. Be sure to plan accordingly.

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

Happy upgrading!

Appendix

Data Files in ASM/OMF

Primary Database

When I create the PDB, I reuse the data files from the primary database. The data files are in the OMF location of the non-CDB database, e.g.:
```
+DATA/DB19_COPENHAGEN/DATAFILE
```
However, after plug-in, the proper OMF location for my PDB data files is:
```
+DATA/CDB26_COPENHAGEN/<PDB GUID>/DATAFILE
```
The CDB doesn’t care about this anomaly. However, if I want to conform to the OMF naming standard, I must move the data files. Find the data files:
```
select file#, name from v$datafile;
```
I use online datafile move to move those files in the wrong location. I don’t specify a new data file name, so the database generates an OMF name:
```
alter database move datafile <file#>;
```
- Online data file move creates a copy of the data files before switching to the new file and dropping the old one. So I need additional disk space, and the operation takes time while the database copies the file.

Standby Database

There is nothing to do on the standby database. When I restore the data files, they are placed in the right OMF location.

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:

RMAN backups
Storage snapshots
Standby database (the source non-CDB standby database, which you leave behind)
Refreshable clone PDB

What If I Have Multiple Standby Databases?

You must repeat the relevant steps for each standby database.

You can mix and match standbys with deferred and enabled recovery. Let’s say that you want to use enabled recovery on DR standbys and deferred recovery on the reporting standbys.

Role	Name	Method
Local DR	CDB26_COPENHAGEN2	Enabled recovery
Local reporting	CDB26_COPENHAGENREP	Deferred recovery
Remote DR	CDB26_AARHUS	Enabled recovery
Remote reporting	CDB26_AARHUSREP	Deferred recovery

You would set the following in your AutoUpgrade config file:

upg1.manage_standbys_clause=standbys=CDB26_COPENHAGEN2,CDB26_AARHUS

You would need to merge the two procedures together. This is left as a reader’s exercise.

What If My Database Is A RAC Database?

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 Encrypted

AutoUpgrade fully supports upgrading an encrypted database. I can still use the above procedure with a few changes.

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.
before_action / after_action: Extend AutoUpgrade with your own functionality by using scripts before or after the job.

Further Information

Upgrade Oracle Database 19c Non-CDB to 26ai and Convert to PDB Using Refreshable Clone PDB

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.

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.

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.

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';

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=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
```
- If the source database is on a different system, set source_home to /tmp.
- sid is the database that I want to upgrade and convert.
- target_cdb is where the database 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.
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.
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.

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=FTEX
```
- If the target_home doesn’t exist because it’s on a remote system, you can use target_version=26 instead.

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

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

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

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.

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

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

I take care of the post-upgrade tasks.
I update any profiles or scripts that use the database.
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.
I can remove the database link user:
```
drop user dblinkuser cascade;
```
Recreate the connection services.
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 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.

What If My Database Is Encrypted

AutoUpgrade fully supports encrypted databases. You must enter the source non-CDB keystore password 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.

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.