AutoUpgrade Command-Line Parameters

About the AutoUpgrade Command-Line Parameters

Review the syntax and prerequisites for using the AutoUpgrade utility (autoupgrade.jar) parameters.

Prerequisites

You must have Java Development Kit (JDK) 8 or later installed in your source environment.

JDK 8 is installed with every release starting with Oracle Database 12c Release 2 (12.2). For any release earlier than 12.2, you must either run AutoUpgrade using the Java release in the target Oracle Database, or you must install JDK 8 on your source database server.
Oracle Database upgrades using the AutoUpgrade utility follow the same upgrade rules that apply to manual Oracle Database upgrades. Confirm that your source Oracle Database release is supported for upgrade.

File Path

The AutoUpgrade utility is a Java JAR file that is located in the new release Oracle Database home.

ORACLE_home/jdk/bin/java

Oracle recommends that you obtain the latest AutoUpgrade JAR file from My Oracle Support. The JAR file and deployment instructions for the JAR file are available from My Oracle Support note 2485457.1

Syntax

AutoUpgrade command syntax is case-sensitive. Enter commands in lowercase.

java -jar autoupgrade.jar
                                   [-version | -help | -create_sample_file create_sample_file
                                   [-settings settings] 
                                   [-config configfile.cfg]
                                               [-clear_recovery_data] 
                                               [-mode mode] 
                                               [-console | -noconsole] 
                                               [-restore_on_fail] 
                                               [-debug]

Each parameter must be prefixed with a minus sign (-). for information about the options that you can use with each parameter, refer to the relevant parameter topic.

Related Topics

Parent topic: AutoUpgrade Command-Line Parameters

Config

The AutoUpgrade parameter config identifies the configuration file that you use to provide information about databases that you want to upgrade.

Property	Description
Parameter type	string
Syntax	`-config configfile -mode mode [-console \| -noconsole] [-restore_on_fail] [-clear_recovery_data] [-debug] [-zip [-sid system_identifier][-d filepath]`
Default value	The option `-console` is enabled by default.

Description

The config...mode clause takes two standard arguments:

The configuration file name, and optionally, path, as represented by config-file
The mode type, using the argument -mode mode, where mode is the processing mode used with the configuration file. The mode argument takes the following options:
- analyze: analyzes the database
- fixups: corrects errors in the source database
- deploy: performs all the operations on the database, from analyze to postupgrade
- upgrade: performs the upgrade on a target Oracle home.

Note:

When you use the -zip clause, you cannot use the -mode clause.

The -config parameter can take the following optional clauses:

-clear_recovery_data: Remove the recovery checkpoint to start fresh the next time AutoUpgrade is started. Use this option to run AutoUpgrade so that it discards any previous generated state information. In particular, this option can be useful during upgrade testing, when you want to test upgrading the same database multiple times, with database restores in between tests.
-console: Enables the AutoUpgrade console, if disabled. The console is enabled by default. The console enables you to submit commands at a terminal to receive details in real time about the jobs that are running, so that you can modify their workflow. For example, from the console, you can abort a job, or restore a given database.
-noconsole: Disables the console. Use the noconsole mode for batch scripting, in which AutoUpgrade commands are run without interaction at the terminal.
-restore_on_fail: Enables the option to restore databases automatically in case of an upgrade failure. This option is only available with Enterprise Edition, and only applies when AutoUpgrade is run in deploy mode. In other modes, this option is ignored.
-debug: Enables debug level messages in both log files and in terminal output.
-zip: Creates an archive (zip) file that contains all AutoUpgrade data and log files. For example, to upload files for a service request, you can use the -zip clause. Without additional clauses, the -zip parameter zips up archive log files for all databases that you specify in the configuration file. The zip file is created in the current path where you run autoupgrade.jar. Note that when you use the-zip option, you cannot use the -mode option. The -zip option takes two optional clauses, which you can specify separately or together:
- -sid system_identifier: Specifies the system identifier (SID) names of the database whose log files you want to have placed in a zip file. You must specify at least one SID as the value of the variable system_identifer. Specify multiple SIDs in a comma-delimited list (sid1,sid2,sid3, …).
- -d filepath: Specifies a destination path where you want the zip file placed. When specified, the archive log files are zipped up into the file path that you specify.
The log files placed in the zip file include the following:
- Configuration file
- Trace directory, including all alert log files specified for each database
- cfgtoollogs directory, including all directories under cfgtoollogs
- System identifier (SID) names: One directory for each SID, containing all job directories and the temp folder for each SID.
The zip file name is in the format AUPG-year-month-day_hour_minute_millisecond.zip, where:
- year is the year that the zip file was created.
- month is the month that the zip file was created
- day is the day that the zip file was created
- hour is the hour that the zip file was created
- minute is the minute that the zip file was created
- millisecond is the millisecond that the zip file was created

Examples

Running AutoUpgrade with a configuration file named myconfig.cfg, with the processing mode deploy:

java -jar autoupgrade.jar -config myconfig.cfg -mode deploy

Running AutoUpgrade with a configuration file named config.cfg located in the path /usr/home/oracle1, with the processing mode analyze:

java -jar autoupgrade.jar -config /usr/home/oracle1/config.cfg -mode analyze

Running AutoUpgrade with a configuration file named config.cfg in analyze mode:

java -jar autoupgrade.jar -config config.cfg -mode analyze -console

Running AutoUpgrade with a configuration file named config.cfg in analyze mode, and disabling the AutoUpgrade console:

java -jar autoupgrade.jar -config config.cfg -mode analyze -noconsole

Running AutoUpgrade with a configuration file named config.cfg in analyze mode, and with the option to enable an automatic restoration of the database in the case that the upgrade fails:

java -jar autoupgrade.jar -config config.cfg -mode deploy –restore_on_fail

Running AutoUpgrade in deploy mode (java -jar autoupgrade.jar -config config.cfg -mode deploy), you encounter an issue during the upgrade. You stop AutoUpgrade, restore the database, and make changes to the database to correct the issue. To start over the AutoUpgrade procedure without encountering the previous AutoUpgrade state file, you run the following command to check your work:

java -jar autoupgrade.jar -config config.cfg -mode analyze -clear_recovery_data

In this example, you run the AutoUpgrade executable autoupgrade.jar with the -zip option. You run AutoUpgrade as the user oracle, where autoupgrade.jar is in the Oracle user home, with a configuration file named myconfig.cfg. You also run AutoUpgrade without setting optional clauses for the -zip option. As a result, a zip file is placed in the Oracle user's home, where the autoupgrade.jar executable is located:

java -jar autoupgrade.jar -config myconfig.cfg -zip
Processing: 230736166 [bytes] in 140 Files
/ 100%
Zipped successfully at /home/oracle/AUPG_200130_1501_900.zip

You run the same AutoUpgrade command, but this time set the optional -d clause of the -zip option, and specify that you want the zip file placed in the path /u03/AUPG-files:

java -jar autoupgrade.jar -config myconfig.cfg -zip -d /u03/AUPG-files/
Processing: 230736166 [bytes] in 140 Files
| 100%
Zipped successfully at /u03/AUPG-files/AUPG_200130_1528_926.zip

You run the AutoUpgrade command on the database, using myconfig.cfg, which includes the SID definitions upg1.sid=sales_01 and upg2.sid=inv_04, but this time set the optional -sid clause of the -zip option, and specify that you want to zip up the files of the SID sales_01:

java -jar autoupgrade.jar -config myconfig.cfg -zip -sid sales_01
Processing: 115368083 [bytes] in 79 Files- 100%
Zipped successfully at /home/oracle/AUPG_200130_1530_843.zip

The zip file contains only the log files and directories associated with sales_01:

cfgtoollogs/
config.cfg
sales_01/
trace/

You run the same command, but this time specify that you want the zip file to contain log files for the SIDs cdb10300, sales_01 and inv_04, and specify that you want the log files placed in the file path /u03/AUPG-files/:

java -jar autoupgrade.jar -config myconfig.cfg -zip -sid cdb18300,sales_01,inv04 -d /u03/AUPG-files/
Processing: 230736166 [bytes] in 140 Files
- 100%
Zipped successfully at /u03/AUPG-files/AUPG_200130_1545_945.zip

The zip file contains the log files and directories associated with both sales_01 and inv_04:

cdb18300/
cfgtoollogs/
config.cfg
sales_01
inv_04
trace/

Parent topic: AutoUpgrade Command-Line Parameters

Config_Values

The AutoUpgrade parameter config_values enables you to provide the same input values about systems as a text configuration file. You can use it conjunction with the config parameter.

Property	Description
Parameter type	String.
Syntax	`-config_values [-config-parameter value] [-config-parameter value] [-config-parameter value] . . .`
Default value	None.

Description

The config_values parameter enables you to provide values about database paths, instances, and target releases through the AutoUpgrade command line that otherwise require you to specify a configuration file. AutoUpgrade then creates a configuration file as the utility runs. Using config_values enables you to run AutoUpgrade without a configuration file.

The config_values options are a comma-separated list that can support multiple database upgrades. Each database configuration is separated by asterisks (*) to identify different databases. Global entries must include the global prefix in the name. For example:

global.autoupg_log_dir=/scratch/upgradelogs

Local entries only need to include the name:

target_home=/scratch/19

Logging directories are resolved in the following manner.

Case: Global autoupg_log_dir is not specified.

If the config_file parameter is not passed to AutoUpgrade, then the local directory is used as the global log directory. If the config_file parameter is not passed to AutoUpgrade, then the global log directory defaults to the Java temporary directory:
- - Unix and Linux systems: /tmp/autoupgrade
  - Microsoft Windows: C:\Users\name\AppData\Local\Temp\autoupgrade
  - A configuration file is created with the name autoupgradeYYYYMMMMMHHMMSS.cfg, where YYYY is year, MMMM is month, HH is hour, MM is minute, and SS is second.
Case: Global autoupg_log_dir is specified.

If the config_file parameter does not pass the directory to AutoUpgrade, then AutoUpgrade creates a configuration file in the AutoUpgrade log directory specified by the parameter. If the config_file parameter does not pass the directory to AutoUpgrade, then the configuration file is created under the global log directory. If you specify a configuration file name that already exists, then AutoUpgrade renames the existing configuration file using the suffix YYYYMMMHHMMMMSS.cfg, where YYYY is year, MMMM is month, HH is hour, MM is minute, and SS is second. For example: on April 29, 2020, at 08:30:04, if configuration file \tmp\autoupgrade.cfg already exists, and you pass the file name -config_file \tmp\autoupgrade.cfg to AutoUpgrade, then the existing file is renamed to \tmp\autoupgrade.cfg20200429083004. AutoUpgrade then creates the new configuration file \tmp\autoupgrade.cfg.

If you use the -config_values parameter, and the user account running the AutoUpgrade command has the following variables set, then AutoUpgrade picks up these variables from the user environment settings:

oracle_home - Sets the Oracle home environment variable for the source Oracle home
oracle_target_home - Sets the target Oracle home.
- Linux and Unix: Equivalent to an export ORACLE_HOME command. For example: export ORACLE_HOME=scratch/oracle/1124
- Microsoft Windows: Equivalent to a SET ORACLE_HOME command. For example: SET ORACLE_HOME=C:\oracle\1124
sid - Sets the Oracle Database system identifier (SID).
- Linux and Unix: Equivalent to an export ORACLE_SID command. For example: export ORACLE_SID=sales
- Microsoft Windows: Equivalent to a SET ORACLE_SID command. For example: SET ORACLE_SID=sales
oracle_target_version - Sets the target release of the new Oracle home. You must set this value either when the target Oracle home does not exist, or the target home is a release earlier than Oracle Database 18c.
- Linux and Unix: Equivalent to an export ORACLE_TARGET_VERSION command. For example: export ORACLE_TARGET_VERSION=19.3
- Microsoft Windows: Equivalent to a SET ORACLE_TARGET_VERSION command. For example: SET ORACLE_TARGET_VERSION=19.3
If you use the config_values parameter in place of a configuration file, and you do not have these environment variables set for the user account running AutoUpgrade, then you must provide at least these four values as arguments using config_values.

Example: Running AutoUpgrade with an existing configuration file

Scenario: Running AutoUpgrade with an existing configuration file, using config_values. The following command syntax creates the global.autoupg_log_dir from the local directory where the myconfig.cfg file is created. As a result of this command, the location for global.autoupg_log_dir is set to /dir:

java –jar autoupgrade.jar –config /dir/myconfig.cfg –config_values
        “source_home=/srcdir, target_home=/trgdir, sid=sales” –mode
        deploy

The configuration file myconfig is created in the path /dir, with the following entries:

global.autoupg_log_dir=/dir
autoupgrade1.source_home=/srcdir
autoupgrade1.target_home=/trgdir
autoupgrade1.sid=sales

Example: Running AutoUpgrade with a required value for –config_values set to a blank value

In analyze, fixup, upgrade, or deploy mode, if you have set user environment values that AutoUpgrade requires to run, and you do not pass these values as an argument for –config_values, but instead provide a blank value argument ("") then AutoUpgrade defaults to using the user environmental variables set on the server.

To understand how this works, suppose you run AutoUpgrade as the user oracle, for which the following environment variables are set:

ORACLE_HOME is set to /u02/app/oracle/1124
ORACLE_TARGET_HOME is set to /scratch/oracle/19
ORACLE_SID is set to sales
ORACLE_TARGET_VERSION is set to 19.3

Now suppose you run the following command at 11:45:15 AM on April 30, 2020:

[Fri May 1 11:45:15] oracle@example:~$ java –jar autoupgrade.jar –config_values "" –mode analyze

Because the log directory was unspecified, AutoUpgrade defaults writing the configuration file for the run to the temporary directory. The configuration file AutoUpgrade creates resides in the path /tmp/autoupgrade as the file/tmp/autoupgrade/autoupgrade20200501114515.cfg, with the following entries:


global.autoupg_log_dir=/tmp/autoupgrade
# Value from environmental variable ORACLE_HOME
autoupgrade1.source_home=/u02/app/oracle/1124
# Value from environmental variable ORACLE_TARGET_HOME
autoupgrade1.target_home=/scratch/oracle/19
# Value from environmental variable ORACLE_SID
autoupgrade1.sid=sales
# Value from environmental variable ORACLE_TARGET_VERSION
autoupgrade1.target_version=19.3

This option enables you to use AutoUpgrade to handle a single database upgrade without requiring you to specify extensive details about the upgrade.

Example: Running AutoUpgrade with –config_values entries for multiple databases

In this scenario, you run AutoUpgrade with –config_values entries for multiple databases, using * to delimit values for each database:

 java –jar autoupgrade.jar –config /tmp/auto.cfg –config_values “global.autoupg_log_dir=/scratch/upglogs, source_home=/scratch/1124, target_home=/scratch/193,sid=sales,*,source_home=/scratch/122,target_home=/scratch/193,sid=employees”

The configuration file is created in the directory /tmp as /tmp/auto.cfg, with the following entries.


global.autoupg_log_dir=/scratch/upglogs
autoupgrade1.source_home=/scratch/1124
autoupgrade1.target_home=/scratch/193
autoupgrade1.sid=sales
autoupgrade2.source_home=/scratch/122
autoupgrade2.target_home=/scratch/193
autoupgrade2.sid=employees

Parent topic: AutoUpgrade Command-Line Parameters

Console

The AutoUpgrade parameter console turns on the AutoUpgrade Console, and provides a set of commands to monitor the progress of AutoUpgrade jobs.

Property	Description
Parameter type	string
Syntax	`autoupgrade.jar -config your-file -mode your-mode -console [exit \| help \| lsj [(-r\|-f-p\|-e)\|-n number \| lsr \| lsa \| tasks \| clear \| resume -job number \| status [-job number\|-long \| restore -job number [force] \| restore all_failed \| logs \| abort -job number \| h[ist][/number]`

Description

To monitor upgrades, use the AutoUpgrade parameter console to run the Console, which monitors the status of upgrade jobs.

The AutoUpgrade console starts by default with the AutoUpgrade command. You can reenable or disable the AutoUpgrade console using the option -console|-noconsole

When you use the -noconsole option, AutoUpgrade runs using only the settings in the configuration file, without requiring console input. Use the noconsole option when you want to create scripts for AutoUpgrade, such as in cases where you want to analyze multiple databases. After the AutoUpgrade jobs are finished, you can review the output of the Analyze mode logs to see what is required to upgrade each of the databases included with your configuration script.

Note:

You can run only one AutoUpgrade instance at a time.

Usage Notes

Each AutoUpgrade console option must be prefixed with a minus sign (-)

Console Option	Description
`exit`	Closes and exits from the console.
`help`	Displays the console command help
`lsj [(-r\|-f-p\|-e)\|-n number`	Lists jobs by status, up to the number of jobs you specify with the numeric value `number`. You can use the following flags: `-f`: (Optional) Filter by finished jobs. `-r`: (Optional) Filter by running jobs. `-e`: (Optional) Filter by jobs with errors. `-p`: (Optional) Filter by jobs in preparation. `-n number: (Required) Number of jobs to display, specified by integer value.`
`lsr`	Displays the restoration queue.
`lsa`	Displays the abort queue.
`tasks`	Displays the tasks that are running.
`clear`	Clears the terminal display.
`resume -job number`	Restarts from a previous job that was running, specified by a numeric value (`number`) for the job.
`status [-job number\|-long`	Lists the status of a particular job, specified by a numeric value (`-job number`. When run with `-long`, AutoUpgrade runs the command in verbose mode.
`restore -job number [force]`	Restores the database in the AutoUpgrade job specified by the integer value `number` to its state before starting the upgrade. When run with the `force` flag, AutoUpgrade restores the database even if the job is not in an abort or error state.
`restore all_failed`	Restores all failed jobs to their previous state before the upgrade started.
`logs`	Displays all log file locations.
`abort -job number`	Aborts the job specified by the numeric value that you provide (`number`).
`h[ist][/number]`	Displays the console command-line history, and takes the option to run a command again, depending on the flat with which you run it: Flags: `/` Runs the last command again. / number Runs the command in the history log specified by the command line number that you specify.

Parent topic: AutoUpgrade Command-Line Parameters

Create_sample_file

The AutoUpgrade parameter create_sample_file generates either a configuration file, or a settings file. You edit these files to create production configuration or settings files for AutoUpgrade.

Property	Description
Parameter type	string
Syntax	`-create_sample_file [settings \| config [config-file-name]]`
Default value	For `create_sample_file config`, if you append a filename to the command, then an example configuration file is created with the name you provide. If you do not provide an output file name, then the example configuration file is created with the name `sample_config.cfg`,

Usage Notes

The create_sample_file parameter is optional. It cannot be used together with other parameters. When you specify this parameter, it requires either the settings or the config clause:

settings: Generates an AutoUpgrade settings file, either with the name sample_autoupg.cfg, or with a name that you specify.

config: Generates an AutoUpgrade configuration file, either with the name sample_config.cfg, or with a name that you specify.

After you generate one of these example files, you can modify the file to control how the AutoUpgrade utility performs upgrades.

config: Generates a template upgrade configuration file of a configuration mode type. AutoUpgrade generates a file named sample_config.cfg, or with a name you provide, in the current folder
settings AutoUpgrade generates a file named sample_autoupg.cfg, or with the name you provide, in the current folder.

For both the config and settings options, the default file name is generated with the extension .cfg. However, AutoUpgrade can read files without an extension, or with an extension that you provide, as long as the file is a valid (plain text) file. The default extension is for convenience in identifying these files as configuration files.

Generating an example configuration file is a standard part of preparing to use AutoUpgrade. After you customize the configuration file parameters in the example configuration file, you can use that file as the production settings and configuration file for your upgrade.

Caution:

The settings file is used to overwrite internal settings of the AutoUpgrade. Generating an example settings file is not required for most use cases. Use carefully.

Examples

Example of running the create_sample_file parameter with the config clause:

[oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file config
Created sample configuration file /home/oracle/sample_config.cfg

Example of running the create_sample_file parameter with the config, clause specifying an output configuration file name:

[oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file config sales01
Created sample configuration file /home/oracle/sales01.cfg

Example of running the create_sample_file parameter with the settings clause:

oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file settings 
Created sample settings file /home/oracle/sample_autoupg.cfg

Example of running the create_sample_file parameter with the settings, clause specifying an output configuration file name:

oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file settings testsetting.test
Created sample settings file /home/oracle/testsetting.test

Parent topic: AutoUpgrade Command-Line Parameters

Noconsole

The AutoUpgrade parameter noconsole turns off the AutoUpgrade Console, so that AutoUpgrade runs using only configuration file information.

Property	Description
Parameter type	string
Syntax	`noconsole`

Description

When you use the -noconsole option, AutoUpgrade runs using only the settings in the configuration file, without requiring console input. Use the noconsole option when you want to create scripts for AutoUpgrade, such as in cases where you want to analyze multiple databases. After the AutoUpgrade jobs are finished, you can review the output of the Analyze mode logs to see what is required to upgrade each of the databases included with your configuration script.

Note:

You can run only one AutoUpgrade instance at a time.

Usage Notes

In this example, AutoUpgrade is run in Analyze mode, using the configuration file in noconsole mode.

java -jar autoupgrade.jar -config autoupgrade.cfg -mode analyze -noconsole

Parent topic: AutoUpgrade Command-Line Parameters

Settings

The AutoUpgrade parameter settings identifies the configuration file that you use to provide custom runtime configuration of the AutoUpgrade utility.

Property	Description
Parameter type	String
Syntax	`-settings my-custom-advanced-settings`
Default value	Not applicable

Description

The -settings clause has the required argument of the name and path to the settings configuration file, which you have modified with custom settings. The -settings clause cannot be used alone, but rather as a configuration input file that modifies the way that AutoUpgrade runs a processing mode.

Usage Notes

This parameter is an advanced parameter. For most upgrade scenarios, you should not need to modify any internal AutoUpgrade parameter settings.

Example

java -jar autoupgrade.jar -settings my_custom_advanced_settings.cfg -config config.cfg -mode deploy

Parent topic: AutoUpgrade Command-Line Parameters

Version

The AutoUpgrade parameter version prints to the terminal screen the current build of the autoupgrade.jar file.

Property	Description
Parameter type	string
Syntax	-version
Default value	Not applicable.

Description

Use this optional parameter to check which version of the autoupgrade.jar utility is on your server.

Usage Notes

Command Example:

java -jar autoupgrade.jar -version

Output example:

[oracle@example ~]$ java -jar autoupgrade.jar -version
build.version 20181129
build.date 2018/11/29 11:33:51

Parent topic: AutoUpgrade Command-Line Parameters