Examples

Examples

Usage Notes

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.

The output of the script is captured and stored in files. Both stdout and stderr are captured. The files are stored in the postupgrade subdirectory in the directory matching the specific database or job.

The following environment variables are set in the shell that runs the script:

• ORACLE_SID
• ORACLE_UNQNAME
• ORACLE_BASE
• ORACLE_HOME
• TNS_ADMIN

Examples

Run the specified script after 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 after AutoUpgrade starts processing the deploy option, with AutoUpgrade set to continue to run if the script fails:

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

Usage Notes

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.

The output of the script is captured and stored in files. Both stdout and stderr are captured. The files are stored in the preupgrade subdirectory in the directory matching the specific database or job.

The following environment variables are set in the shell that runs the script:

• ORACLE_SID
• ORACLE_UNQNAME
• ORACLE_BASE
• ORACLE_HOME
• TNS_ADMIN

Examples

Run the specified script before AutoUpgrade starts processing deploy mode, 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 

Usage Notes

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 and NON-CDB databases 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 Takes offline user schema-based table spaces.
• -z Turns on production debugging information for catcon.pl.

Examples

sales4.catctl_options=-n 24 -N 4

Usage Notes

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.

Examples

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.

Usage Notes

During the operations described above, if close_source is set to yes (the default), then AutoUpgrade closes source non-CDB or source PDB just before starting the upgrade. Additionally, if Oracle Real Application Clusters or Oracle Grid Infrastructure (CRS) services are configured for a non-CDB source, then they are disabled before starting the upgrade.

This parameter can only be used when the source and target databases are both on the same system. When they are on different systems, the source non-CDB or PDB cannot be closed, because AutoUpgrade has no access to it.

Options

[yes | no]

The default value is yes.

Examples

sales3.close_source=yes

Examples

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

Examples

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

Usage Notes

When set to NO, AutoUpgrade does not delete the Microsoft Windows file credential after the AutoUpgrade job first using the credential is completed. The default value is YES.

The purpose of this parameter is to enable you to choose whether AutoUpgrade immediately deletes the Microsoft Windows object credentials loaded with the wincredential parameter after these credentials are first used, or if you want to be able to reuse the Windows object credential with other AutoUpgrade patching or upgrading operations.

Use case:

You are performing multiple upgrades or patching operation with AutoUpgrade, and you want to specify credentials for the owner of database binaries on a Microsoft Windows server for more than one upgrade or patching operation so that they can all complete automatically. When you specify the wincredential parameter to load the credentials, and then also specify delete_wincredential_file to NO, AutoUpgrade can use that credential for multiple upgrades or patches of the same Oracle Database, or for different Oracle Databases. To use this feature, you must have already created the Windows PowerShell credential object, and then specify that credential object in the configuration file using wincredential.

Example

In the following example, the local configuration file setting wincredential provides the location where the Microsoft Windows credentials have been loaded, and delete_wincredential_file=NO specifies that AutoUpgrade does not automatically delete the Windows object credential file after the db12201 database operation is complete.

global.autoupg_log_dir=C:\Users\oracle\autoupg
global.target.version=19.0.0
global.target_home=C:\u01\app\oracle\product\19\dbhome_1
 
upg1.sid=db12201
upg1.source_home=C:\u01\app\oracle\product\12.2\dbhome_1
upg1.log_dir=C:\Users\Oracle\autoupg
upg1.upgrade_node=localhost
upg1.target_base=C:\u01\app\oracle
upg1.target_version=19.0.0.0
upg1.wincredential=C:\Users\oracle\cred
upg1.delete_wincredential_file=NO

Usage Notes

Specifies whether to automatically download patches from My Oracle Support. The default is YES.

When set to YES, you must either load My Oracle Support (MOS) credentials or an OAUTH token into AutoUpgrade Patching at the command line using the -load_password command-line option.

The patches that are downloaded are placed into the directory folder specified by the folder parameter.

If proxy information is required to connect to My Oracle Support, then set proxy values using the Linux operating system environment variables https_proxy, http_proxy, and no_proxy.

