Upgrading an Encrypted PDB

An unplug-plug upgrade of an encrypted PDB requires the keystore password of the source and target CDB, and you can do it with AutoUpgrade.

How To

The pluggable database PDB1 is encrypted and is plugged into CDB1, which is Oracle Database 12.2. I want to upgrade the PDB to Oracle Database 19c by plugging it into CDB2.

  1. Ensure that AutoUpgrade is version 22.2 or higher:
    $ java -jar autoupgrade.jar -version
  2. Create your AutoUpgrade config file and set global.keystore as specified in a previous blog post:
  3. Analyze:
    $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
  4. The summary report warns me that TDE keystore passwords are needed:
    [Stage Name]    PRECHECKS
    [Status]        FAILURE
    [Start Time]    2022-03-29 07:58:52
    [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks
    [Detail]        /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks/cdb1_preupgrade.log
    		Check failed for PDB1, manual intervention needed for the below checks
    There are more details in the preupgrade log file:
    		1.  Perform the specified action ...
    		ORACLE_SID                      Action Required
    		------------------------------  ------------------------
    		CDB1                            Add TDE password
    		CDB2                            Add TDE password
  5. Add the TDE keystore passwords into the AutoUpgrade keystore:
    $ java -jar autoupgrade.jar -config PDB1.cfg -load_password
    TDE> add CDB1
    Enter your secret/Password:    
    Re-enter your secret/Password: 
    TDE> add CDB2
    Enter your secret/Password:    
    Re-enter your secret/Password: 
  6. Save the passwords into the AutoUpgrade keystore. I choose to create an auto-login keystore:
    TDE> save
    Convert the keystore to auto-login [YES|NO] ? YES
    TDE> exit
  7. Re-analyze the PDB:
    $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
  8. If AutoUpgrade does not report any other problems, start the unplug-plug upgrade. Since I chose to create an AutoUpgrade auto-login keystore, I don’t have to provide the password when AutoUpgrade starts:
    $ java -jar autoupgrade.jar -config PDB1.cfg -mode deploy
  9. That’s it!

What Happens

  • When AutoUpgrade needs to unplug the encrypted PDB into a manifest file, the source CDB will need the TDE keystore password. AutoUpgrade can get it from its keystore. This is the IDENTIFIED BY clause of the ALTER PLUGGABLE DATABASE ... UNPLUG INTO statement.
  • The encryption keys of the PDB go into the manifest file. The database doesn’t want to write the encryption keys in clear text in the manifest file and asks for a passphrase that can encrypt the encryption keys. AutoUpgrade generates a passphrase and stores the passphrase in the AutoUpgrade keystore. This is the ENCRYPT USING clause of the ALTER PLUGGABLE DATABASE ... UNPLUG INTO statement.
  • When the PDB plugs into the target CDB, the target CDB will need the TDE keystore password. This is the IDENTIFIED BY clause of the CREATE PLUGGABLE DATABASE ... USING statement.
  • The database must get the encryption keys of the PDB from the manifest files. The encryption keys are encrypted using a passphrase. The database asks AutoUpgrade about the passphrase which is stored in the AutoUpgrade keystore. This is the DECRYPT USING clause of the CREATE PLUGGABLE DATABASE ... USING statement.


AutoUpgrade fallback functionality also works on an encrypted PDB. When it comes to unplug-plug upgrades and fallback capability, it is a requirement that the data files were copied as part of the upgrade process.

In the above example, a fallback using AutoUpgrade would not be possible. Since I did not specify a target_pdb_copy_option the data files were re-used. Other means of falling back to the original state is needed.

Had I specified a target_pdb_copy_option in my config file, a fallback would be possible. In the below example, I am specifying a copy option. file_name_convert=none means that the data files are copied and new OMF names are generated:


In this case, I can revert the unplug-plug upgrade and return to the original state using AutoUpgrade. 103 is the job id of the upgrade:

$ java -jar autoupgrade.jar -config PDB1.cfg -restore -jobs 103

Isolated Keystore Mode

In CDBs the default way of storing TDE encryption keys is in a united keystore. The CDB has one keystore and all PDBs store their encryption keys in that one keystore.

With Oracle Database 19.14 a new option became possible: isolated keystore. The CDB still has a keystore that PDBs can use. But you can also configure each individual PDB to use its own keystore.

Currently, AutoUpgrade does not support isolated keystore mode. But we are working on it.

Other Blog Posts in This Series

3 thoughts on “Upgrading an Encrypted PDB

  1. Hi,
    thank you for this example .
    I’m preparing to relocate a Encrypted non-cdb database (19.9 ) into
    container which is already 19.13 .
    I’ve already successfuly tested this process manually using hot-clonning (CREATE PLUGGABLE DATABASE OurName FROM NON$CDB@link_noncdb_source_for_hotclone ) .
    Do you think it is now possible to do such thing with autoupgrade 22.2.220324 ?
    kind regards


  2. Hi Janus,
    That should be possible. In start of May we have a webinar with new AutoUpgrade features: https://dohdatabase.com/webinars/. We plan to demo it at the webinar.
    I know Mike Dietrich is looking at it now. Keep an eye out on his blog for any posts that could be relevant: https://mikedietrichde.com/.
    You can also have a look in the documentation: https://docs.oracle.com/en/database/oracle/oracle-database/21/upgrd/autoupgrade-configuration-file-examples.html#GUID-BBDA588D-2CCD-4551-BDE2-CA7821A1A54D



  3. Hi Daniel ,
    thank you for the hint on that example from the documentation .
    With the help of it I have managed to setup a config file a run the autoupgrade .
    The result is interesting – I cannot put all the details on this PUBLIC blog .

    [Stage Name] PREUPGRADE
    [Status] SUCCESS
    [Start Time] 2022-04-12 08:24:39
    [Duration] 0:00:00
    [Log Directory] /home/oracle/hajekj/autoupgrade/CPK4A/PK4/106/preupgrade
    [Stage Name] CLONEPDB
    [Status] SUCCESS
    [Start Time] 2022-04-12 08:24:39
    [Duration] 0:03:23
    [Log Directory] /home/oracle/hajekj/autoupgrade/CPK4A/PK4/106/clonepdb
    [Stage Name] DBUPGRADE
    [Status] SUCCESS
    [Start Time] 2022-04-12 08:28:03
    [Duration] 0:14:17
    [Log Directory] /home/oracle/hajekj/autoupgrade/CPK4A/PK4/106/dbupgrade
    [Stage Name] NONCDBTOPDB
    [Status] SUCCESS
    [Start Time] 2022-04-12 08:42:20
    [Duration] 0:03:27
    [Log Directory] /home/oracle/hajekj/autoupgrade/CPK4A/PK4/106/noncdbtopdb

    The source nonCDB was left intact – this is GREAT if fallback is needed !

    Clone was performed by autoupgrade with this command
    CREATE PLUGGABLE DATABASE PK4 FROM pk4@link_noncdb_source_for_hotclone file_name_convert=(‘…’,’…’) keystore identified by * REFRESH MODE MANUAL

    … if i did it manually I would additionaly used STANDBYS=NONE because target container is in DG config

    Encryption is working in cloned PDB , yet
    SQL> select * from v$encryption_keys;
    no rows selected

    Clonned PDB components are upgraded like this:
    SQL> select comp_id , version_full , status from dba_registry;

    —————————— —————————— ———–

    9 rows selected.

    kind regards


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s