1. Database Upgrade Guide
  2. Using AutoUpgrade for Oracle Database Upgrades
  3. AutoUpgrade Command-Line Parameters

AutoUpgrade Command-Line Parameters

Review the AutoUpgrade parameters and select the parameters and options for your Oracle Database upgrade use case.

Use the parameters with the command java -jar autoupgrade.jar.

  • About the AutoUpgrade Command-Line Parameters
    Review the syntax and prerequisites for using the AutoUpgrade utility (autoupgrade.jar) parameters.
  • Config
    The AutoUpgrade parameter config identifies the configuration file that you use to provide information about databases that you want to upgrade.
  • Console
    The AutoUpgrade parameter console turns on the AutoUpgrade Console, and provides a set of commands to monitor the progress of AutoUpgrade jobs.
  • 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.
  • Noconsole
    The AutoUpgrade parameter noconsole turns off the AutoUpgrade Console, so that AutoUpgrade runs using only configuration file information.
  • Settings
    The AutoUpgrade parameter settings identifies the configuration file that you use to provide custom runtime configuration of the AutoUpgrade utility.
  • Version
    The AutoUpgrade parameter version prints to the terminal screen the current build of the autoupgrade.jar file.

Parent topic: Using AutoUpgrade for Oracle Database Upgrades

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] [-debug]
Default value The option -console is enabled by default.

Description

The config...mode clause takes two required 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.

The -config clause can take the following optional clauses:

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

Examples

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

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

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

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

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

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

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

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

Running AutoUpgrade with a configuration file named config.txt 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.txt -mode deploy –restore_on_fail

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 ]

Default value

None

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.

config: Generates an AutoUpgrade configuration file

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

  • settings AutoUpgrade generates a file named sample_autoupg.cfg in the current folder.

  • config: Generates a template upgrade configuration file of a configuration mode type. AutoUpgrade generates a file named sample_config.cfg in the current folder

For both the settings and config 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

Example of running the create_sample_file parameter with the settings clause: 

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

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