The supported format of the proxy definition is as follows, where user_info is a user account, site is a URL, and port is a designated port for the proxy listener:

[https|http|socks5|socks]://(user_info@)site:port

Adding user_info to the proxy definition is optional, and has a format of username:password for the credentials of the proxy.

Options

[yes | no]

The default value is yes.

Examples

Override the default (yes) so that you use patches that you have downloaded manually instead of having AutoUpgrade download the patches automatically:

upg1.download=no 

Usage Notes

If you select this parameter option, then GRP is deleted after the AutoUpgrade patch maintenance completes successfully.

Options

[yes | no]

The default value is no.

Example

sales4.drop_grp_after_patching=yes

Usage Notes

By default, for Oracle Database upgrades on Microsoft Windows operating systems, after AutoUpgrade shuts down the Windows Oracle Database service and completes the upgrade, it leaves the service in place. Leaving the service down but in place gives you the option to restore the database to the source Oracle home without having to recreate the Microsoft Windows service for the database. However, you can choose to have the Microsoft Windows service for the source database removed automatically after upgrade is completed successfully. If either no is specified, or no value is is specified, then the service is shut down on the source, but left in place after the upgrade.

Options

[yes | no]

The default value is no.

Examples

upg1.drop_win_src_service=yes 

Usage Notes

The Enterprise Manager command-line interface (EMCLI) enables AutoUpgrade to use scheduled blackouts to suspend any data collection activity on one or more monitored targets. Use this parameter to provide a specific suffix for AutoUpgrade blackouts. By default, when you enable the use of EMCLI to create blackouts, the default blackout name in the EMCLI log file is as follows, where sid is the system identifier of the database where the blackout is enabled:

blackout_AutoUpgrade_sid

If you specify em_blackout_suffix, then in addition to the system identifier (sid), you can specify a suffix, so that you can track AutoUpgrade processes more precisely (blackout-suffix).

Syntax

em_blackout_AutoUpgrade_sid_blackout-suffix

Example

Suppose you are updating a set of upgrades in your configuraiton file, and in the set of upgrades specified with the prefix upg1, you want to attach a suffix to the database with the system identifier sales1. The suffix you choose is q3-updates. To do this, you use em_blackout_autoupgrade as follows:

upg1.em_blackout_autoupgrade_sid_q3-updates

Usage Notes

AutoUpgade can use the Enterprise Manager command-line interface (EMCLI) to update Enterprise Manager monitoring to the new Oracle Database home. However, you must provide the name of the database so that AutoUpgade is configured to update the database to the new Oracle home.

Syntax

Enter the parameter in your configuration file, where database-sid is the database system identifier for the database where you need to update the monitored Oracle home:

em_target_name=database-sid

Example

Update the Enterprise Manager monitored database sales1 to point to the new Oracle Home

upg1.em_target_name=sales1

Usage Notes

AutoUpgade can use the Enterprise Manager command-line interface (EMCLI) to perform tasks during upgrade or patching. However, to access the command, you must provide AutoUpgrade the path to the EMCTL path for the database that EMCTL is monitoring to update the monitored database to the new Oracle home.

Syntax

emctl_path=path-to-emctl-location

Example

Suppose you are updating a set of upgrades in your configuration file, and in the set of upgrades specified with the prefix upg1, you want to update Enterprise Manager monitored databases to their new Oracle home. The path to the Enterprise Manager command-line interface home is var/opt/dbascripts/emcli/. To do this, you use emctl_path as follows:

upg1.emctl_path=var/opt/dbascripts/emcli/

Usage Notes

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. Multiple settings are comma-delimited.

Syntax:

prefix=VARIABLE1=value1 [, VARIABLE2=value2, ...]

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

Usage Notes

Use this parameter to provide a list of PDBs to exclude from the AutoUpgrade run. The PDB list is comma-delimited. It can contain either a list of PDB names, or an asterisk character (*), which indicates that you want ot exclude all PDBs that are open on the CDB at the time that you run AutoUpgrade.

