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.
• 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. For example:

  target_cdb=cdb1

• 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 [options]

Multiple options can be concatenated.

Run Type One (Basic) Parameters for AutoUpgrade

Run type one (Basic) parameters and options for AutoUpgrade provide a starting point for preparing for upgrades.

Run Type Two (Core) Parameters for AutoUpgrade

Run type two (Core) parameters and options for AutoUpgrade provide essential upgrade functionality for most upgrade scenarios.

Run Type Three (Additional) Parameters for AutoUpgrade

Run type three (Additional) parameters and options for AutoUpgrade are useful for particular upgrade scenarios, such as restarting from a failed point in an upgrade, or running particular fixups.

Description

The AutoUpgrade debug parameter turns on debugging messages, which can assist you with correcting AutoUpgrade command syntax.

Usage Notes

Use the debug parameter in concert with any other AutoUpgrade parameter.

Description

The AutoUpgrade clear_recovery_data parameter removes the recovery information, which causes AutoUpgrade to start from the beginning on specified databases, or on all databases.

Usage Notes

Use after manually restoring a database and attempting a new upgrade. If no list of jobs is provided, then by default, all job metadata is removed. Removing the metadata does not remove log files, or reset the job identifier (jobid) counter. Only the AutoUpgrade files used to keep track of the progress of each job are removed.

Examples

The following example shows how to use the clear_recovery_data option after you encounter an issue, fix it, and then run AutoUpgrade again.

You start AutoUpgrade in deploy mode

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

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 and clear out the current job state information, specify the job number that is associated with the previously run job. If you specify the job number, then AutoUpgrade only removes the state information for that specific job. The rest of the jobs will remain untouched.

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

The analyze results are good, so you then run the deploy option again:

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

When you run autoupgrade.jar -config with the -clear_recovery_data parameter, AutoUpgrade only drops state files. It ignores any previously generated log files, so you can retain log files for further reference. Running AutoUpgrade with the -clear_recovery_data parameter also preserves the latest jobid information, so that the jobid AutoUpgrade creates for the next job is the next ID in sequence. By maintaining the jobid state, AutoUpgrade helps you to avoid mixing log output from earlier AutoUpgrade jobs in the same log file.

The following are additional examples of how you can run the clear_recovery_data parameter.

java -jar autoupgrade.jar -config config.cfg -clear_recovery_data
java -jar autoupgrade.jar -config config.cfg -clear_recovery_data -jobs 111,222

-config configfile

Description

The config parameter specifies a configuration file name. It takes two arguments:

• The configuration file name

• (Optional) The path to the configuration file, as represented by config-file

Examples

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

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

-config_values [config-parameter1=value*,config-parameter2=value,...]
     

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-delimited 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=/u01/app/oracle/cfgtoollogs/upgradelogs/

Local entries only need to include the name:

target_home=/u01/app/oracle/product/21.0.0.0/dbhome_1

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 autoupgradeYYYYMMMHHMMSS.cfg, where YYYY is year, MMM 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, MMM 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 operating system environment variables set, then AutoUpgrade picks up the path defined for these variables:

• ORACLE_HOME - The Oracle home path for the source Oracle home
• ORACLE_TARGET_HOME - The target Oracle home path.
  • Linux and Unix: Equivalent to an export ORACLE_TARGET_HOME command. For example: export ORACLE_TARGET_HOME=/u01/app/oracle/product/21.0.0/
  • Microsoft Windows: Equivalent to a SET ORACLE_TARGET_HOME command. For example: SET ORACLE_TARGET_HOME=C:\oracle\21
• ORACLE_SID - The Oracle Database system identifier (SID).
  • Linux and Unix: Set with the operating system shell command export ORACLE_SID. For example: export ORACLE_SID=sales
  • Microsoft Windows: Set with the operating system shell command SET ORACLE_SID command. For example: SET ORACLE_SID=sales
• ORACLE_TARGET_VERSION - The target release of the new Oracle home. You must set this operating system environment variable either when the target Oracle home does not exist, or the target home is a release earlier than Oracle Database 18c.

  • Linux and Unix: Set with export ORACLE_TARGET_VERSION. For example, for Oracle Database 19c:

    export ORACLE_TARGET_VERSION=19.1

    For Oracle Database 21c:

    export ORACLE_TARGET_VERSION=21.1

  • Microsoft Windows: Set with SET ORACLE_TARGET_VERSION.

    For example, for Oracle Database 19c:

    SET ORACLE_TARGET_VERSION=19.1

    For example, for Oracle Database 21c:

    SET ORACLE_TARGET_VERSION=21.1

  If you use the config_values parameter in place of a configuration file, and you do not have these operating system 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 Without Specifying a Value for –config_values

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, 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, where the target version is Oracle Database 21c:

• ORACLE_HOME is set to /u01/app/oracle/product/12.2.0.1/dbhome_1
• ORACLE_TARGET_HOME is set to /u01/app/oracle/product/21.0.0.0/dbhome_1
• ORACLE_SID is set to sales
• ORACLE_TARGET_VERSION is set to 21.1

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

