8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux
Multitenant : Unplug/Plugin PDB Upgrade to Oracle Database 21c (AutoUpgrade)
Oracle 21c is an innovation release, so it may not be suitable for most production systems. Please read this before using Oracle 21c for anything real.
This article provides an overview of upgrading an existing PDB to Oracle 21c on the same server using AutoUpgrade Unplug/Plugin. Upgrades can be very complicated, so you must always read the upgrade manual, and test thoroughly before considering an upgrade of a production environment.
- Assumptions
- Prerequisites
- Install 21c Software
- Create 21c Container Database
- Run AutoUpgrade Analyze
- Run AutoUpgrade Deploy
- Final Steps
- Appendix
Related articles.
- Oracle 21c : Upgrade Overview
- Multitenant : Upgrade to Oracle Database 21c (AutoUpgrade)
- Multitenant : PDB Upgrades Using Priority Lists, Inclusion Lists and Exclusion Lists in Oracle Database 12c Release 2 (12.2)
- Multitenant : All Articles
- Upgrade the Database Time Zone File Using the DBMS_DST Package
Assumptions
This article is focused on upgrading a pluggable database using unplug/plugin. If you want to upgrade a CDB and all PDBs directly, you need to follow this article.
This article assumes your source database is of a version supported for direct upgrade to 21c.
19c, 18c, 12.2
In this example we are doing an upgrade from 19c multitenant to 21c. The process is very similar for all supported versions.
It's important to have backups of everything before you start! Some of these steps are destructive, and if something goes wrong you have no alternative but to restore from backups and start again.
Remember, this article is not a replacement for reading the upgrade documentation. Each upgrade has the potential to be different, depending on what options are installed.
Prerequisites
Make sure you have all the OS prerequisites in place by running the 21c preinstall package. On Oracle Linux you can do this by installing the preinstall package. It probably makes sense to update the remaining packages also.
yum install -y oracle-database-preinstall-21c yum update -y
Install 21c Software
You can read about the installation process in more detail here (OL7, OL8), but for this example we'll keep it brief. The following commands will perform a silent installation of the 21c software.
export ORACLE_HOME=$ORACLE_BASE/product/21.0.0/dbhome_1 export PATH=$ORACLE_HOME/bin:$PATH export SOFTWARE_DIR=/vagrant/software export ORA_INVENTORY=/u01/app/oraInventory mkdir -p ${ORACLE_HOME} cd $ORACLE_HOME /bin/unzip -oq ${SOFTWARE_DIR}/LINUX.X64_213000_db_home.zip ./runInstaller -ignorePrereq -waitforcompletion -silent \ -responseFile ${ORACLE_HOME}/install/response/db_install.rsp \ oracle.install.option=INSTALL_DB_SWONLY \ ORACLE_HOSTNAME=${ORACLE_HOSTNAME} \ UNIX_GROUP_NAME=oinstall \ INVENTORY_LOCATION=${ORA_INVENTORY} \ SELECTED_LANGUAGES=en,en_GB \ ORACLE_HOME=${ORACLE_HOME} \ ORACLE_BASE=${ORACLE_BASE} \ oracle.install.db.InstallEdition=EE \ oracle.install.db.OSDBA_GROUP=dba \ oracle.install.db.OSBACKUPDBA_GROUP=dba \ oracle.install.db.OSDGDBA_GROUP=dba \ oracle.install.db.OSKMDBA_GROUP=dba \ oracle.install.db.OSRACDBA_GROUP=dba \ SECURITY_UPDATES_VIA_MYORACLESUPPORT=false \ DECLINE_SECURITY_UPDATES=true
Run the root scripts when prompted.
As a root user, execute the following script(s): 1. /u01/app/oracle/product/21.0.0/dbhome_1/root.sh
At this point you should also patch the new Oracle home, but in this case we will forgo that step to keep things simple.
Create 21c Container Database
We need to create a container database (CDB) as the destination for the resulting PDB. The following example create a CDB called "cdb2" with no PDBs.
#dbca -silent -deleteDatabase -sourceDB cdb2 -sysDBAUserName sys -sysDBAPassword SysPassword1 dbca -silent -createDatabase \ -templateName General_Purpose.dbc \ -gdbname cdb2 -sid cdb2 -responseFile NO_VALUE \ -characterSet AL32UTF8 \ -sysPassword SysPassword1 \ -systemPassword SysPassword1 \ -createAsContainerDatabase true \ -numberOfPDBs 0 \ -databaseType MULTIPURPOSE \ -memoryMgmtType auto_sga \ -totalMemory 1536 \ -storageType FS \ -datafileDestination "/u02/oracle/" \ -redoLogFileSize 50 \ -emConfiguration NONE \ -ignorePreReqs Prepare for db operation 10% complete Copying database files 40% complete Creating and starting Oracle instance 42% complete 46% complete 52% complete 56% complete 60% complete Completing Database Creation 66% complete 69% complete 70% complete Executing Post Configuration Actions 100% complete Database creation complete. For details check the logfiles at: /u01/app/oracle/cfgtoollogs/dbca/cdb2. Database Information: Global Database Name:cdb2 System Identifier(SID):cdb2 Look at the log file "/u01/app/oracle/cfgtoollogs/dbca/cdb2/cdb2.log" for further details. $
We enable the fast recovery area, Oracle Managed Files (OMF) and archivelog mode.
export ORACLE_SID=cdb2 sqlplus / as sysdba <<EOF alter system set db_recovery_file_dest_size=40g; alter system set db_recovery_file_dest='/u01/app/oracle/fast_recovery_area'; alter system set db_create_file_dest = '/u02/oradata'; shutdown immediate; startup mount; alter database archivelog; alter database open; exit; EOF
You will need to adjust the instance parameters to make sure the container can cope with the demands of the final PDB, but for this example we will ignore that.
Run AutoUpgrade Analyze
Download the latest "autoupgrade.jar" file from MOS 2485457.1. If you don't have MOS access you can miss out the next step.
cd $ORACLE_BASE/product/21.0.0/dbhome_1/rdbms/admin mv autoupgrade.jar autoupgrade.jar.`date +"%Y"-"%m"-"%d"` cp /tmp/autoupgrade.jar .
Make sure you are using the original Oracle home before running the "autoupgrade.jar" commands.
export ORACLE_SID=cdb1 export ORAENV_ASK=NO . oraenv export ORAENV_ASK=YES export ORACLE_HOME=$ORACLE_BASE/product/19.0.0/dbhome_1
Generate a sample file for a full database upgrade.
$ORACLE_BASE/product/21.0.0/dbhome_1/jdk/bin/java \ -jar $ORACLE_BASE/product/21.0.0/dbhome_1/rdbms/admin/autoupgrade.jar \ -create_sample_file config /tmp/config.txt unplug
Edit the resulting "/tmp/config.txt" file, setting the details for your required upgrade. In this case we used the following parameters. We are only upgrading a single PDB, but if we had multiple we could use a comma-separated list of PDBs.
upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/pdb1 upg1.sid=cdb1 upg1.source_home=/u01/app/oracle/product/19.0.0/dbhome_1 upg1.target_cdb=cdb2 upg1.target_home=/u01/app/oracle/product/21.0.0/dbhome_1 upg1.pdbs=pdb1 # Comma delimited list of pdb names that will be upgraded and moved to the target CDB #upg1.target_pdb_name.mypdb1=altpdb1 # Optional. Name of the PDB to be created on the target CDB #upg1.target_pdb_copy_option.mypdb1=file_name_convert=('mypdb1', 'altpdb1') # Optional. file_name_convert option used when creating the PDB on the target CDB #upg1.target_pdb_name.mypdb2=altpdb2 upg1.start_time=NOW # Optional. [NOW | +XhYm (X hours, Y minutes after launch) | dd/mm/yyyy hh:mm:ss] upg1.upgrade_node=localhost # Optional. To find out the name of your node, run the hostname utility. Default is 'localhost' upg1.run_utlrp=yes # Optional. Whether or not to run utlrp after upgrade upg1.timezone_upg=yes # Optional. Whether or not to run the timezone upgrade upg1.target_version=21 # Oracle version of the target ORACLE_HOME. Only required when the target Oracle database version is 12.2
Run the upgrade in analyze mode to see if there are any expected issues with the upgrade.
$ORACLE_BASE/product/21.0.0/dbhome_1/jdk/bin/java \ -jar $ORACLE_BASE/product/21.0.0/dbhome_1/rdbms/admin/autoupgrade.jar \ -config /tmp/config.txt -mode analyze AutoUpgrade tool launched with default options Processing config file ... +--------------------------------+ | Starting AutoUpgrade execution | +--------------------------------+ 1 databases will be analyzed Type 'help' to list console commands upg> Job 100 completed ------------------- Final Summary -------------------- Number of databases [ 1 ] Jobs finished [1] Jobs failed [0] Jobs pending [0] Please check the summary report at: /u01/app/oracle/cfgtoollogs/autoupgrade/cfgtoollogs/upgrade/auto/status/status.html /u01/app/oracle/cfgtoollogs/autoupgrade/cfgtoollogs/upgrade/auto/status/status.log
The output files list the status of the analysis, and any manual intervention that is needed before an upgrade can take place. The output of the "status.log" file is shown below. The detail section gives a file containing the details of the steps in the upgrade process. If you've seen the output from the "preupgrade.jar", it will look familiar. If there are any required manual actions in the main log file, the detail file should give more information.
========================================== Autoupgrade Summary Report ========================================== [Date] Sun Aug 22 14:49:01 UTC 2021 [Number of Jobs] 1 ========================================== [Job ID] 100 ========================================== [DB Name] cdb1 [Version Before Upgrade] 19.12.0.0.0 [Version After Upgrade] 21.3.0.0.0 ------------------------------------------ [Stage Name] PRECHECKS [Status] SUCCESS [Start Time] 2021-08-22 14:48:44 [Duration] 0:00:16 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/100/prechecks [Detail] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/100/prechecks/cdb1_preupgrade.log Precheck passed and no manual intervention needed ------------------------------------------
The log directory contains a number of files, including a HTML format of the detailed report. It's the same information as the log file, but some people my prefer reading this format.
Once any required manual fixups are complete, run the analysis again and you should see a clean analysis report.
Run AutoUpgrade Deploy
We are now ready to run the database upgrade with the following command. The upgrade takes some time, so you will be left at the "upg" prompt until it's complete.
$ORACLE_BASE/product/21.0.0/dbhome_1/jdk/bin/java \ -jar $ORACLE_BASE/product/21.0.0/dbhome_1/rdbms/admin/autoupgrade.jar \ -config /tmp/config.txt -mode deploy AutoUpgrade tool launched with default options Processing config file ... +--------------------------------+ | Starting AutoUpgrade execution | +--------------------------------+ 1 databases will be processed Type 'help' to list console commands upg>
Use the "help" command to see the command line options. We can list the current jobs and check on the job status using the following commands.
upg> lsj +----+-------+---------+---------+-------+--------------+--------+----------------+ |Job#|DB_NAME| STAGE|OPERATION| STATUS| START_TIME| UPDATED| MESSAGE| +----+-------+---------+---------+-------+--------------+--------+----------------+ | 101| cdb1|DBUPGRADE|EXECUTING|RUNNING|21/08/22 14:51|14:56:28|22%Upgraded PDB1| +----+-------+---------+---------+-------+--------------+--------+----------------+ Total jobs 1 upg> status -job 101 Progress ----------------------------------- Start time: 21/08/22 14:51 Elapsed (min): 5 End time: N/A Last update: 2021-08-22T14:56:28.019 Stage: DBUPGRADE Operation: EXECUTING Status: RUNNING Pending stages: 7 Stage summary: SETUP <1 min PREUPGRADE <1 min PRECHECKS <1 min PREFIXUPS 1 min DRAIN <1 min DBUPGRADE 3 min (IN PROGRESS) Job Logs Locations ----------------------------------- Logs Base: /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1 Job logs: /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101 Stage logs: /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/dbupgrade TimeZone: /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/temp Additional information ----------------------------------- Details: [Upgrading] is [22%] completed for [cdb1-pdb1] +---------+-------------+ |CONTAINER| PERCENTAGE| +---------+-------------+ | PDB1|UPGRADE [22%]| +---------+-------------+ Error Details: None upg>
Once the job completes a summary message is displayed.
upg> Job 101 completed ------------------- Final Summary -------------------- Number of databases [ 1 ] Jobs finished [1] Jobs failed [0] Jobs pending [0] Please check the summary report at: /u01/app/oracle/cfgtoollogs/autoupgrade/cfgtoollogs/upgrade/auto/status/status.html /u01/app/oracle/cfgtoollogs/autoupgrade/cfgtoollogs/upgrade/auto/status/status.log
The "status.log" contains the top-level information about the upgrade process.
========================================== Autoupgrade Summary Report ========================================== [Date] Sun Aug 22 15:15:50 UTC 2021 [Number of Jobs] 1 ========================================== [Job ID] 101 ========================================== [DB Name] cdb1 [Version Before Upgrade] 19.12.0.0.0 [Version After Upgrade] 21.3.0.0.0 ------------------------------------------ [Stage Name] PREUPGRADE [Status] SUCCESS [Start Time] 2021-08-22 14:51:03 [Duration] 0:00:00 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/preupgrade ------------------------------------------ [Stage Name] PRECHECKS [Status] SUCCESS [Start Time] 2021-08-22 14:51:03 [Duration] 0:00:20 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/prechecks [Detail] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/prechecks/cdb1_preupgrade.log Precheck passed and no manual intervention needed ------------------------------------------ [Stage Name] PREFIXUPS [Status] SUCCESS [Start Time] 2021-08-22 14:51:24 [Duration] 0:01:43 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/prefixups ------------------------------------------ [Stage Name] DRAIN [Status] SUCCESS [Start Time] 2021-08-22 14:53:08 [Duration] 0:00:12 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/drain ------------------------------------------ [Stage Name] DBUPGRADE [Status] SUCCESS [Start Time] 2021-08-22 14:53:20 [Duration] 0:15:56 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/dbupgrade ------------------------------------------ [Stage Name] NONCDBTOPDBXY [Status] SUCCESS [Start Time] 2021-08-22 15:09:16 [Duration] 0:00:00 ------------------------------------------ [Stage Name] POSTCHECKS [Status] SUCCESS [Start Time] 2021-08-22 15:09:16 [Duration] 0:00:09 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/postchecks [Detail] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/postchecks/cdb1_postupgrade.log ------------------------------------------ [Stage Name] POSTFIXUPS [Status] SUCCESS [Start Time] 2021-08-22 15:09:26 [Duration] 0:06:23 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/postfixups ------------------------------------------ [Stage Name] POSTUPGRADE [Status] SUCCESS [Start Time] 2021-08-22 15:15:49 [Duration] 0:00:00 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/postupgrade ------------------------------------------ [Stage Name] SYSUPDATES [Status] SUCCESS [Start Time] 2021-08-22 15:15:50 [Duration] 0:00:00 [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/sysupdates ------------------------------------------ Upgrade Summary: /u01/app/oracle/cfgtoollogs/autoupgrade/pdb1/cdb1/101/dbupgrade/upg_summary.log
Check out the "upg_summary.log" file, and if anything looks wrong, check out the associated log files. At this point I do a shutdown and startup to make sure everything is running in the correct mode.
export ORACLE_HOME=$ORACLE_BASE/product/21.0.0/dbhome_1 export PATH=$ORACLE_HOME/bin:$PATH export ORACLE_SID=cdb2 sqlplus / as sysdba <<EOF alter pluggable database PDB1 save state; shutdown immediate; startup; show pdbs exit; EOF
Final Steps
If you've finished with the 19c CDB1 instance, you can remove it.
export ORACLE_HOME=/u01/app/oracle/product/19.0.0/dbhome_1 export PATH=$ORACLE_HOME/bin:$PATH export ORACLE_SID=cdb1 dbca -silent -deleteDatabase -sourceDB mydb -sysDBAUserName sys -sysDBAPassword SysPassword1
Edit the "/etc/oratab" file and any environment files as required.
If you are using APEX or ORDS, you probably want to validate them (validate APEX, validate ORDS).
Appendix
The following commands are used to rebuild the databases if you want to rerun the examples.
Rebuild the 21c CDB1 multitenant database with no PDBS.
export ORACLE_HOME=/u01/app/oracle/product/21.0.0/dbhome_1 export PATH=$ORACLE_HOME/bin:$PATH export ORACLE_SID=cdb2 #dbca -silent -deleteDatabase -sourceDB cdb2 -sysDBAUserName sys -sysDBAPassword SysPassword1 dbca -silent -createDatabase \ -templateName General_Purpose.dbc \ -gdbname cdb2 -sid cdb2 -responseFile NO_VALUE \ -characterSet AL32UTF8 \ -sysPassword SysPassword1 \ -systemPassword SysPassword1 \ -createAsContainerDatabase true \ -numberOfPDBs 0 \ -databaseType MULTIPURPOSE \ -memoryMgmtType auto_sga \ -totalMemory 1536 \ -storageType FS \ -datafileDestination "/u02/oradata/" \ -redoLogFileSize 50 \ -emConfiguration NONE \ -ignorePreReqs sqlplus / as sysdba <<EOF alter system set db_recovery_file_dest_size=40g; alter system set db_recovery_file_dest='/u01/app/oracle/fast_recovery_area'; alter system set db_create_file_dest = '/u02/oradata'; shutdown immediate; startup mount; alter database archivelog; alter database open; exit; EOF
Rebuild the 19c CDB1 multitenant database with one PDB.
export ORACLE_HOME=/u01/app/oracle/product/19.0.0/dbhome_1 export PATH=$ORACLE_HOME/bin:$PATH export ORACLE_SID=cdb1 #dbca -silent -deleteDatabase -sourceDB mydb -sysDBAUserName sys -sysDBAPassword SysPassword1 dbca -silent -createDatabase \ -templateName General_Purpose.dbc \ -gdbname cdb1 -sid cdb1 -responseFile NO_VALUE \ -characterSet AL32UTF8 \ -sysPassword SysPassword1 \ -systemPassword SysPassword1 \ -createAsContainerDatabase true \ -numberOfPDBs 1 \ -pdbName pdb1 \ -pdbAdminPassword SysPassword1 \ -databaseType MULTIPURPOSE \ -memoryMgmtType auto_sga \ -totalMemory 1536 \ -storageType FS \ -datafileDestination "/u02/oradata/" \ -redoLogFileSize 50 \ -emConfiguration NONE \ -ignorePreReqs sqlplus / as sysdba <<EOF alter pluggable database pdb1 save state; alter system set db_recovery_file_dest_size=40g; alter system set db_recovery_file_dest='/u01/app/oracle/fast_recovery_area'; alter system set db_create_file_dest = '/u02/oradata'; shutdown immediate; startup mount; alter database archivelog; alter database open; exit; EOF
For more information see:
- Oracle Database Upgrade Guide 21c
- Oracle 21c : Upgrade Overview
- Multitenant : Upgrade to Oracle Database 21c (AutoUpgrade)
- Multitenant : PDB Upgrades Using Priority Lists, Inclusion Lists and Exclusion Lists in Oracle Database 12c Release 2 (12.2)
- Multitenant : All Articles
- Upgrade the Database Time Zone File Using the DBMS_DST Package
Hope this helps. Regards Tim...