Syntax:

prefix.exclusion_list=[pdb-name|*][,pdb-name,...]

Examples

Assume that you want to exclude PDBs pdb1 and pdb2 from the upgrade of cdb sales1. The following entry in the configuration file excludes pdb1 and pdb2 from being processed during the AutoUpgrade run:

sales1.exclusion_list=pdb1,pdb2

This entry in the configuration file excludes all open PDBs from the CDB sales2:

sales2.exclusion_list=*

Usage Notes

For AutoUpgrade to perform patching, you must identify the directory that contains the patch zip files. This directory must also contain the Oracle Database base image. There is no default value. You must provide the directory path. This parameter also is used in conjunction with the download parameter as follows:

When download=YES, the directory specified by the folder parameter is the directory to which the patches will be downloaded

When download=NO, the directory specified by the folder parameter is the directory that must contain the patches that have been manually downloaded.

The directory that you specify with the folder parameter must contain the base image of the source database's release (for example, Oracle Database Release 19.3).

Examples

upg1.folder=/storage/patches

Usage Notes

If you add this parameter to your configuration file, then the error numbers that you specify are ignored during the upgrade for the upgrade prefix that you specify.

Examples

sales3.ignore_errors=ORA-48181,ORA-00001

Usage Notes

This parameter applies to the Unplug-Plug flow (including restorations). If the PDB state is saved in the source CDB, then by default that same saved state continues to be saved after the upgrade process (default is yes). When keep_pdb_save_state is set to no, the source PDB state is not saved after the upgrade. You can choose to set keep_pdb_save_state to no when you are advised to do so in AutoUpgrade preupgrade checks. For example, with Oracle Real Application Clusters (Oracle RAC) upgrades, Oracle recommends that you do not keep the source PDB saved state.

Options

[yes | no]

The default value is yes.

Example

sales1.keep_pdb_save_state.pdbA=no

Usage Notes

By default, the source PDB is removed from the source CDB during the upgrade process. When keep_source_pdb is set to YES, the source PDB is not removed from the earlier release system. You are only able to set the parameter to YES when the copy option is specified in the parameter target_pdb_copy_option. When the copy option is not used, this parameter is ignored, because the PDB must be dropped. Without a copy, the existing datafiles can only be used by a single CDB.

Options

[yes | no]

The default value is no.

Example

sales1.keep_source_pdb=yes

Usage Notes

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.

Usage Notes

Before upgrades of database configurations with standby databases, to reduce potential issues, Oracle recommends that you run AutoUpgrade in analyze mode on your standby databases.

Options

In the following syntax, pdb-name is a DB_UNIQUE_NAME of a source PDB that you are upgrading to the target CDB in an unplug/plug upgrade.

manage_standbys_clause=STANDBYS=[NONE|ALL|ALL EXCEPT ('pdb-name', 'pdb-name', ...)|STANDBYS=('pdb-name', 'pdb-name', ...)]

The default value is NONE.

Examples

upg2.sid=cdb1 
upg2.pdbs=* 
upg2.target_cdb=cdb21x 
upg2.source_home=/source/18x 
upg2.target_home=/target/21x
upg2.manage_standbys_clause=standbys=none

In the following example, applying the redo on data files on all standby databases is deferred on all AutoUpgrade plug-in upgrades:

upg3.sid=cdb2 
upg3.pdbs=* 
upg3.target_cdb=cdb21x 
upg3.source_home=/source/18x 
upg3.target_home=/target/21x
upg3.manage_standbys_clause=standbys=all

In the following example, during the AutoUpgrade plug-in upgrades, applying the redo on data files is deferred on all standby PDBs except PDBs cdb3_stby_1 and cdb3_stby_2.

upg4.sid=cdb3 
upg4.pdbs=* 
upg4.target_cdb=cdb21x 
upg4.source_home=/source/12.2x 
upg4.target_home=/target/21x
upg4.manage_standbys_clause=standbys=all except ('cdb3_stby_1','cdb3_stby_2')

