AutoUpgrade and Oracle Database Configuration Options
When you run AutoUpgrade, it determines the type of database (Oracle Database, Oracle Database Standalone with Oracle ASM, or Oracle RAC), and performs an upgrade for that type of database
- Non-CDB to PDB Upgrade Guidelines and Examples
Before conversion, back up your datafiles and database, and follow the guidelines for your source Oracle Database release. - AutoUpgrade Process Flow for Oracle Grid Infrastructure Managed Configurations
When AutoUpgrade detects Oracle RAC or Oracle RAC One Node, it proceeds to perform upgrade steps required for all Oracle RAC instances. - Oracle RAC Requirements for Upgrade with AutoUpgrade
To determine if AutoUpgrade can upgrade your Oracle Real Application Clusters (Oracle RAC) or Oracle RAC One Node database, review the use case requirements. - Preparing for Oracle RAC Upgrades Using AutoUpgrade
Review to find what information you must collect before the upgrade, and other upgrade preparation guidelines. - AutoUpgrade Patching
AutoUpgrade can patch Oracle Database releases to a newer Release Update or Monthly Recommended Patches using out-of-place patching. - AutoUpgrade and Oracle Data Guard
The AutoUpgrade utility that you download from My Oracle Support can simplify the upgrade process for your primary and secondary databases configured for Oracle Data Guard. - How to Run AutoUpgrade Using the Fast Deploy Option
To minimize downtime, you can upgrade your database by running AutoUpgrade using the Fast Deploy option. - How to Perform an Unplug-Plug Upgrade of an Encrypted PDB
Learn how you can perform unplug-plug upgrades of encrypted PDBs using the AutoUpgrade Utility. - How to Perform a Non-CDB to PDB Conversion of an Encrypted PDB
With AutoUpgrade 22.1 and later updates, AutoUpgrade simplifies the upgrade and conversion of Oracle Databases that use Transparent Data Encryption (TDE).
Parent topic: Using AutoUpgrade for Oracle Database Upgrades
Non-CDB to PDB Upgrade Guidelines and Examples
Before conversion, back up your datafiles and database, and follow the guidelines for your source Oracle Database release.
To ensure that you can recover from a failed conversion, Oracle strongly recommends that allow time in your upgrade plan to implement your backup strategy before you use AutoUpgrade to perform a non-CDB upgrade and conversion.
Guidelines for Upgrade Planning
The non-CDB-to-PDB conversion and upgrade process is not recoverable. To ensure a proper upgrade and conversion, and to reduce unexpected downtime, Oracle strongly recommends that you address any error conditions found during the analyze phase.
If you use the target_pdb_copy_option
in your
configuration file to create copies of your data files, then your existing database
is available as a backup. This is a safe option, but will require additional time
and disk space. If you do not set the target_pdb_copy_option
in
your AutoUpgrade configuration file, then the database conversion uses the same file
location and file names that are used with existing database files. To prevent
potential data loss, ensure that your data is backed up, and consider your file
placement plans before starting AutoUpgrade.
GRP and Upgrades from Non-CDB to Multitenant Architecture
- During the upgrade, AutoUpgrade creates a guaranteed restore point (GRP) that is available only in the context of the upgrade stage of the AutoUpgrade Deploy workflow. To ensure against any potential data loss, you must implement your backup strategy before starting AutoUpgrade.
- Database conversion from non-CDB to the multitenant architecture is
performed during the AutoUpgrade Drain stage. After this stage is complete, the
GRP that AutoUpgrade creates is removed, and it is not possible to use the
AutoUpgrade
restore
command to restore the database. In the event that you require a recovery to the earlier non-CDB Oracle Database release, you must be prepared to recover the database manually.
Example 3-4 Upgrading and Converting a Non-CDB to Oracle Database 19c Using Multitenant Architecture
During the Deploy conversion and upgrade workflow, AutoUpgrade creates a GRP, and runs the Prefixup stage. If any part of the Deploy workflow up to the Prefixup stage completion fails, then AutoUpgrade can restore the database back to the GRP created at the start of the deployment,
However, after the Prefixup stage is complete, the upgraded database is plugged in to the target release Oracle Database container database (CDB) to complete conversion. As soon as the non-CDB is plugged into the CDB, the GRP is no longer valid, and is dropped.
If anything goes wrong during the plug-in, and you did not choose to use
the target_pdb_copy_option
in your configuration file to create
copies of your data files, then be aware that AutoUpgrade cannot recover and restore
the database. In that event, you must restore the database manually.
Parent topic: AutoUpgrade and Oracle Database Configuration Options
AutoUpgrade Process Flow for Oracle Grid Infrastructure Managed Configurations
When AutoUpgrade detects Oracle RAC or Oracle RAC One Node, it proceeds to perform upgrade steps required for all Oracle RAC instances.
When you start AutoUpgrade, it detects when Oracle Database is managed with Oracle Grid Infrastructure, either with Oracle Real Application Clusters (Oracle RAC), or an Oracle RAC One Node configuration. Before you start AutoUpgrade, you must already have upgraded Oracle Grid Infrastructure to a release equal to or more recent than the Oracle Database release to which you are upgrading.
Note:
Choosing this upgrade option requires downtime of the clustered database while AutoUpgrade completes upgrades of database instances, and system configuration. If you use Oracle Enterprise Manager, then you must reconfigure it after the upgrade.During an upgrade, when AutoUpgrade detects that the Oracle Database is an Oracle Clusterware resource, it performs the following steps, in sequence:
- AutoUpgrade shuts down the database, or all instances of the Oracle RAC database.
- AutoUpgrade disables Oracle RAC and Oracle RAC One Node services.
- If the Oracle Clusterware resource is Oracle RAC, then AutoUpgrade disables the Oracle RAC database resource in Oracle Clusterware.
- AutoUpgrade starts up the Oracle Database instance:
- If the instance was an Oracle RAC instance, then AutoUpgrade
starts the local Oracle Database instance in upgrade mode, with
CLUSTER_DATABASE
set to false. - If the instance was a single-instance Oracle Database, then it starts up the instance in normal mode.
- If the instance was an Oracle RAC instance, then AutoUpgrade
starts the local Oracle Database instance in upgrade mode, with
- AutoUpgrade upgrades the local Oracle Database Oracle home binaries to the new Oracle Database release binaries.
- During an upgrade, AutoUpgrade runs
srvctl upgrade database
from the local Oracle Database home, and for Oracle RAC, upgrades the configuration of the Oracle RAC services to the new release. During a patch operation, instead ofsrvctl upgrade database
, AutoUpgrade runssrvctl modify database
. - AutoUpgrade enables Oracle Grid Infrastructure services for the
database, using
srvctl enable database
. For Oracle RAC instances, it changesCLUSTER_DATABASE
to true. - AutoUpgrade recreates the server parameter file
(
SPFILE
) with the updated parameters, and the parameter options you previously set for your environment that are not affected by the release upgrade. - If the Oracle Database is an instance of an Oracle RAC database, then AutoUpgrade repeats this process on each other cluster member node, until all instances of the Oracle RAC database are upgraded.
- AutoUpgrade starts up the Oracle Database. For Oracle RAC, it starts all instances of Oracle Real Application Clusters on the cluster.
During a patch operation, the process is similar, with the following differences:
- AutoUpgrade shuts down the database, or all instances of the Oracle RAC database.
- AutoUpgrade disables Oracle RAC and Oracle RAC One Node services.
- If the Oracle Clusterware resource is Oracle RAC, then AutoUpgrade disables the Oracle RAC database resource in Oracle Clusterware.
- AutoUpgrade starts up the Oracle Database instance:
- If the instance was an Oracle RAC instance, then AutoUpgrade
starts the local Oracle Database instance in upgrade mode, with
CLUSTER_DATABASE
set to false. - If the instance was a single-instance Oracle Database, then it starts up the instance in normal mode.
In comparison to an upgrade operation, patch maintenance also performs the following steps in this stage, so that the database is ready to start up after the drain stage is complete:
- AutoUpgrade upgrades the local Oracle Database Oracle home binaries to the new Oracle Database release binaries.
- AutoUpgrade runs
srvctl modify database
from the local Oracle Database home, and patches the database. For Oracle RAC, it also patches the configuration of the Oracle RAC services to the new release update. - AutoUpgrade enables Oracle Grid Infrastructure services for the database,
using
srvctl enable database
. F - AutoUpgrade recreates the server parameter file
(
SPFILE
) with the updated parameters, and the parameter options you previously set for your environment that are not affected by the release patch maintenance. - If the Oracle Database is an instance of an Oracle RAC database, then AutoUpgrade repeats this process on each other cluster member node, until all instances of the Oracle RAC database are upgraded.
- AutoUpgrade starts up the Oracle Database. For Oracle RAC, it starts all instances of Oracle Real Application Clusters on the cluster.
- If the instance was an Oracle RAC instance, then AutoUpgrade
starts the local Oracle Database instance in upgrade mode, with
Parent topic: AutoUpgrade and Oracle Database Configuration Options
Oracle RAC Requirements for Upgrade with AutoUpgrade
To determine if AutoUpgrade can upgrade your Oracle Real Application Clusters (Oracle RAC) or Oracle RAC One Node database, review the use case requirements.
Requirements for Using AutoUpgrade with Oracle RAC Databases
You can use AutoUpgrade to perform upgrades of Oracle RAC or Oracle Real Application Clusters One Node systems. However, your system must meet all of the following requirements:
- Must be either a Linux or Unix-based system. Microsoft Windows systems are not supported.
- Must meet the upgrade requirements to upgrade to the new Oracle Database release.
- Must be registered and managed through the Server Control
(
SRVCTL
) utility.
Required Tasks for Database Administrators to Use AutoUpgrade
As the database administrator, you must complete the following tasks:
- Create an adequate backup strategy to prevent data loss from any problems resulting from the upgrade.
- Configure Listener and Transparent Network Substrate (TNS) files,
both for local
tnsnames.ora
and SCAN listeners, if needed. - Configure Oracle Wallet certificates and management (if needed), and configure for automatic login.
Related Topics
Parent topic: AutoUpgrade and Oracle Database Configuration Options
Preparing for Oracle RAC Upgrades Using AutoUpgrade
Review to find what information you must collect before the upgrade, and other upgrade preparation guidelines.
To use AutoUpgrade for Oracle Real Application Clusters (Oracle RAC) upgrades, ensure that you collect information as needed before the upgrade, and be prepared to provide information during the upgrade.
Scope Limits for AutoUpgrade and Oracle RAC
AutoUpgrade does not perform upgrades of the Oracle Clusterware and Oracle ASM components of Oracle Grid Infrastructure. Before you start AutoUpgrade to upgrade your Oracle RAC database, you must first complete a successful Oracle Grid Infrastructure upgrade to the new release.
File System Preparation Before Upgrades Using AutoUpgrade
AutoUpgrade can identify the PFILE
and
SPFILE
files shared on Oracle ASM. AutoUpgrade recreates the
SPFILE as part of the upgrade. If you are sharing an SPFILE
on the
cluster using Oracle ASM, then you do not need to complete this procedure.
Parent topic: AutoUpgrade and Oracle Database Configuration Options
AutoUpgrade Patching
AutoUpgrade can patch Oracle Database releases to a newer Release Update or Monthly Recommended Patches using out-of-place patching.
AutoUpgrade Patching enables you to apply Release Update (RU) and Monthly Recommended Patches (MRPs). When you use this AutoUpgrade procedure, you leverage the AutoUpgrade capabilities of prechecks, resume, restoration, and Oracle RAC management, to perform multiple RU or MRP applications in one seamless operation. AutoUpgrade Patching can simplify the deployment of Oracle Database updates to your enterprise.
- How AutoUpgrade Performs AutoUpgrade Patching
AutoUpgrade Patching extends the AutoUpgrade upgrade process to patching, which enables you to perform out-of-place patching for multiple databases using a single command. - AutoUpgrade Patching Configuration Files and Log Files
See examples of configuration files and log files for AutoUpgrade Patching.
Parent topic: AutoUpgrade and Oracle Database Configuration Options
How AutoUpgrade Performs AutoUpgrade Patching
AutoUpgrade Patching extends the AutoUpgrade upgrade process to patching, which enables you to perform out-of-place patching for multiple databases using a single command.
Note:
Oracle recommends that you use Oracle Fleet Patching and Provisioning for Oracle Real Application Clusters environments.With the latest release of AutoUpgrade the AutoUpgrade Patching procedure can be performed on Release Update (RU), Monthly Recommended Patches (MRPs), and one-off patches, using out-of-place patching. When you patch from an earlier RU or MRP with AutoUpgrade, the simplicity, reliability, and recoverability of AutoUpgrade is extended to the patching process. As a result, patching is easier to perform, and you also obtain simpler recovery from any issues that can arise during the patch deployment.
There are no additional parameters or options that you need to set in the configuration file for AutoUpgrade to perform patching. Just specify the source and target Oracle homes, and AutoUpgrade will apply changes to the databases. When the source and target Oracle homes are the same Oracle Database release (for example, from 19.11 to 19.13), AutoUpgrade identifies the operation as an RU or MRP patch operation. This capability also applies to one-off patches: If the RU or MRP applied to the target Oracle home is later than the RU or MRP of the source Oracle home, then you can apply one-off patches as needed to the target Oracle home using this method.
As AutoUpgrade performs the patch operation, it uses Datapatch to apply an RU or MRP to databases, including Oracle Real Application Clusters (Oracle RAC) databases. The process of patching takes advantage of existing AutoUpgrade options and operations, as with a full release upgrade, including creating a Guarantee Restore Point. During the patching process, the database is shut down in the source Oracle home, and brought back up in the target Oracle home. RU or MRP updates are performed in upgrade mode, using Datapatch.
Note:
At the time of this release, AutoUpgrade does not perform rolling upgrades of Oracle Database releases. Oracle recommends that you use Oracle Fleet Patching and Provisioning to be able to obtain rolling patch maintenance for Oracle Real Application Clusters (Oracle RAC) environments.Benefits of AutoUpgrade Patching
- AutoUpgrade enables patching of all databases specified in the configuration file, in one operation.
- Resume capabilities are already included with AutoUpgrade.
- Restore capabilities are provided so that it is possible to roll
back to the earlier release Oracle home:
- Restore using the Guarantee Restore Point (GRP) generated during the patching process.
- If a GRP is not present, then the Datapatch rollback
functionality can also perform a restore. AutoUpgrade detects that a GRP
does not exist, and automatically performs the restore using Datapatch.
To enable a Datapatch rollback restore, set the restoration
configuration option to
no
. For example:sales1.restoration=no
.
- Oracle RAC management is provided automatically with AutoUpgrade.
- The error management reporting features of AutoUpgrade are extended to patching.
- The JSON status and progress reporting of AutoUpgrade are extended to patching.
- AutoUpgrade uses the Datapatch JSON status files to determine success or failure of each process, and reports those results to you at the completion of the process.
Features Supported for AutoUpgrade Patching
The following features are provided with AutoUpgrade Patching
- Patching of databases encrypted with Transparent Data Encryption (TDE).
- Hot Cloning/Relocate, which enables you to create PDBs from a Non-CDB, or from a PDB on a remote host.
- Proactive Fixups, which runs postfixups on the PDB as soon as the PDB is patched.
- Multi-node patching and upgrades using Oracle Real Application Clusters (Oracle RAC), which enables AutoUpgrade to spread the workload across multiple nodes.
- Configuration management, by copying or merging the source Oracle home
configuration files (
tnsnames.ora
,sqlnet.ora
, and other files) to the target Oracle home. - Analysis of the database before starting a patching procedure, to ensure patch readiness.
- Running fixups during production before patching, so that you reduce downtime.
You can then use
-mode upgrade
to bypass running fixups and proceed directly to patching the database. - Performing all patching tasks in Deploy mode, to achieve end-to-end patching.
- Enhanced reporting of the patching process, which enables you to diagnose errors
more easily by using the
datapatch_summary.log
report. - Datapatch log files found in the Datapatch summary JSON file are
copied to the output file of the apply or rollback operational logs as
follows:
- Apply log format, where
dbname
is the name of the database:applydatapatchlogfiles#dbname.log
- Rollback log format, where
dbname
is the name of the database:rollbackdatapatchlogfiles#dbname.log
- Apply log format, where
- Datapatch output is logged to following operational logs:
- Apply log format, where
dbname
is the name of the database:applyautoupgrade#dbname.log
- Rollback log format, where
dbname
is the name of the database:rollbackautoupgrade#dbname.log
- Apply log format, where
- Datapatch JSON output is logged to the following operational logs:
- Apply log format, where
dbname
is the name of the database:applydatapatchsummary#dbname.log
- Rollback log format, where
dbname
is the name of the database:rollbackdatapatchsummary#dbname.log
- Apply log format, where
- Storage of all related patching log files produced by AutoUpgrade
are stored in the
dbupgrade
directory. - Standard Datapatch log files are stored in
Oracle-base/cfgtoollogs/sqlpatch
. - Starting with AutoUpgrade 23.1, Patching is supported for single-instance databases on Microsoft Windows. It is not supported with Oracle Real Application Clusters (Oracle RAC).
Requirements and Restrictions for using AutoUpgrade Patching
- Downtime is required to use AutoUpgrade Patching:
- After the patch operation is completed, the database is restarted.
- Patching in normal mode enables the database to be available in the target home while the patching is proceeding.
- Patching in upgrade mode requires the patching to be completed before the database is restarted in the target home.
- During the patch operation, the CDB and PDBs are opened in normal mode after drain operations complete, and patching proceeds. However, rolling patching for Oracle Real Application Clusters is not supported at this time.
- To enable PDBs to become available as soon as they are
successfully patched, then ensure that you set the
tune_settings
optionmake_pdbs_avaliable
totrue
in your configuration file. For example:sales3.tune_setting=proactive_fixups=true,make_pdbs_available=true
- Because downtime is required, rolling upgrades of Oracle RAC are not supported at this time.
- AutoUpgrade can support a target RU or MRP that has additional patches applied. However, the source Oracle Database must be on an earlier RU or MRP than the target Oracle Database RU or MRP.
- AutoUpgrade does not run any OPatch commands. For that reason, the target Oracle home must be fully patched before starting AutoUpgrade.
- AutoUpgrade does not move the listener to the new Oracle home. If needed, you must manually move the listener to the new Oracle home before you start AutoUpgrade.
- Installation and configuration of the target Oracle Database home must be complete before you can run RUs and MRPs on the target home using AutoUpgrade Patching. If a target RU is patched after it has been applied to the database, then you can no longer use AutoUpgrade Patching. Instead, you must use Datapatch to apply the updates.
- Performing rolling patches of Oracle Database (single-instance or Oracle RAC) is not supported. When you use AutoUpgrade Patching on a single-instance or Oracle RAC Oracle Database, AutoUpgrade's Oracle RAC management will shut down the database on all nodes.
- The target Oracle Database RU must be at least Oracle Database 19c, RU 19.3, or later releases. You cannot use AutoUpgrade Patching to perform RUs or MRPs to earlier Oracle Database releases.
- The effect of AutoUpgrade Patching on databases using Oracle Data Guard Physical Standby or Oracle Data Guard Logical Standby and Rolling Upgrade is the same as with using Datapatch. AutoUpgrade patching can be a part of the procedures.
- AutoUpgrade supports physically moving a database to different
hardware. When the database is moved to a different target system, AutoUpgrade
Patching can be used with the
-mode upgrade
option. However, when the database is moved to a different system, AutoUpgrade is unable to perform a restore of the database. In that case, the upgrade options for patching follow the same rules that apply for upgrading your database. - In describing AutoUpgrade, this documentation generally refers to AutoUpgrade performing upgrades. When AutoUpgrade performs patching, patching is functionally similar to upgrades. Accordingly, references to upgrades in this guide or in diagrams are applicable to both upgrade and patching with AutoUpgrade Patching.
- Performing patching with AutoUpgrade Patching supports all
AutoUpgrade
-mode
options except thepreupgrade
mode, which is only supported for upgrades. - When patching or upgrading relocatable PDB's the configuration file cannot contain a mixture of patch clone PDBs and upgraded clone PDBs. The configuration for the clone PDB's must be either all upgrade clones, or all patched clones.
-
AutoUpgrade patching supports only one
catctl_options
setting,-n number
, wherenumber
is the number of processes to use for parallel operations. Thecatctl_options=-n
setting enables you to control the total number of PDBs that you want to run concurrently during the patching process. The default isCPU_COUNT
divided by 2. For example ifCPU_COUNT
is set to 24 then by default, 12 PDBs (Datapatch instances) can run concurrently during the patching process.To overwrite the default, add
prefix.catctl_options
to your configuration file with a value for the number of concurrent Datapatch instances you want to run. For example, to configure AutoUpgrade to run 6 PDBs (Datapatch instances) for the patch operations specified with the prefixsales
, overriding the default, add the following line to your configuration file:sales.catctl_options=-n 6
Caution:
For 19.13 and earlier release updates (RUs), Oracle strongly recommends that you set the
catctl_options
parameter for patching operations.With 19.13 and earlier RUs, the default value of SQL*Plus processors allocated to each Datapatch instance is
CPU_COUNT
multiplied by two (CPU_COUNT*2) processors for each Datapatch instance that AutoUpgrade starts. This default SQL*Plus processor allocation can quickly overload your system. To restrict system resources allocated to the patch operation, restricting how many Datapatch instances running simultaneously is the only option. For RU 19.13 and later, only one SQL*Plus process is started for each instance of Datapatch. This change enables AutoUpgrade to run more PDBs in parallel without consuming a large amount of system resources.
Security Characteristics of AutoUpgrade Patching
- The user running AutoUpgrade Patching must have the
SYSDBA
system privilege to log into the database, and run the patching operation. For an Oracle Real Application Clusters database, the user must be the owner of the source and target Oracle Database Oracle homes. - The same security rules that apply for upgrades also apply with AutoUpgrade Patching.
Performance Characteristics of AutoUpgrade Patching
- The speed of deploying an RU or MRP depends on the number of PDBs in a CDB, and on changes in the release update or release update revision. If the number of changes from the source RU or MRP patches are relatively few, then deployment of patches should be quick. If the patches have many changes, then applying the patches requires more time.
- Because AutoUpgrade Patching includes a number of additional automated procedures, release update deployment is slightly slower than running Datapatch manually. For example, AutoUpgrade Patching automatically includes recompiling invalid objects, and configuring Oracle RAC management on the target system.
What Happens If AutoUpgrade Patching Rolls Back a Release Update
- AutoUpgrade uses the Guarantee Restore Point (GRP) generated during the patch process to roll back to the earlier release Oracle home.
- If no GRP is created, then AutoUpgrade automatically calls Datapatch to rollback the changes.
Parent topic: AutoUpgrade Patching
AutoUpgrade Patching Configuration Files and Log Files
See examples of configuration files and log files for AutoUpgrade Patching.
An AutoUpgrade Patching configuration file is essentially the same as an AutoUpgrade configuration file for upgrades. However, instead of AutoUpgrade using the parameters you specify to perform an upgrade, AutoUpgrade performs a patch operation from a source Oracle Database patch release to a target Oracle Database patch release, and AutoUpgrade runs Datapatch as part of the procedure.
Example 3-5 AutoUpgrade Configuration Files for Different Patching Scenarios
In the following configuration file examples, the following Oracle Databases are patched from Oracle Database 19c patched to Release Update (RU) 11 to 19c RU 13:
- A non-CDB database patched from 19.11.0 to 19.13.0, designated with the prefix
patch1
- An Oracle Database 19c CDB patched from 19.11 to 19.13, designated with the
prefix
patch2
- An encrypted PDB patched by unplug-plug, designated with the prefix
patch3
- A non-CDB, which is patched and converted to a CDB, designated with
the prefix
patch4
- A CDB with a PDB that is relocated during the patching operation,
designated with the prefix
patch5
- An Oracle Real Application Clusters (Oracle RAC) database,
designated with the prefix
patch6
- An Oracle RAC database in a distributed cluster configuration,
designated with the prefix
patch7
#
# Global log directory for patch logs
#
global.autoupg_log_dir=/databases/patchlogs
#
# Non-CDB patch to Non-CDB patch, source and target home
#
patch1.sid=db19
patch1.source_home=/databases/ee/product/1911/dbhome_1
patch1.target_home=/databases/ee/product/1913/dbhome_2
#
#
# CDB patch, Source and Target home
#
patch2.sid=cdb19
patch2.source_home=/databases/ee/product/1911/dbhome_1
patch2.target_home=/databases/ee/product/1913/dbhome_2
#
# Unplug-Plug with KeyStore
#
global.keystore=/databases/tde
patch3.sid=cdb19
patch3.source_home=/databases/ee/product/1911/dbhome_1
patch3.target_home=/databases/ee/product/1913/dbhome_2
patch3.target_cdb=cdb1913
patch3.target_pdb_name=sales
patch3.target_pdb_copy_option=file_name_convert=('/databases/ee/oradata/CDB19/sales', '/databases/ee/oradata/CDB1913/sales')
#
# Non-CDB to CDB, Source and Target home
#
patch4.sid=db19
patch4.source_home=/databases/ee/product/1911/dbhome_1
patch4.target_home=/databases/ee/product/1913/dbhome_2
patch4.target_cdb=cdb1913
patch4.target_pdb_name=emp
patch4.target_pdb_copy_option=file_name_convert=('/databases/ee/oradata/DB19', '/databases/ee/oradata/CDB1913/emp')
#
# Patch relocate DB
#
patch5.sid=cdb19
patch5.source_home=/databases/ee/product/1911/dbhome_1
patch5.target_home=/databases/ee/product/1913/dbhome_2
patch5.target_cdb=cdb1913
patch5.pdbs=cars
patch5.target_pdb_copy_option.cars=file_name_convert=('/databases/ee/oradata/CDB19/cars', '/databases/ee/oradata/CDB1913/cars')
patch5.source_dblink.cars=db19_link
#
# Oracle RAC
#
patch6.sid=rac1
patch6.source_home=/databases/ee/product/1911/dbhome_1
patch6.target_home=/databases/ee/product/1913/dbhome_2
#
# Distributed Oracle RAC with proactive fixups
#
patch7.sid=rac2
patch7.source_home=/databases/ee/product/1911/dbhome_1
patch7.target_home=/databases/ee/product/1913/dbhome_2
patch7.tune_setting=distributed_upgrade=true
Example 3-6 A Summary Log File for AutoUpgrade Patching
In this patching summary report file, you can see how AutoUpgrade applies patches to the CDB and PDBs.
********************************************************************************
Datapatch Apply Summary Report for CDB$ROOT
Return code = 0 SUCCESS
Failure reason = null
Total time = 161.721805095673
Install patches = 1
Database Open = SUCCESS
Invocation Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_17781_2022_05_18_10_57_58/sqlpatch_invocation.log
Bootstrap Required = 1
Bootstrap Status = SUCCESS
Bootstrap Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_17781_2022_05_18_10_57_58/bootstrap1_CDB19X_CDBROOT.log
Total patches = 1
Patch Key = 33192793-24462514
Mode = apply
Status = SUCCESS
Patch Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_apply_CDB19X_CDBROOT_2022May18_10_58_06.log
RU Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_ru_apply_CDB19X_CDBROOT_2022May18_10_58_05.log
RU Errors = N/A
********************************************************************************
Datapatch Apply Summary Report for PDBX
Return code = 0 SUCCESS
Failure reason = null
Total time = 123.969398021698
Install patches = 1
Database Open = SUCCESS
Invocation Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_18416_2022_05_18_11_01_40/sqlpatch_invocation.log
Bootstrap Required = 1
Bootstrap Status = SUCCESS
Bootstrap Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_18416_2022_05_18_11_01_40/bootstrap1_CDB19X_PDBX.log
Total patches = 1
Patch Key = 33192793-24462514
Mode = apply
Status = SUCCESS
Patch Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_apply_CDB19X_PDBX_2022May18_11_01_55.log
RU Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_ru_apply_CDB19X_PDBX_2022May18_11_01_55.log
RU Errors = N/A
********************************************************************************
Datapatch Apply Summary Report for PDB$SEED
Return code = 0 SUCCESS
Failure reason = null
Total time = 124.234117984772
Install patches = 1
Database Open = SUCCESS
Invocation Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_18406_2022_05_18_11_01_40/sqlpatch_invocation.log
Bootstrap Required = 1
Bootstrap Status = SUCCESS
Bootstrap Log = /databases/cfgtoollogs/sqlpatch/sqlpatch_18406_2022_05_18_11_01_40/bootstrap1_CDB19X_PDBSEED.log
Total patches = 1
Patch Key = 33192793-24462514
Mode = apply
Status = SUCCESS
Patch Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_apply_CDB19X_PDBSEED_2022May18_11_01_55.log
RU Log File = /databases/cfgtoollogs/sqlpatch/33192793/24462514/33192793_ru_apply_CDB19X_PDBSEED_2022May18_11_01_55.log
RU Errors = N/A
Parent topic: AutoUpgrade Patching
AutoUpgrade and Oracle Data Guard
The AutoUpgrade utility that you download from My Oracle Support can simplify the upgrade process for your primary and secondary databases configured for Oracle Data Guard.
- How AutoUpgrade Performs Oracle Data Guard Upgrades
AutoUpgrade can detect Oracle Data Guard configurations, and defer shipping logs to standby databases configured for the primary database. - Steps AutoUpgrade Completes for Oracle Data Guard Upgrades
The steps that AutoUpgrade completes vary, depending on whether standby databases are managed manually, or through Data Guard Broker. - Steps After the Primary Database is Upgraded
For Oracle Data Guard upgrades, after you upgrade the primary database you must complete these procedures.
Parent topic: AutoUpgrade and Oracle Database Configuration Options
How AutoUpgrade Performs Oracle Data Guard Upgrades
AutoUpgrade can detect Oracle Data Guard configurations, and defer shipping logs to standby databases configured for the primary database.
AutoUpgrade automatically detects the presence of an Oracle Data Guard deployment, and whether that deployment is configured manually, or uses Data Guard Broker to manage and monitor Oracle Data Guard configurations.
When you set the parameter defer_standby_log_shipping
to
no
(the default) in the configuration file, AutoUpgrade can defer
the log-shipping to configured standby databases, both when Oracle Data Guard is
configured manually, and when Oracle Data Guard is configured through Data Guard Broker.
Preparation Before AutoUpgrade Upgrades of Databases with Oracle Data Guard
Before you begin the upgrade, to be prepared in case of a failure during the primary database upgrade, or in case the primary database must be reverted to the source Oracle home, ensure that your standby databases are protected and recoverable.
Parent topic: AutoUpgrade and Oracle Data Guard
Steps AutoUpgrade Completes for Oracle Data Guard Upgrades
The steps that AutoUpgrade completes vary, depending on whether standby databases are managed manually, or through Data Guard Broker.
For Oracle Data Guard earlier release (source) databases
where Oracle Data Guard is managed manually, or through Data Guard Broker, to manage
log-shipping to standby databases, you can set
defer_standby_log_shipping=yes
in your AutoUpgrade configuration
file (the default is no
). However, the specific actions that
AutoUpgrade takes vary, depending on how you manage standby databases.
Note:
For standby databases managed either manually or through Data Guard Broker, after the upgrade completes, you must runENABLE DATABASE
database-name;
on each of the standby archive log
destinations after successful upgrade on the primary database, and perform all steps
needed to have standby databases upgraded through the redo log apply.
Manually Managed Oracle Data Guard Standby Databases
For Oracle Data Guard standby databases supported for direct upgrade, AutoUpgrade
places in DEFER
mode all VALID
and
ENABLED
standby archive log destinations before starting the
upgrade process for both manually managed and Data Guard Broker managed standby
databases.
Data Guard Broker-Managed Oracle Data Guard Standby Databases
For Oracle Database releases supported for direct upgrade with Oracle Data Guard standby databases that are managed using Data Guard Broker, AutoUpgrade completes the following actions:
- The primary database state is set to
TRANSPORT-OFF
to all standby databases configured with Data Guard Broker - The Data Guard Broker files are copied from the source Oracle home to the target Oracle home.
Note:
If the Data Guard Broker files are located outside of the Oracle home, then files are not found and copied.Parent topic: AutoUpgrade and Oracle Data Guard
Steps After the Primary Database is Upgraded
For Oracle Data Guard upgrades, after you upgrade the primary database you must complete these procedures.
- Ensure that redo transport is enabled on the primary database, so that the upgrade is applied to the standby databases.
- Check that the archives are applied, and that there is a minimal gap. Oracle recommends that Apply Lag and Transport Lag is not bigger than 5 minutes.
Example 3-7 Checking Redo Transport Service Status
To check the status of the redo transport services on the primary
database, use the Data Guard broker command-line interface (DGMGRL
)
LogXptStatus
monitorable property. For example:
DGMGRL> SHOW DATABASE 'sales1' 'LogXptStatus' ;
Example 3-8 Checking Apply Lag and Transport Lag
To check that the archives are applied, and verify that Apply Lag and Transport Lag is not bigger than 5 minutes, log in to the primary database and submit a SQL query similar to the following:
[oracle]$ sqlplus / as sysdba
SYS@sales1>
SET LINESIZE 200
COL VALUE FOR A30
SELECT NAME,VALUE,TIME_COMPUTED,DATUM_TIME FROM V$DATAGUARD_STATS WHERE NAME LIKE '%lag';
The result should be similar to this output:
NAME VALUE TIME_COMPUTED DATUM_TIME
-------------- -------------- --------------------- --------------------
transport lag +00 00:00:00 timestamp timestamp
apply lag +00 00:01:07 timestamp timestamp
Related Topics
Parent topic: AutoUpgrade and Oracle Data Guard
How to Run AutoUpgrade Using the Fast Deploy Option
To minimize downtime, you can upgrade your database by running AutoUpgrade using the Fast Deploy option.
Note:
Oracle recommends that you run AutoUpgrade using standard Analyze and Deploy modes. If you choose to use the Fast Deploy method, then be aware that there is a small risk that new issues can develop in the time duration after you run AutoUpgrade in the preupgrade Analyze mode and before you run AutoUpgrade in Upgrade mode, which can cause a problem. Assess that risk, and take precautions accordingly.-
Create your AutoUpgrade configuration file, providing information about your source and target systems, and your upgrade preferences. In the steps that follow, that file name is
myconfig.cfg
. -
Analyze the database using Analyze mode.
– java -jar autoupgrade.jar -config myconfig.cfg -mode analyze
-
Run the preupgrade fixups using Fixups mode.
– java -jar autoupgrade.jar -config myconfig.cfg -mode fixups
-
Upgrade the database using Upgrade mode.
– java -jar autoupgrade.jar -config myconfig.cfg -mode upgrade
As this command runs, the database can experience downtime, because databases being upgraded are opened in
UPGRADE
mode in the target Oracle home.
Parent topic: AutoUpgrade and Oracle Database Configuration Options
How to Perform an Unplug-Plug Upgrade of an Encrypted PDB
Learn how you can perform unplug-plug upgrades of encrypted PDBs using the AutoUpgrade Utility.
Caution:
If you choose to specify the directory for AutoUpgrade to create withglobal.keystore
, then be aware that
it contains a software keystore. It should be protected using the
same security best practices as you use with the TDE keystore files.
To perform upgrades of encrypted PDBs, AutoUpgrade requires
loading the password for the TDE keystore into its own secure
keystore. To load the passwords, you set the AutoUpgrade global
configuration file parameter keystore
in your
configuration file, and run AutoUpgrade using the command-line
parameter load_password
. This parameter must be
used in conjunction with the -config
parameter. It
takes no arguments. Instead, it starts an interactive prompt with
specific commands that enable you to provide information required
for the keystore. AutoUpgrade stores the passwords you load securely
during the upgrade, and uses those passwords when needed.
Note:
If the database is using an Oracle Secure External
Password Store (SEPS), and a TDE keystore password is
required, then AutoUpgrade uses the IDENTIFIED BY
EXTERNAL STORE
clause, so it does not
require loading passwords into the AutoUpgrade password
keystore. However, if all databases are configured with a
Secure External Password Store, then you still need to
define global.keystore
in your
configuration file.
The AutoUpgrade keystore is similar to other keystores that
Oracle Database uses. You have the option to create it as an
auto-login keystore. For example, if the external keystore
is ewallet.p12
AutoUpgrade creates an
auto-login keystore cwallet.sso
, which is
used to open the ewallet.p12
keystore.
Before you begin to upgrade the encrypted PDB, the following must be true:
- AutoUpgrade must be version 22.2 or later. Oracle strongly recommends that you always download and run the latest version of AutoUpgrade.
- You must use an external TDE keystore
- You have to have available to you the external keystore password of the source and target CDB.
Example 3-9 Upgrading an Encrypted PDB with an Unplug Plug Upgrade Using AutoUpgrade
In the following example, an Oracle Database 12c Release 2
(12.2) PDB using Transparent Data Encryption (TDE) is upgraded to
Oracle Database 19c, using the AutoUpgrade
load_password
command option with the
AutoUpgrade configuration file keystore parameter to provide a
secure store for the TDE keys during the upgrade.
- Ensure that you have the latest version of
AutoUpgrade:
$ java -jar autoupgrade.jar -version
If the AutoUpgrade version is an earlier release, then download the most recent version of AutoUpgrade from My Oracle Support AutoUpgrade Tool (Doc ID 2485457.1)
- Create your AutoUpgrade configuration file. In this
example, the configuration file
PDB1.cfg
is created with the path to the keystore, which is specified in theadmin
folder under the Oracle base directory, in the path/u01/app/oracle/admin/autoupgrade/keystore
. The source CDB isCDB1
,and the target CDB isCDB2
:global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade global.keystore=/u01/app/oracle/admin/autoupgrade/keystore upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/DB12 upg1.source_home=/u01/app/oracle/product/12.2.0/dbhome_1 upg1.target_home=/u01/app/oracle/product/19.1.0/dbhome_1 upg1.sid=CDB1 upg.pdbs=PDB1 upg1.target_cdb=CDB2
Note:
If you do not specify a keystore location, and an AutoUpgrade keystore has not been created previously, then AutoUpgrade creates the AutoUpgrade keystore for you.
- Run AutoUpgrade in Analyze
mode:
$ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
The summary report indicates that TDE keystore passwords are needed before starting the upgrade (
TDE_PASSWORDS_REQURED
):[Stage Name] PRECHECKS [Status] FAILURE [Start Time] 2022-03-29 07:58:52 [Duration] [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 [TDE_PASSWORDS_REQUIRED]
-
Add the TDE keystore passwords into the AutoUpgrade keystore:
$ java -jar autoupgrade.jar -config PDB1.cfg -load_password
The first time you run AutoUpgrade with the
-load_password
command option, you are prompted to create a password for the AutoUpgrade keystore, where TDE passwords can be stored securely:Starting AutoUpgrade Password Loader - Type help for available options Creating new keystore - Password required Enter password: Enter password again: Keystore was successfully created
If do not use a SEPS keystore, then AutoUpgrade prompts you to add the TDE keystore passwords for the databases specified with
source_home
in your configuration file to AutoUpgrade's own keystore, where that database requires a TDE keystore password. This is what we have specified in the configuration file example.In the following example, the source and target TDE keystore passwords are loaded:
TDE> ADD CDB1 Enter your secret/Password: Re-enter your secret/Password: TDE> ADD CDB2 Enter your secret/Password: Re-enter your secret/Password:
Confirm that the passwords are loaded:
TDE> LIST +---------------+-----------------+-----------------+--------------+----------------------+ |ORACLE_SID |Action Required |TDE Password |SEPS Status |Active Wallet Type | +---------------+-----------------+-----------------+--------------+----------------------+ | CDB1 | | Verified | Inactive | Auto-login | | CDB2 | | Verified | Inactive | Any | +---------------+-----------------+-----------------+--------------+----------------------+
When the
Action Required
column is empty, the TDE passwords are available for the upgrade.If you use a SEPS keystore on the source CDB or target CDB, then AutoUpgrade automatically detects the SEPS keystore as the source for the TDE password. AutoUpgrade uses the
IDENTIFIED BY EXTERNAL STORE
clause, and does not need to load the TDE keystore passwords to the AutoUpgrade keystore. Again, the TDE LIST command should show an emptyAction Required
column:TDE> LIST +--------------+------------------+-------------------------+--------------+---------------------+ |ORACLE_SID |Action Required | TDE Password |SEPS Status |Active Wallet Type | +--------------+-------------------+------------------------+--------------+---------------------+ | CDB1 | |No password loaded | Verified | Any | | CDB2 | |No password loaded | Verified | Any | +--------------+-------------------+------------------------+--------------+---------------------+
Both options can be used in the same configuration file. For example, if you do not use a SEPS keystore for the source non-CDB database, but you do use a SEPS keystore for the target CDB, then you only need to load a password for the source non-CDB.
-
Save the TDE passwords into the AutoUpgrade keystore. (Optional): In this example, we will convert the keystore to an auto-login keystore:
TDE> save Convert the keystore to auto-login [YES|NO] ? YES TDE> exit
-
Analyze the PDB again:
$ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
Review the report and confirm all issues are resolved.
- Start the upgrade and
conversion:
$ java -jar autoupgrade.jar -config PDB1.cfg -mode deploy
- AutoUpgrade proceeds to upgrade
PDB1
on the target Oracle Database, using the TDE passwords as needed to complete the upgrade. Because in this example we have configured AutoUpgrade to create an AutoUpgrade auto-login keystore, and access the TDE passwords using its own secure keystore, you are not prompted to provide TDE passwords during the upgrade.
How to Perform a Non-CDB to PDB Conversion of an Encrypted PDB
With AutoUpgrade 22.1 and later updates, AutoUpgrade simplifies the upgrade and conversion of Oracle Databases that use Transparent Data Encryption (TDE).
keystore
, and the AutoUpgrade command-line
parameter load_password
to load TDE passwords securely into
the AutoUpgrade keystore, and use those passwords when needed.
global.keystore
.
Note:
If you specify the AutoUpgrade keystore path, then that path should be different from any other file path you specify in AutoUpgrade, so that the keystore is not in any log file location. If the AutoUpgrade keystore path directory does not exist, then AutoUpgrade automatically creates it..
If the database is using an Oracle Secure External
Password Store (SEPS), and a TDE keystore password is
required, then AutoUpgrade uses the IDENTIFIED BY
EXTERNAL STORE
clause, so it does not
require loading passwords into the AutoUpgrade password
keystore. However, if all databases are configured with a
Secure External Password Store, you still need to define
global.keystore
in your
configuration file.
Example 3-10 Upgrading a Database Using TDE and Converting from Non-CDB to PDB
In the following example, an Oracle Database 12c Release 2
(12.2) non-CDB database using Transparent Data Encryption (TDE) is
upgraded to Oracle Database 19c and converted to a PDB, using the
AutoUpgrade load_password
command option with the
AutoUpgrade configuration file keystore parameter to provide a
secure store for the TDE keys during PDB conversion and upgrade.
- Ensure that you have the latest version of
AutoUpgrade:
$ java -jar autoupgrade.jar -version
If the AutoUpgrade version is an earlier release, then download the most recent version of AutoUpgrade from My Oracle Support AutoUpgrade Tool (Doc ID 2485457.1)
- Create your AutoUpgrade configuration file. In this
example, the path to the keystore is specified in the admin
folder under the Oracle base directory, in the path
/u01/app/oracle/admin/autoupgrade/keystore
:global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade global.keystore=/u01/app/oracle/admin/autoupgrade/keystore upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/DB12 upg1.source_home=/u01/app/oracle/product/12.2.0 upg1.target_home=/u01/app/oracle/product/19.1.0 upg1.sid=DB12 upg1.target_cdb=CDB2
- Run AutoUpgrade in Analyze
mode:
$ java -jar autoupgrade.jar -config DB12.cfg -mode analyze
The summary report indicates that no additional preupgrade tasks need to be completed before starting the upgrade:
[Stage Name] PRECHECKS [Status] SUCCESS [Start Time] 2022-03-30 10:28:38 [Duration] [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/DB12/DB12/100/prechecks [Detail] /u01/app/oracle/cfgtoollogs/autoupgrade/DB12/DB12/100/prechecks/db12_preupgrade.log Check passed and no manual intervention needed
If the
TDE_PASSWORDS_REQUIRED
check fails, then load the TDE password:$ java -jar autoupgrade.jar -config DB12.cfg -load_password
The first time you run AutoUpgrade with the
-load_password
command option, if AutoUpgrade requires a TDE password to perform the upgrade, then you are prompted to create a password for the AutoUpgrade keystore, where the TDE password can be stored securely:Starting AutoUpgrade Password Loader - Type help for available options Creating new keystore - Password required Enter password: Enter password again: Keystore was successfully created
If do not use a SEPS keystore, then AutoUpgrade prompts you to add the TDE keystore passwords for the databases specified with
source_home
in your configuration file to AutoUpgrade's own keystore, where that database requires a TDE keystore password. This is what we have specified in the configuration file example.In the following example, the source and target TDE keystore passwords are loaded:
TDE> ADD DB12 Enter your secret/Password: Re-enter your secret/Password: TDE> ADD CDB2 Enter your secret/Password: Re-enter your secret/Password:
- To check the TDE configuration, you can run
AutoUpgrade again using the
-load_password
command parameter. This time, because the password is already loaded, the TDE console prompt appears. Run the TDE consolelist
command to check the TDE configuration:$ java -jar autoupgrade.jar -config DB12.cfg -load_password TDE> list +----------+---------------+------------------+-----------+------------------+ |ORACLE_SID|Action Required| TDE Password |SEPS Status|Active Wallet Type| +----------+---------------+------------------+-----------+------------------+ | CDB2| |No password loaded| Verified| Any| | DB12| |No password loaded| Unknown| Auto-login| +----------+---------------+------------------+-----------+------------------+
In the table output for the list command, the
Action Required
column is empty. This result verifies that you have provided the TDE keystore password. In theSEPS Status
column, AutoUpgrade reports that it checked the password storage access on the target Oracle Database,CDB2
, and confirms that the password works. Because the TDE console functionality to check the password was a feature added in Oracle Database 19c, AutoUpgrade is unable to confirm the password check for TDE on Oracle Database 12c Release 2 (12.2), so the resultUnknown
is expected.If you use a SEPS keystore on the source CDB or target CDB, then AutoUpgrade automatically detects the SEPS keystore as the source for the TDE password. AutoUpgrade uses the
IDENTIFIED BY EXTERNAL STORE
clause, and does not need to load the TDE keystore passwords to the AutoUpgrade keystore. Again, the TDE LIST command should show an emptyAction Required
column.Both options can be used in the same configuration file. For example, if you do not use a SEPS keystore for the source non-CDB database, but you do use a SEPS keystore for the target CDB, then you only need to load a password for the source non-CDB.
- Start the upgrade and
conversion:
$ java -jar autoupgrade.jar -config DB12.cfg -mode deploy
- AutoUpgrade proceeds to upgrade and convert the source non-CDB Oracle Database to a PDB on the target Oracle Database, using the TDE passwords as needed to complete the upgrade.
Caution:
As with any other Oracle Database keystore, protect the AutoUpgrade keystore files:
- Apply restrictive file system permissions
- Audit access
- Back up the keystore