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 on a non-CDB Oracle home, or 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 on a non-CDB Oracle home, or 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 

catctl_options

(Optional) Specifies one or more of a set of catctl.pl options that you can select for AutoUpgrade to submit for catctl.pl to override default behavior. For a complete description of the options, refer to "Parallel Upgrade Utility (catctl.pl) Parameters," which is linked to at the end of this table.

Available catctl.pl options:

• -n Number of processes to use for parallel operations. For Replay upgrades, the number of parallel processes used for the upgrade defaults to the value of (CPU_COUNT divided by 4) . For Classic upgrades, the default for CDB$ROOT is 8.
• -N Number of processors to use when upgrading PDBs. For Replay upgrades, the number of parallel processes used for the upgrade defaults to the value of (CPU_COUNT divided by 4) For Classic upgrades, the default is 2
• -t Run SQL in Classic upgrade overwriting default Replay upgrade method
• -T Takes offline user schema-based table spaces.
• -z Turns on production debugging information for catcon.pm.

Example:

sales4.catctl_options=-t

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 with a new name. 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.

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

(Optional) Specifies custom operating system environment variables set on your operating system, 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.

Syntax:

prefix.env=VARIABLE1=value1/, VARIABLE2=value2/

For example, assume that for the PDB sales2, the value for WALLET_LOCATION is set using custom environment variables:

WALLET_LOCATION=
  (SOURCE=
    (METHOD=file)
    (METHOD_DATA=(DIRECTORY=/databases/wallets/$CUSTOM_ENV1/$CUSTOM_ENV2))

In that case, for AutoUpgrade to know what those custom environment variables are, you must provide them using the env parameter, where dir1 is the path indicated by the environment variable CUSTOM_ENV1, and dir2 is the path specified by CUSTOM_ENV2:

sales2.env=CUSTOM_ENV1=dir1,CUSTOM_ENV2=dir2

log_dir

(Optional with AutoUpgrade 19.8) 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.

When set, AutoUpgrade creates a hierarchical directory based on a local log file path that you specify. 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

By default, if the global configuration file parameter global.autoupg_log_dir is specified, and you do not specify log_dir, then the default is the path specified in global.autoupg_log_dir.

When neither global.autoupg_log_dir nor log_dir is specified, then by default the log files are placed in the location indicated by the orabase utility for the databases that you include in your configuration file. In that case, the default logs directory is in the path ORACLE_BASE/cfgtoollogs/autoupgrade.

If the orabase utility fails for all databases included in the configuration file, then the log file location is then based on the temp directory for the user running AutoUpgrade.

pdbs

(Optional) Sets a list of PDBs on which you want the upgrade to run. This parameter only applies to upgrades of multitenant architecture (CDB) databases. If you are plugging in and upgrading a non-CDB database, then this 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 the parameter is not specified, then the default value is *.

If running in ANALYZE mode, AutoUpgrade ignores the PDBs in a mounted state.

If running in FIXUPS, DEPLOY or UPGRADE mode, AutoUpgrade opens the PDBs in mount state in read-write mode, upgrade mode, or both, depending on the execution mode.

Example:

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

raise_compatible

(Optional) Increases the compatible parameter to the default value of the target release after the upgrade is completed successfully.

Options:

[yes | no]

The default value is no.

CAUTION:

• After the COMPATIBLE parameter is increased, database downgrade is not possible.
• Oracle recommends that you only raise the COMPATIBLE parameter to the current release level after you have thoroughly tested the upgraded database.
• Regardless of what value you use for the autoupgrade command-line parameter restore, if you set the value of the configuration file parameter raise_compatible to yes, then before starting the upgrade, you must delete manually any guaranteed restore point you have created. After the upgrade is completed successfully, AutoUpgrade deletes the guaranteed restore point it creates before starting the upgrade. When AutoUpgrade starts the POSTUPGRADE stage, there is no way to restore the database.

Example:

sales1.raise_compatible=yes

remove_underscore_parameters

(Optional) 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.

Options:

[yes | no]

The default value is no.

Example:

sales1.remove_underscore_parameters=yes

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

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

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

Example:

sales1.sid=salesdb

skip_tde_key_import

(Optional) The default is NO. You can use this option for nonCDB-to-PDB and unplug/plug operations. When set to YES, the upgrade is run, but import of the source database KeyStore into the target database is skipped, without raising an error. AutoUpgrade will leave the PDB open in upgrade mode, so that you can import the keys manually yourself. After you import the keys, you must then restart the database in normal mode.

source_home

(Required for analyze, fixups, and deploy modes. Optional for upgrade mode.) Current Oracle home (ORACLE_HOME) of the database that you want to upgrade. 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. This parameter has no effect on Microsoft Windows, because on Windows, the TNS_ADMIN environmental variable is set within the registry.

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 server, and to prevent multiple jobs from starting immediately.

Values must either take the form now (start immediately), or take the English Date Format form DD/MM/YYYY or MM/DD/YYYY, where MM is month, DD is day, and YYYY is year. If you do not set a value, then the default is now.

Example:

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

Permitted values:

now
30/12/2019 15:30:00
01/11/2020 01:30:15
2/5/2020 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-2019 15:30:00
01/11/2020 3:30:15pm
2020/06/01 01:30:15   

(Optional) Specifies the target ORACLE_BASE path for the target Oracle home.

Example:

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

(Optional) Specifies the SID of the target CDB into which a non-CDB Oracle Database is plugged in. This parameter is mandatory when you want to upgrade and convert a non-CDB Oracle Database.

Example:

emp.target_cdb=salescdb

target_pdb_copy_option=file_name_convert=('f1', 'r1', 'f2', 'r2', 'f3', 'r3'...)

(Optional) This option is only used when creating a pluggable database within the target CDB. It specifies the file_name_convert option that will be used by the create pluggable database statement that is executed by AutoUpgrade when converting a non-CDB database to a PDB or an existing PDB from a different source CDB into a PDB in the specified target CDB. If you do not specify this parameter, then the default value of the parameter is NOCOPY, and existing data files are reused.

On the target CDB, if you have the parameters DB_CREATE_FILE_DEST or PDB_FILE_NAME_CONVERT set, and you want these parameters on the target CDB to take effect, then set the value of prefix.target_pdb_copy_option=file_name_convert=NONE

If you want one or more data file names changed during conversion, then enter values for the parameter to indicate the filename you want to change, and the filename to which you want the existing files copied, using the syntax prefix.target_pdb_copy_option=('f1', 'r1', 'f2', 'r2', . . .), where f1 is the first filename pattern on your source, r1 is the first replacement filename pattern on your target CDB, f2 is the second filename pattern on your source, r2 is the second replacement file pattern on your target CDB, and so on.

Example:

In this example, AutoUpgrade will copy existing datafiles during conversion of a database specified with the prefix string upg1 to replace the file path string and filename /old/path/pdb_2 with the file path string and filename /new/path/depsales:

upg1.target_pdb_copy_option=file_name_convert=('/old/path/pdb_2', '/new/path/depsales') 

To convert OMF files with target_pdb_copy_option=file_name_convert, the target Oracle home must be Oracle Database 19c Release Update 6 or later (19.6.0), or Oracle Database 18c Release Update 10 or later (18.10.0).

In this example, the parameter is configured so that data files that are stored on Oracle ASM, but not stored as Oracle-managed files, are copied from +DATA/dbname/sales to +DATA/dbname/depsales:

upg1.target_pdb_copy_option=file_name_convert=('+DATA/dbname/sales', '+DATA/dbname/depsales')

target_pdb_name

(Optional) Specifies the name that you want to assign to a non-CDB source Oracle Database after is plugged in to the target CDB. The default value is to use the database unique name of the non-CDB Oracle Database. If you want to specify a name that is different from the existing name of the non-CDB when you plug it in to the CDB, then you must set this parameter.

Example:

emp.target_pdb_name=sales2

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

(Optional) Specifies the node on which the current user configuration is valid. The default value is localhost.

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