In the following example, during the AutoUpgrade plug-in upgrades, applying the redo on data files is deferred only on standby PDB cdb4_stby1.

upg4.sid=cdb4 
upg4.pdbs=* 
upg4.target_cdb=cdb21x 
upg4.source_home=/source/12.2x 
upg4.target_home=/target/21x
upg4.manage_standbys_clause=standbys=('cdb4_stby_1')

Usage Notes

The default value is outofplace. At the time of this release, outofplace is the only permitted value. When the AutoUpgrade command-line parameter -patch is used, AutoUpgrade creates a new target Oracle home using the base image contained in the directory specified by the folder parameter. Oracle recommends that all patching is performed as out-of-place patching, where a new Oracle home is created.

Examples

upg1.method=outofplace

Usage Notes

This parameter is optional. You can use this parameter to specify the number of parallel execution servers to copy the new PDB's data files to a new location when creating a PDB. This may result in faster creation of the PDB. Scenarios where you can take advantage of this option is when you want to upgrade and convert a non-CDB Oracle Database to a PDB, or you want to unplug a PDB from a source release CDB and relocate it in for an upgrade to a target release CDB.

The parameter is specific for every source database or pluggable database on the AutoUpgrade configuration file. The CDB can ignore this setting, depending on the current database load and the number of available parallel execution servers. Using this parameter enables you to provide better control of the load placed on the target database.

Options

Use an integer value to specify the number of servers to run in parallel, where source-db-name-or-pdb is the non-CDB database name or the PDB name, and integer-value is a numeric value specifying the number of servers to run in parallel::

prefix.parallel_pdb_creation_clause.source-db-name-or-pdb='integer-value'

Example

In the following example, 16 servers are specified as the limit for the number of servers to run in parallel.

upg1.parallel_pdb_creation_clause.pdb1=16

Usage Notes

Required for AutoUpgrade patching.

Options

[recommended|ru|ru:x.y|opatch|ojvm|ojvm:x.y|dpbp|patch-number]

The default value is RECOMMENDED.

Options:

• RECOMMENDED: Alias for all of the following options: RU, OPATCH, OJVM, DPBP.

• RU: Latest release update

• RU:x.y: A release update (RU) of the specified release version, where x is the major release number, and y is the RU. For example: RU:19.24

• OPATCH: Use latest version of OPatch

• OJVM: Apply the Oracle Java VM patch that applies to the specified RU.

• OJVM:x.y: Apply the Oracle Java VM patch of the specified release version, where x is the major release number, and y is the RU. For example: OJVM:19.24

• DPBP: Apply the Oracle Data Pump patch for the specified RU

• patch-number[,patch-number,patch-number...] specifies one or more specific one-off patches that you want AutoUpgrade to apply, in order of priority.

Examples

patch-number: Provide a specific one-off patch number.

upg1.patch=ru:19.24,12345678,opatch

Apply recommended patches, which includes the set of recommended patch options: RU (the latest release update for the base image), as well as OPATCH, OJVM, and DPBP:

upg1.patch=recommended

Usage Notes

In AutoUpgrade 23.4 and earlier versions, the default for patching has been to perform patching in upgrade mode. Starting with AutoUpgrade 24.1, the default is to perform patching in normal mode. If you prefer to perform patching only in upgrade mode, then you can use this parameter to override that default behavior, and patch in upgrade mode.

Options

[yes | no]

The default value is no.

Example

sales.patch_in_upgrade_mode=yes

Usage Notes

The purpose of this parameter is to prevent AutoUpgrade patching from processing databases that are listed in the configuration file that you use with AutoUpgrade, where the value for the patch_node parameter does not correspond to the current host name. It does not enable running AutoUpgrade patching 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 patch_node set to denver01. The remaining five have the value of patch_node set to denver02. If AutoUpgrade is run on the server denver01 using the configuration file config.cfg, then AutoUpgrade only processes the databases for patching where patch_node is set to denver01. It ignores the databases where patch_node is set to denver02. The utility hostname identifies the value used to resolve the upgrade node.