[Wed Sep 30 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/122
# Value from environmental variable ORACLE_TARGET_HOME
autoupgrade1.target_home=/scratch/oracle/21
# Value from environmental variable ORACLE_SID
autoupgrade1.sid=sales
# Value from environmental variable ORACLE_TARGET_VERSION
autoupgrade1.target_version=21.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, with a target release of Oracle Database 21c:

 java –jar autoupgrade.jar –config /tmp/auto.cfg –config_values "global.autoupg_log_dir=/scratch/upglogs,source_home=/scratch/122,target_home=/scratch/21,sid=sales,*,source_home=/scratch/18,target_home=/scratch/21,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/122
autoupgrade1.target_home=/scratch/21
autoupgrade1.sid=sales
autoupgrade2.source_home=/scratch/18
autoupgrade2.target_home=/scratch/21
autoupgrade2.sid=employees

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.

Usage Notes

When you start the console, you can use options within the console.

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.

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

Examples

When entered without a specification, Autoupgrade produces descriptions of all of the error codes:

$ java -jar autoupgrade.jar  -error_code
ERROR1000.ERROR  = UPG-1000
ERROR1000.CAUSE  = It was not possible to create the data file where the jobsTable is being written or there was a problem during the writing, it might be thrown due to a permission error or a busy resource scenario

ERROR1001.ERROR  = UPG-1001
ERROR1001.CAUSE  = There was a problem reading the state file perhaps there was corruption writing the file and in the next write it might be fixed

ERROR1002.ERROR  = UPG-1002
ERROR1002.CAUSE  = Error deserializing the object for rerun, review log for any errors
.
.
.

When entered with a specific error code, AutoUpgrade provides output for the error that you specify. For example:

java -jar autoupgrade.jar -error_code UPG-3010 

This command produces the following output:

ERROR3010.ERROR  = UPG-3010
ERROR3010.CAUSE  = Error running approot_to_pdb.sql script

Here is another example:

$ java -jar autoupgrade.jar  -error_code UPG-1400

This command produces the following output:

ERROR1400.ERROR  = UPG-1400
ERROR1400.CAUSE  = Database upgrade failed with errors

Examples

java -jar autoupgrade.jar -config config.cfg -mode analyze
java -jar autoupgrade.jar -config config.cfg -mode deploy
java -jar autoupgrade.jar -preupgrade "target_version=21" -mode fixups
 

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 run AutoUpgrade as part of a batch flow, or in scripts, 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.

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

-preupgrade preupgrade_options -mode
      [analyze|fixups|postfixups]
                     

Description

The -preupgrade clause of AutoUpgrade replaces the functions previously preformed by the manual Pre-Upgrade Information Tool (preupgrade.jar) in previous releases. The -mode clause takes one of three values:

• analyze: Check your system for readiness to upgrade.
• fixups: Perform fixups as needed on your source Oracle Database release in preparation for upgrade
• postfixups: Perform fixups on your target Oracle Database release after upgrade is completed.

If no value for -mode is specified, then by default the -preupgrade parameter defaults to analyze mode.

Usage Notes

Use the preupgrade clause only if you want to obtain the same features previously made available with the Pre-Upgrade Information Tool (preupgrade.jar). For most upgrade scenarios, you do not need to use this parameter.

The -preupgrade parameter requires preupgrade_options, which specifies a list of comma-delimited option-value pairs in the following format: option1=value1,option2=value2,…

Arguments

• target_version=release-number: Specifies the target Oracle Database release version, which is the release to which you want to upgrade.

  The value for this argument is required by the analyze and fixups modes. However, the target release can be derived from target_home. Accordingly, for analyze and fixups modes, either target_version or target_home must be specified. The value for target_version must be 12.2, or a later release value.

• target_home=[target-path|env-variable]: Specifies the Oracle Database home location of the target release to which you want to upgrade, which can either be the Oracle home path, or an operating system path variable.

  This argument is mandatory if you select the postfixups mode. If you select the postfixups mode, and you do not specify a target home path, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_HOME on Linux and Unix systems, or %ORACLE_HOME% on Microsoft Windows systems).

• oh=[source-path|env-variable]: Specifies the Oracle Database home location of the source release from which you want to upgrade, which can either be the Oracle home path, or an operating system path variable.

  This argument is mandatory if you select the analyze or fixups mode. If you select either analyze or fixups modes, and you do not specify a source home path, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_HOME on Linux and Unix systems, %ORACLE_HOME% on Microsoft Windows systems).

• sid=system-identifier: Specifies an Oracle system identifier for the source database that you want to upgrade. This argument is mandatory for analyze or fixups modes. If you select either the analyze or the fixups mode, and you do not specify a system identifier, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_SID on Linux and Unix systems, %ORACLE_SID% on Microsoft Windows systems).

• dir=path: Directs the output to a specific directory. If you do not specify an output directory with the dir argument, then the output is directed to a folder called autoupgrade that is placed in the temporary directory on your system. Typically, that directory is in one of the following locations:

  • Linux or Unix: /tmp, or /var/tmp.
  • Microsoft Windows: C:\WINNT\TEMP

