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.
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.
With non-CDB to PDB conversion and upgrade, AutoUpgrade can automatically complete both upgrade and conversion when these conditions are met:
• The target release CDB must exist.
• The target release should be patched to the latest release update (RU) or release update revision (RUR).
• In the AutoUpgrade configuration file, where the target CDB system identifier is target_cdb, you must set the local parameter target_cdb using the following syntax:
target_cdb=target_cdb.
• The target_cdb value is the Oracle SID of the CDB into which you are plugging the non-CDB.
File Path
The AutoUpgrade utility is a Java JAR file that is located in the new release Oracle Database home.
Oracle_home/rdbms/admin/autoupgrade.jar
Oracle strongly 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.
Example 3-2 Rerunning AutoUpgrade After Fixing an Issue Using clear_recovery_data
You run AutoUpgrade in deploy mode
java -jar autoupgrade.jar -config config.cfg -mode deploy
Chapter 3 AutoUpgrade Command-Line Parameters
However, 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
The analyze results are good, so you then run the deploy option again:
java -jar autoupgrade.jar -config config.cfg -mode deploy
autoupgrade.jar -config-clear_recovery_data-clear_recovery_datajobidjobidjobid
Related Topics
• My Oracle Support note 2485457.1
• Oracle Database Releases That Support Direct Upgrade
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.
Chapter 3 AutoUpgrade Command-Line Parameters
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
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
Chapter 3 AutoUpgrade Command-Line Parameters
inv_04 trace/
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 that is associated with a given configuration file.
Usage Notes
Each AutoUpgrade console option must be prefixed with a minus sign (-)
Console Option Description
exit Closes and exits from the console. If there are jobs
running, then they are stopped.
help Displays the console command help.
Console Option Description
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 displays full details about the job as it is being run.
restore [-job (0-9)|-all_failed]
Restores the database in the AutoUpgrade job specified by the integer value number to its state before starting the upgrade.
When run with the all_failed option, 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.