Example

hostname
denver02
sales1.patch_node=denver01

Usage Notes

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=*

Usage Notes

The parameter platform specifies which platform patches AutoUpgrade uses for patching. AutoUpgrade Patching supports the following platforrms:

• AIX.x64 IBM AIX on POWER Systems (64-Bit)
• ARM.x64 LINUX ARM (aarch64)
• LINUX.X64 Linux x86-64
• SPARC.x64 Oracle Solaris on SPARC (64-Bit)
• SOLARIS.x64 Oracle Solaris on x86-64 (64-Bit)
• WINDOWS.X64 Microsoft Windows x64 (64-bit).

If the current operating system is one of the supported platforms, then the default value matches that platform. Otherwise, the default value is LINUX.X64

Options

[AIX.x64|ARM.x64|LINUX.X64|SPARC.x64|SOLARIS.x64|WINDOWS.X64]

The default value is LINUX.X64.

Example

upg1.platform=LINUX.X64

Usage Notes

Options:

• Y : Increase the COMPATIBLE parameter setting to the target release
• N : Do not increase the COMPATIBLE parameter setting to the target release
• Increase the COMPATIBLE level to a specific release update (RU) level (for example, 23.0, 23.4, 23.7)

The default is N.

Examples

Raise COMPATIBLE to the level of the target Oracle Database home:

sales1.raise_compatible=yes

Raise COMPATIBLE to RU 23.4:

sales1.raise_compatible=23.4

Raise COMPATIBLE to RU 23.7:

sales1.raise_compatible=23.7

Usage Notes

By default, the source Oracle RAC database configuration on a non-CDB is removed from the source Oracle Grid Infrastructure when it is migrated to a CDB during the upgrade process. When remove_rac_config is set to no, the source Oracle RAC database is not removed from the earlier release non-CDB system.

Options

[yes | no]

The default value is yes.

Example

upg1.remove_rac_config=no

Usage Notes

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

Usage Notes

By default, AutoUpgrade performs a Classic upgrade to upgrade the database.

Options

[yes | no]

The default value is no.

ALTER PLUGGABLE DATABASE UPGRADE SYNC ON

Example

upg1.replay=yes

Usage Notes

If left at default value (yes), a fast recovery area configuration is required to create a GRP. If you set restoration=no, then both the database backup and restoration must be performed manually. Set to no for databases that operate in NOARCHIVELOG mode, and for Standard Edition and Standard Edition 2 databases, which do not support the Oracle Flashback technology feature Flashback Database. If you do not specify the parameter, then the default value (yes) is used, and a guaranteed restore point is created.

Options

[yes | no]

The default value is yes.

Example

sales1.restoration=no

Usage Notes

The action that you specify with revert_after_action runs on the target Oracle home binaries after the restoration process is completed, and the database is up.

The script that you specify to run 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 script (.sql), with a local operation on the database designated by the revert_before_action parameter prefix.

Options

Stop on fail: [Y|N]. The default is N.