• inclusion_list=list: Specifies a list of pluggable databases (PDBs) inside a container database (CDBs) that you want to include for processing. Provide a space-delimited list of PDBs that you want processed, in one of the following two formats, where pdb1, pdb2, and pdb3 are PDBs that you want processed:

  • pdb1 pdb2 pdb3
  • (pdb1 pdb2 pdb3)

  If you do not specify a list of PDBs, then all PDBs in a CDB are processed.

• exclusion_list=list: Specifies a list of pluggable databases (PDBs) inside a container database (CDBs) that you want to exclude for processing. Provide a space-delimited list of PDBs that you want processed, in one of the following two formats, where pdb1, pdb2, and pdb3 are PDBs that you want processed:

  • pdb1 pdb2 pdb3
  • (pdb1 pdb2 pdb3)

  If you do not specify a list of PDBs, then all PDBs in a CDB are processed.

• user=username: Specifies the Oracle Database user name that the AutoUpgrade utility uses to connect to Oracle Database If the user is specified, then AutoUpgrade prompts for the user name password input on the command line. If no user name is specified, then AutoUpgrade uses operating system authentication for the Oracle Database connection.

Modes

• analyze (Default value): Runs Autoupgrade in Analyze mode, with all of the preupgrade checks that apply for the target release argument that you specify. If you do not specify a mode, then AutoUpgrade defaults to analyze.

• fixups: Runs preupgrade fixups (when available) for all issues reported by AutoUpgrade Analyze preupgrade checks on the source database that must be fixed before upgrade. All checks are run.

  Fixup results are reported in the file upgrade.xml. That file is placed in the path log_dir/db_name/jobnumber/prefixups/prefixups.xml, where log_dir is the log directory that you specify using the dir argument, db_name is the name of the source database, and jobnumber is the autoupgrade job number.

• postfixups: Runs postupgrade fixups (when available) for all issues reported by AutoUpgrade Analyze preupgrade checks on the upgraded database that you must fix after the upgrade is completed.

  Postfixup results are reported in the file postfixups.xml. That file is placed in the path log_dir/db_name/jobnumber/postfixups, where log_dir is the log directory that you specify using the dir argument, db_name is the name of the source database, and jobnumber is the autoupgrade job number.

Examples

Running AutoUpgrade with the preupgrade clause using analyze mode, and specifying that the target release is Oracle Database 21c.

java -jar autoupgrade.jar -preupgrade "target_version=21" -mode analyze

Running AutoUpgrade with the preupgrade clause using fixups mode, and specifying that the target release is Oracle Database 21c.

java -jar autoupgrade.jar -preupgrade "target_version=21" -mode fixups

Running AutoUpgrade with the preupgrade clause using postfixups mode, and specifying that the target Oracle home is in the path C:\app\oracle\product\21.0.0\dbhome_1.

java -jar autoupgrade.jar -preupgrade "target_home=C:\app\oracle\product\21.0.0\dbhome_1" -mode postfixups

Running AutoUpgrade with the preupgrade clause without specifying the mode, and specifying that the target release is Oracle Database 21c. In this case, the mode used is the default mode, analyze.

java -jar autoupgrade.jar -preupgrade "target_version=21"

Description

The settings parameter has the required argument of the name and path to the settings configuration file, which you have modified with custom settings. The settings parameter 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

In this example, settings specifies a settings input file called my_custom_advanced_settings.cfg.

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

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.hash 04a58df
build.version 20201127
build.date 2020/11/27 11:40:37
build.max_target_version 20
build.type production-21.1

Description

Use this optional parameter to specify a system-level restoration of the jobs you specify, using a comma-delimited list of job numbers. The databases in the upgrade jobs that you specify are flashed back to the Guarantee Restore Point (GRP). Before you run this command, the GRP must have been created by AutoUpgrade.

Examples

java -jar autoupgrade.jar -config config.cfg -restore -jobs 111
java -jar autoupgrade.jar -config config.cfg -restore -jobs 111,222 -console
java -jar autoupgrade.jar -config config.cfg -restore -jobs 111,222 -noconsole

Description

Use this optional parameter to specify that AutoUpgrade restores any jobs that failed during the upgrade deployment.

Examples

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

-zip [-sid sid] [-d dir]

Description

Use this optional parameter to create a zip file that you can send to Oracle Support that contains the log files for jobs that are the object of your service request. Use the -sid clause to specify a comma-delimited list of system identifiers (SIDs) of databases whose log files you want to send. If no SID value is defined, then AutoUpgrade creates a zip file for all databases specified in the configuration file. Use the -d clause to specify a specific output directory. If no directory is specified, then the current directory from which the command is run is used for the zip file output.

Usage Notes

Examples

java -jar autoupgrade.jar -config yourconfig.cfg -zip
java -jar autoupgrade.jar -config yourconfig.cfg -zip -sid sales1,sales2 -d /scratch/upgrd