AutoUpgrade Utility Configuration Files

AutoUpgrade configuration files contain all the information required to perform Oracle Database upgrades.

AutoUpgrade configuration files contain global and local configuration parameters. Global parameters by default apply to all databases addressed by the configuration file. When specified for a specific database, local configuration parameters override global parameters specified by the configuration file.

Global Parameters for the AutoUpgrade User Configuration File

To specify a default behavior for a parameter for all Oracle Database upgrades addressed in the configuration file, you can use the optional AutoUpgrade global parameters.

Usage Notes

All global parameters are optional. All global parameters take the prefix global.

Table 3-1 Global Configuration Parameters for Oracle Database AutoUpgrade Utility

Parameter Description

add_after_upgrade_pfile

Specifies a path and file name of a PFILE whose parameters you want to add after the PFILE is upgraded. This specification applies to all databases in the user configuration file.

Example:

global.add_after_upgrade_pfile=/path/to/my/add_after.ora
add_during_upgrade_pfile

Specifies a path and file name of a PFILE whose parameters you want to have added during the PFILE upgrade. This specification applies to all databases in the user configuration file.

global.add_during_upgrade_pfile=/path/to/my/add_during.ora

after_action

Specifies a path and a file name for a custom user script that you want to have run after all the upgrade jobs finish successfully. The script that you use must be in the form of name.ext (for example, myscript.sh, so that AutoUpgrade can identify the type of script that you want to run. Permitted extension options:

  • Unix shell (.sh)

  • Microsoft Windows batch (.bat, .cmd)

  • Microsoft Windows PowerShell (.ps1)

By default, if the script fails, then AutoUpgrade continues to run. Use the Y flag to specify that AutoUpgrade stops if the operating system detects that your script fails. If the script finishes with a status different than 0, then it is considered a failed completion.

Examples:

If the script fails, then stop AutoUpgrade:

global.after_action=/path/to/my/script.sh Y 

If the script fails, then continue AutoUpgrade:


global.after_action=/path/to/my/script.sh

autoupg_log_dir

Sets the location of the log files, and temporary files that belong to global modules, which AutoUpgrade uses. If you do not use this parameter to set a path, then the log files are placed in the current location where you run AutoUpgrade.

Example:

global.autoupg_log_dir=/path/to/my/global/log/dir

before_action

Specifies a custom user script that you want to have run for all upgrades before starting the upgrade jobs. The script that you use must be in the form of name.ext (for example, myscript.sh), so that AutoUpgrade can identify the type of script that you want to run. If you want to have a script run before a specific upgrade job, then specify that script by using the local parameter (local.before_action)

Permitted extension options:

  • Unix shell (.sh)

  • Microsoft Windows batch (.bat, .cmd)

  • Microsoft Windows PowerShell (.ps1)

By default, if the script fails, then AutoUpgrade continues to run. Use the Y flag to specify that AutoUpgrade stops if the operating system detects that your script fails. If the script finishes with a status different than 0, then it is considered a failed completion.

Examples:

If the script fails, then stop AutoUpgrade:

global.before_action=/path/to/my/script.sh Y 

If the script fails, then continue AutoUpgrade:


global.before_action=/path/to/my/script.sh
del_after_upgrade_pfile

Specifies a path and file name of a PFILE whose parameters you want to have removed during the PFILE upgrade. This specification applies to all databases in the user configuration file.

Example:

global.del_after_upgrade_pfile=/path/to/my/del_after.ora
del_during_upgrade_pfile

Specifies a path and file name of a PFILE whose parameters you want to have removed during the PFILE upgrade. This specification applies to all databases in the user configuration file.

Example:

global.del_during_upgrade_pfile=/path/to/my/del_during.ora

drop_grp_after_upgrade

(Optional) Deletes the Guaranteed Restore Point (GRP) after database upgrade. If you select this option, then GRP is deleted after upgrade completes successfully.

Options:

[yes | no]

The default value is no.

Example:

global.drop_grp_after_upgrade=yes

remove_underscore_parameters

Removes underscore (hidden) parameters from PFILE files during upgrade, and after upgrade, for all Oracle Databases in the configuration file. Underscore parameters should only be used by advice of Oracle Support.

Example:

global.remove_underscore_parameters=yes

restoration

(Optional) Generates a Guaranteed Restore Point (GRP) for database restoration. If you select this option, then both database backup and database restoration must be performed manually by the DBA.

Options:

[yes | no]

The default value is yes.

Example:

global.restoration=no

target_home

Sets a global target home for all of the databases specified in the configuration file. Use this option to avoid specifying the same target_home multiple times. This parameter can be overwritten locally.

Example:

global.target_home=/target/Oracle/home

upgradexml

Generates the upgrade.xml file. Options: [yes | no]

The upgrade.xml is equivalent to the file in earlier releases that the preupgrade package generated when you specified the XML parameter. This file is created during the analyze mode (mode -analyze). It is generated in the preupgrade directory defined for the AutoUpgrade log files.

Example:

global.upgradexml=yes

Local Parameters for the AutoUpgrade Configuration File

To configure information for specific Oracle Databases for the AutoUpgrade utility upgrade, you provide information in the AutoUpgrade local parameters.

Usage Notes

Local parameters take precedence over any global parameters set in the AutoUpgrade configuration file. Except where indicated with (Optional), all local parameters are required. All local parameters take a prefix (in examples, identified by a value you define to identify a particular database or upgrade. The prefix identifies the specific upgrade job to which the parameter applies in the configuration file.

Example: The set of parameters for the first upgrade in the configuration file uses the prefix sales, and the set of parameters for the next upgrade in the configuration file uses the prefix employees:

sales.dbname=hr
sales.source_home=/u01/app/oracle/11.2.0.4/dbhome1
.
.
.
employees.dbname=sales.cdb
employees.source_home-/03/app/oracle/18.0.0.0/dbhome1

Table 3-2 Local Configuration Parameters for Oracle Database AutoUpgrade Utility.

Parameter Description

add_after_upgrade_pfile

(Optional) Specifies a path and file name of a PFILE whose parameters you want to add after the upgrade.

Example:

sales3.add_after_upgrade_pfile=/path/to/my/pfile_add.ora

add_during_upgrade_pfile

(Optional) Specifies a path and file name of a PFILE whose parameters you want to add during the upgrade.

Example:

sales3.add_during_upgrade_pfile=/path/to/my/newpfile.ora

after_action

(Optional) Specifies a custom action that you want to have performed after completing the upgrade job for the database identified by the prefix address.

The script that you use must be in the form of name.ext (for example, myscript.sh, so that AutoUpgrade can identify the type of script that you want to run. Permitted extension options:

  • Unix shell (.sh)

  • Microsoft Windows batch (.bat, .cmd)

  • Microsoft Windows PowerShell (.ps1)

  • Oracle SQL file (.sql), with a local operation only designated by the prefix.

By default, if the script fails, then AutoUpgrade continues to run. Use the Y flag to specify that AutoUpgrade stops if the operating system detects that your script fails. If the script finishes with a status different than 0, then it is considered a failed completion.

In contrast to the global after_action parameter, the local after_action parameter can specify a SQL script, which then runs on the database using the target Oracle Database binaries. The script runs either on the On-Premises database (Non-CDB), or with a multitenant architecture database (CDB), on CDB$ROOT. If you want to run additional container-specific actions, then they must be set within the code. For more complex scenarios, you can run container-specific actions in a shell.

Examples:

Run the specified script before AutoUpgrade starts processing, with the Y flag set to stop AutoUpgrade if the script fails:

sales2.after_action=/user/path/script.sh Y 

Run the specified script before AutoUpgrade starts processing, with AutoUpgrade set to continue to run if the script fails:

sales3.after_action=/user/path/script.sh 

before_action

(Optional) Specifies a custom action that you want to have performed before starting the upgrade job for the specific database job addressed by the prefix. If you want to have a script run before all upgrade jobs, then specify that script by using the local parameter (global.before_action)

The script that you use must be in the form of name.ext (for example, myscript.sh), so that AutoUpgrade can identify the type of script that you want to run. Permitted extension options:

  • Unix shell (.sh)

  • Microsoft Windows batch (.bat, .cmd)

  • Microsoft Windows PowerShell (.ps1)

  • Oracle SQL file (.sql), with a local operation only designated by the prefix.

By default, if the script fails, then AutoUpgrade continues to run. Use the Y flag to specify that AutoUpgrade stops if the operating system detects that your script fails. If the script finishes with a status different than 0, then it is considered a failed completion.

In contrast to the global before_action parameter, the local before_action parameter can specify a SQL script, which can run on the database in the source database Oracle home, using the earlier release Oracle Database binaries. The script runs either on the on-premises database (Non-CDB) or with a multitenant architecture database (CDB), on CDB$ROOT. If you want to run additional container-specific actions, then they must be set within the code. For more complex scenarios, you can run container-specific actions in a shell.

Examples:

Run the specified script before AutoUpgrade starts processing, with the Y flag set to stop AutoUpgrade if the script fails:

sales.before_action=/user/path/script.sh Y 

Run the specified script before AutoUpgrade starts processing, with AutoUpgrade set to continue to run if the script fails:

sales4.before_action=/user/path/script.sh 

checklist

(Optional) Specifies the path to a checklist that you can use to override the default list of fixups that AutoUpgrade performs, such as fixups that you do not want implemented automatically, due to policy or security concerns.

To use this parameter during other AutoUpgrade modes, you must run AutoUpgrade in analyze mode. After AutoUpgrade finishes the analysis, you can then find the checklist file identified by the database name under the precheck directory (dbname_checklist.cfg). Update the file manually to exclude the fixups that you want AutoUpgrade to bypass, and save the file. When you run AutoUpgrade again, you can specify the parameter pointing to the checklist file that you created, and modify fixups that are performed for individual databases. If you do not specify a checklist file path, then the set of fixups that run during the upgrade is the latest version of the checklist file that is created during the deploy mode that you specified.

Example:

sales.checklist=/u01/app/oracle/upgrade-jobs/salesdb_checklist.cfg

In the preceding example, salesdb_checklist.cfg is the checklist configuration file for the database salesdb.

dbname

Identifies the DB_UNIQUE_NAME value of the database that you want to upgrade. .

In the configuration file:
sales.dbname=salesdb

del_after_upgrade_pfile

(Optional) Specifies a path and file name of a PFILE whose parameters you want to remove after the upgrade.

Example:

sales3.del_after_upgrade_pfile=/path/to/my/pfile_del.ora

del_during_upgrade_pfile

(Optional) Specifies a path and file name of a PFILE whose parameters you want to have removed during upgrade.

Example:

sales3.del_during_upgrade_pfile=/path/to/my/oldpfile.ora

env

Specifies your custom operating system environment variables, excluding ORACLE_SID, ORACLE_HOME, ORACLE_BASE, and TNS_ADMIN.

Use Case:

Use this parameter to provide environment setting that are indicated in the database sqlnet.ora file, such as secure socket layer cipher suites that are used for Oracle Wallet.

Example:

sales2.env=VARIABLE1:/value1/,VARIABLE2:/value2/

log_dir

Sets the location of log files that are generated for database upgrades that are in the set of databases included in the upgrade job identified by the prefix for the parameter. AutoUpgrade creates a hierarchical directory based on that log file path. For example, where the job identifier prefix is sales, and where log_dir is identified as upgrade-jobs, and stage1, stage2, and stagen represent stages of the upgrades:

/u01/app/oracle/upgrade-jobs
                                      /temp/
                                      /sales/
                                      /sales/stage1
                                      /sales/stage2
                                      /sales/stagen

You cannot use wild cards for paths, such as tilde (~). You must use a complete path.

Example:

salesdb.log_dir=/u01/app/oracle/upgrade-jobs

pdbs

(Optional) Sets a list of PDBs on which you want the upgrade to run. This parameter only applies to multitenant architecture (CDB) databases. If the database on which you are running AutoUpgrade is an on-premises Oracle Database, then the parameter is ignored.

The PDB list is comma-deliminated. The list can contain either PDB names, or a star character (*), which indicates that you want to upgrade all PDBs that are open on the CDB at the time that you run AutoUpgrade. If a PDB is mounted, then AutoUpgrade ignores that PDB for the analyze deployments. However, if the PDB is in mount state, and the deploy mode is fixups, deploy or upgrade, then the PDB is opened in read-write mode, or upgrade mode, or both, so that the stages can run.

Example:

sales1.pdbs=pdb1, pdb2, pdbn
   upgr1.pdbs=*

restoration

(Optional) Generates a Guaranteed Restore Point (GRP) for database restoration. If you set restoration=no, then both the database backup and restoration must be performed manually. Use this option for databases that operate in NOARCHIVELOG mode, and for Standard Edition and SE2 databases, which do not support the Oracle Flashback technology feature Flashback Database.

Options:

[yes | no]

The default value is yes.

Example:

sales1.restoration=no

run_utlrp

(Optional) Enables or disables running utlrp as part of the upgrade.

The utlrp utility recompiles all Data Dictionary objects that become invalid during a database upgrade. Oracle recommends that you run this utility after every Oracle Database upgrade. Options: yes, no. The default is enabled (yes).

Example:

prefix.run_utlrp=yes

sid

Identifies the Oracle system identifier (SID) of the database that you want to upgrade.

Example:

sales1.sid=salesdb

source_home

Current Oracle home (ORACLE_HOME) of the database that you want to upgrade. This parameter is particularly of use for the modes analyze, fixups, and deploy. For the mode upgrade, the source home and target home values can be the same path.

Example:

sales2.source_home=/path/to/my/source/oracle/home

source_tns_admin_dir

(Optional) Specifies the path to the TNS_ADMIN directory in the source database home.

Example:

sales1.source_tns_admin_dir=/u01/app/oracle/12.2/dbhome01/network/admin

start_time

(Optional) Sets a future start time for the upgrade job to run. Use this parameter to schedule upgrade jobs to balance the load on your serer, and to prevent multiple jobs from starting immediately.

Values must either take the form now (start immediately), or take the form 00/00/0000 00:00:00. If you do not set a value, then the default is now.

Example:

sales1.start_time=now
sales2.start_time=01/11/2019 01:30:15

Permitted values:

now
30/12/2018 15:30:00
01/11/2019 01:30:15
2/5/2019 3:30:50

If more than one job is started with the start_time value set to now, then AutoUpgrade schedules start times based on resources available in the system, which can result in start time for jobs that are separated by a few minutes.

Values are invalid that use the wrong deliminator for the date or time element, or use the wrong date or hour format.

Example:

30-12-2018 15:30:00
01/11/2019 3:30:15pm
2019/06/01 01:30:15   

target_tns_admin_dir

(Optional) Specifies the path to the TNS_ADMIN directory in the target database home.

Example:

sales1.target_tns_admin_dir=/u01/app/oracle/19.0.0.0/dbhome01/network/admin

timezone_upg

(Optional) Enables or disables running the time zone upgrade as part of the AutoUpgrade process. To preserve data integrity, Oracle recommends that you upgrade the time zone settings at the time of your database upgrade. In particular, upgrade the timezone when you have data that depend on the time zone, such as timestamp with time zone table columns. Note that this setting can be disabled by overwriting the fixup on the checklist file. Options: yes, no. The default is enabled (yes).

Example:

sales1.timezone_upg=yes

upgrade_node

Specifies the node on which the current user configuration is valid.

The purpose of this parameter is to prevent AutoUpgrade from processing databases that are listed in the configuration file that you use with AutoUpgrade, where the value for the upgrade_node parameter does not correspond to the current host name. It does not enable running AutoUpgrade remotely. You can use the keyword localhost as a wild card to indicate that databases on the local host should be processed.

Use case:

The configuration file config.cfg contains 10 databases. Five of the databases have the value of upgrade_node set to denver01. The remaining five have the value of upgrade_node set to denver02. If AutoUpgrade is run on the server denver01 using the configuration file config.cfg, then AutoUpgrade only processes the databases where upgrade_node is set to denver01. It ignores the databases where upgrade_node is set to denver02. The utility hostname identifies the value used to resolve the upgrade node

Example:

hostname
denver02
sales1.upgrade_node=denver01

Locally Modifiable Global Parameters for AutoUpgrade Configuration File

Locally modifiable global parameters are parameters that you set both globally, and as you require, set locally, so that you can better control AutoUpgrade job processing.

Usage Notes

Locally modifiable global parameters are required parameters. You must define these parameters in your AutoUpgrade configuration file, either globally, or locally. With locally modifiable global parameters, you can use the prefix global to set values as global parameters for all jobs in your AutoUpgrade configuration file, but reset the same parameter with a local job prefix for a particular job in the same configuration file. You can also choose to set locally modifiable global parameters only as local parameters for each AutoUpgrade job.

When a locally modifiable global parameter is set both with a global prefix, and with a local job prefix, the locally modified parameter value overrides the global parameter values for the job identified by the prefix that you use with the parameter. The syntax you use is in the form global.target_home=Global target Oracle home, and database.target_home=local target Oracle home.

Example:

In the AutoUpgrade configuration file, the required parameter target_home is set globally to one Oracle home path. But in the configuration file, the same parameter is set locally to a different Oracle home path. As AutoUpgrade processes the jobs in the configuration file, it uses the locally defined path for target_home for the job defined by the prefix upgrade3, overriding the global parameter setting:

global.target_home=/u01/app/oracle/19.0.0.0/dbhome01
upgrade3.target_home=/u03/app/oracle3/12.2.0.1/dbhome3

Table 3-3 Locally Modifiable Global Parameters for AutoUpgrade Configuration Files

Parameter Description

target_version

(Optional) Specifies the target release version on which you want AutoUpgrade to perform the upgrade. AutoUpgrade uses the release version information that you provide in this parameter to ensure that the correct checks and fixups are used for the target Oracle Database release to which you are upgrading. The format for this parameter are period-delimited values of valid Oracle versions.

Valid values

  • 12.2
  • 18
  • 19
  • 20

This option is only required if the target home is not present on the system, or if the target home is a 12.2 release. Otherwise, AutoUpgrade can derive the target release value.

Example:

global.target_version=18
employees.target_version=12.2
target_home

Specifies the target Oracle home (ORACLE_HOME) path.

Example:

global.target_home=/u01/app/oracle/19.0.0/dbhome01
sales4.target_home=/u04/app/oracle4/19.0.0/dbhome04
target_base

Specifies the target ORACLE_BASE path for the target Oracle home.

Example:

global.target_base=/u01/app/oracle
sales4.target_base=/u04/app/oracle4