By default, if the specified script fails, then AutoUpgrade continues to run (N. To specify that AutoUpgrade stops if the script fails, use the Y flag. If the script finishes running on the operating system with a status different than 0, then AutoUpgrade identifies the script as failed.

Examples

Run the script you specify on the operating system after AutoUpgrade completes processing the restoration, with the Y flag set to stop AutoUpgrade if the script fails:

sales3.revert_after_action =/user/path/script.sh Y

Run the script you specify on the operating system after AutoUpgrade completes processing the restoration. With no flag, the default stop on fail option is N, so AutoUpgrade continues to run if the script fails:

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

Usage Notes

The action that you specify with revert_before_action runs on the target Oracle home binaries before database restoration is started, and the database is up.

The script that you specify to run 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 script (.sql), with a local operation on the database designated by the revert_before_action parameter prefix.

Options

Stop on fail: [Y|N]. The default is N.

By default, if the specified script fails, then AutoUpgrade continues to run (N. To specify that AutoUpgrade stops if the script fails, use the Y flag. If the script finishes running on the operating system with a status different than 0, then AutoUpgrade identifies the script as failed.

Examples

Run the script you specify on the operating system before AutoUpgrade starts the restoration, with the Y flag set to stop AutoUpgrade if the script fails:

sales3.revert_before_action =/user/path/script.sh Y

Run the script you specify on the operating system before AutoUpgrade starts the restoration. With no flag, the default stop on fail option is N, so AutoUpgrade continues to run if the script fails:

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

Usage Notes

To help to identify database dictionary inconsistencies, you can specify that AutoUpgrade runs the DBMS_DICTIONARY_CHECK PL/SQL package on the source database as part of preupgrade checks. If set, the AutoUpgrade run_dictionary_health parameter enables you to specify for each upgrade source database that AutoUpgrade runs either the full array of Oracle Dictionary Health Checks on the database dictionary, or that it runs only the most critical set of checks. If the check detects potential or critical problems with the database dictionary, then it prevents the upgrade from starting.

Oracle Dictionary Health Check results are stored under the AutoUpgrade precheck directory in the format dbname_healthcheck_result.log, where dbname is the name of the database on which the check was run. For more information about Oracle Dictionary Health Check, refer to the DBMS_HCHECK package documentation in Oracle Database PL/SQL Packages and Types Reference.

Options

[full| critical]

If the parameter is not set, then the default is to not run DBMS_DICTIONARY_CHECK.

Example

sales1.run_dictionary_health=full
sales2.run_dictionary_health=critical

Usage Notes

The utlrp utility recompiles all Data Dictionary objects that become invalid during a database upgrade. If you set run_utlrp=no, or if you want invalid user objects also to be recompiled, then Oracle recommends that you use this utility to recompile invalid objects after upgrading with AutoUpgrade.

Options

[yes | no]

The default value is yes.

Example

prefix.run_utlrp=yes

Usage Notes

This parameter is case-sensitive.

Example

sales1.sid=salesdb

Usage Notes

You can use this option for nonCDB-to-PDB and unplug/plug operations. When import of the source database KeyStore into the target database is skipped, 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.

Options

[yes | no]

The default value is no.

Example

sales1.skip_tde_key_import=yes

Examples

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

Usage Notes

To set up an unplug-plug relocate upgrade for a non-CDB or a PDB, you must first set up a database link between the source database and the target database location. You then pass that database link to AutoUpgrade using the source_dblink parameter. You identify source database name associated with the database link as a suffix to source_dblink. parameter. You also have the option to specify a time value, in seconds, that the database is refreshed from the database link.

The source_dblink parameter becomes active when you use the target_pdb_copy_option parameter. When you use source_dblink, you must also must specify a value for the file_name_convert parameter, either to convert file names, or to specify not to convert file names. If file_name_convert is set to none, then you must also set db_create_file_dest to specify where you want to place the database files.

You can also choose to set a refresh interval, in seconds, specifying how frequently the target database is updated over the database link from the source database. You can use the refresh interval with the start_time parameter to keep the source database refreshed for the target location. If no refresh rate is specified, then the source database is cloned only one time, and no refresh occurs. If the refresh rate is specified, but you do not specify a future start time using the start_time parameter, then the refresh interval value is ignored, and the database is cloned only one time.

Options

• (Required) The source database name, specified as a suffix.
• (Required) The name of the database link that you created.
• (Optional) The refresh rate for the target database from the source database, in seconds. If you specify a refresh rate, then typically you also specify a future start time using the start_time parameter.
• (Optional) CLONE_ONLY. Adding this option specifies that the PDB that is created is a clone that is never refreshed, and that the upgrade is started immediately after the clone operation is completed. This option is required when the source is Oracle Database 12.1 (Release 12.1.0.2).

Examples

In the AutoUpgrade configuration file, the database name associated with the database link is specified by using that name as a suffix to source_dblink: The suffix: pdbx for the PDB source database, and the suffix db18x for the non-CDB source database.

upg1.source_dblink.pdbx=pdbxcdb18x

Using the same configuration file, AutoUpgrade starts the upgrade of the database named db18x in 1 hour and 40 minutes after AutoUpgrade is started from the command line. Between the time that AutoUpgrade is started, and the deployment time specified by start_time, the cloned target database is refreshed every 20 seconds from the source.

upg1.source_dblink.db18x=db18x_link 20 
upg1.start_time=+1h40m

In the following example, the source database db18x is cloned to the target PDB db18x_link, and the upgrade is started immediately after that source database is cloned successfully:

upg1.source_dblink.db18x=db18x_link CLONE_ONLY

Usage Notes

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

Usage Notes

This parameter has no effect on Microsoft Windows, because on Windows, the LDAP_ADMIN environmental variable is set within the registry.

Example

sales1.source_ldap_admin_dir=/u01/app/oracle/12.2/dbhome01/ldap/admin

Usage Notes

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

Usage Notes

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.

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 that use the wrong date or hour format, such as the following:

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

Examples

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

Examples

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

Usage Notes

This parameter is mandatory when you want to upgrade and convert a non-CDB Oracle Database. It is case-sensitive.

Example

emp.target_cdb=salescdb

Usage Notes

This option is only used when creating a pluggable database within the target CDB. If you do not specify this parameter, then the default value of the parameter is NOCOPY, and existing data files on the source database are reused. When you do specify this parameter, then you must append a suffix to the parameter that specifies either the source database name or PDB name (target_pdb_copy_option.suffix, and specify file_name_convert= with one of the following options:

• Specify source file names (f) and target replacement file names (r) ('f', 'r'), or specify NONE
• If you are creating a refreshable clone database, then append a suffix to the parameter that specifies either the source database name or PDB name (target_pdb_copy_option.suffix

On the target CDB, if you are using ASM, or 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 for replacement file names, then set the value of prefix.target_pdb_copy_option.source-db-name-or-pdb=file_name_convert=NONE.

If you want one or more data file names changed during conversion on the target CDB, then enter values for the parameter to indicate the source database name or PDB, specified as a suffix, the source filename you want to change, and the target filename to which you want the existing files copied, using the syntax prefix.target_pdb_copy_option.source-db-name-or-pdb=('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.

Syntax

prefix.target_pdb_copy_option.source-db-name-or-pdb=file_name_convert=('f1', 'r1', 'f2', 'r2', 'f3', 'r3'...)

Example

In this example, AutoUpgrade will copy existing datafiles during conversion of a database specified with the prefix string upg1, and with the suffix sales 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.sales=file_name_convert=('/old/path/pdb_2', '/new/path/depsales') 

To convert OMF files with target_pdb_copy_optionsource-db-name-or-pdb=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.sales=file_name_convert=('+DATA/dbname/sales', '+DATA/dbname/depsales')

Usage Notes

This parameter is optional. It is used when you want to upgrade and convert a non-CDB Oracle Database to a PDB, or you want to unplug a PDB from a source release CDB and plug it in for an upgrade to a target release CDB.

When you upgrade and convert an existing non-CDB database to a PDB on a target CDB, the target_cdb parameter is mandatory, because it specifies the target CDB. If you want to determine how the PDB is created on the target CDB, you can use the optional parameters target_pdb_name and target_pdb_copy_option to specify how the PDB is created on the target CDB. However, if neither optional parameters are used, then a full upgrade of the source CDB is performed.

The default name for the target PDB when you convert a non-CDB to a PDB is to use the database unique name of the non-CDB Oracle Database. To specify a name that is different from the existing name of the non-CDB when you plug it in to the CDB, set the new name by using target_pdb_name. In addition, if you are creating a refreshable clone database, then append a suffix to the parameter that specifies either the source database name or PDB name (target_name.suffix)

Examples

upg.target_pdb_name=emp23pdb

For a refreshable clone, add a prefix to indicate the source database for the clone. In this example, the source container database is db122b and we are cloning pdb1 from db122b into the target container database db19. The suffix pdb1 is used as the identifier for both target_pdb_name and source_dblink. The pdb1 suffix identifier associates both the target PDB name and the dblink used to move the data from the source, pdb1, into the target PDB PLUG122.

global.autoupg_log_dir=/tmp/logs
upg1.source_home=/u01/app/oracle/122
upg1.target_home=/u01/app/oracle/19
upg1.sid=db122b
upg1.target_cdb=db19
upg1.pdbs=pdb1
upg1.target_pdb_name.pdb1=PLUG122
upg1.target_pdb_copy_option.pdb1=file_name_convert=('/u01/app/oracle/oradata/db122b/pdb1', '/u01/app/oracle/plug/pdb122b')
upg1.source_dblink.pdb1=pdbxcdb122x_link

Example

sales1.target_ldap_admin_dir=/u01/app/oracle/19/dbhome01/ldap/admin

Example

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

Usage Notes

The purpose of this parameter is to ensure that the proper set of patches are downloaded or installed into the target Oracle home that is being created. For AutoUpgrade patching, the local parameter target_version is only required if both of the following conditions are true:

1. The source_home parameter is not specified in the configuration file
2. The patch parameter does not use RU:x.y notation

If these conditions do not apply, then AutoUpgrade can derive the target release value. The allowed value is a single major release number. At the time of this release, the only valid value is for Oracle Database 19c (19).

Valid value:

19

Example

sales1.target_version=19

Usage Notes

To preserve data integrity, Oracle recommends that you upgrade the time zone file (DST) 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.

If you explicitly disable the time zone file upgrade in your AutoUpgrade configuration file, then Oracle recommends that you perform this task either as part of your upgrade plan, or at a later point in time.

Options

[yes | no]

The default value is yes for upgrade, and no for patching.

Example

sales1.timezone_upg=no

Usage Notes

The tune_setting parameter enables you to fine-tune upgrade steps or the resources allocated to the processing of the upgrades specified by the container databases or pluggable databases (CDBs or PDBs) specified by the parameter prefix in your AutoUpgrade configuration file. This capability can be useful for some upgrades if you find the default AutoUpgrade values are insufficient for your system requirements, or when you want to enable nondefault AutoUpgrade options.

Syntax

prefix.tune_setting=option[, option, option, ...]

sales3.tune_setting=proactive_fixups=true,query_hint_parallel=8,utlrp_threads_per_pdb=8

Examples

sales3.tune_setting=distributed_upgrade=true

sales3.tune_setting=proactive_fixups=true,query_hint_parallel=8,utlrp_threads_per_pdb=8

Usage Notes

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

Usage Notes

The purpose of this parameter is to create a credentials file to store the user and password credentials for the owner of the Oracle database binaries, and to specify the location of the Administrator PowerShell credential object for those credentials, so that AutoUpgrade can be run using that that credential object during the Oracle Database upgrade. To use this feature, you must have already created the Windows PowerShell credential object, and then specify that credential object in the configuration file using wincredential.

Use case:

You want to specify credentials for the owner of database binaries on a Microsoft Windows server. To specify these credentials, after you enter the wincredential paramter in your configuration file, you run AutoUpgrade in Configuration mode using the load_win_credentials command-line paramter, and provide credentials as prompted. Microsoft Window Powershell then creates the credential object, and stores the generated credential object in the path location you specify with wincredential. For example, in the following file, the location of the credential file is specified with upg1.wincredential=C:\Users\oracle\cred

Example

global.autoupg_log_dir=C:\Users\oracle\autoupg
global.target.version=19.0.0
global.target_home=C:\u01\app\oracle\product\19\dbhome_1

upg1.sid=db12201
upg1.source_home=C:\u01\app\oracle\product\12.2\dbhome_1
upg1.log_dir=C:\Users\Oracle\autoupg
upg1.upgrade_node=localhost
upg1.target_base=C:\u01\app\oracle
upg1.target_version=19.0.0.0
upg1.wincredential=C:\Users\oracle\cred