You must complete preparations before you can run an AutoUpgrade processing mode.

Before you can use an AutoUpgrade processing mode, confirm that you meet the following requirements:

• You have created a user configuration file.

• The source Oracle Database release is up and running in the original Oracle home. In case of a restart of AutoUpgrade, you must start the database in the Oracle home that corresponds to the phase in the upgrade flow.

• The server on which the database is running is registered on the server hosts file (for example, /etc/hosts), or on a domain name server (DNS).

  If you are logged in to the server on which the target database is located, and the database is running either on localhost, or where AutoUpgrade is running, then remove the hostname parameter from the AutoUpgrade config file.

• On container databases (CDBs), if you want to upgrade a subset of pluggable databases (PDBs), then the PDBs on which you want to run the upgrade are open, and they are configured in the user configuration file, using the AutoUpgrade local parameter pdbs. If you do not specify a list of PDBs, then AutoUpgrade upgrades all PDBs on the CDB.
• You have the AutoUpgrade jar file (autoupgrade.jar) downloaded or available, and you are able to run it using a Java 8 distribution.
• If you want to run AutoUpgrade in a batch or script , then you have called AutoUpgrade using the noconsole parameter in the command.

In Oracle Database 19c (19.3) and later target Oracle homes, the autoupgrade.jar file exists by default. However, before you use AutoUpgrade, Oracle strongly recommends that you download the latest version, which is available form My Oracle Support Document 2485457.1.

The AutoUpgrade Analyze (analyze) processing mode checks your database to see if it is ready for upgrade.

When you run AutoUpgrade in Analyze mode, AutoUpgrade only reads data from the database, and does not perform any updates to the database. You can run AutoUpgrade using the Analyze mode during normal business hours. You can run AutoUpgrade in Analyze mode on your source Oracle Database home before you have set up your target release Oracle Database home.

You start AutoUpgrade in Analyze mode using the following syntax, where Java-8-home is the location of your Java 8 distribution, or the environment variable set for the Java 8 home, and path/yourconfig.txt is the path and filename of your configuration file:

Java-8-home/bin/java -jar autoupgrade.jar -config /path/yourconfig.txt -mode analyze

For example, suppose you have copied the most recent AutoUpgrade release to the new release Oracle home under rdbms/admin, and set an environment variable for that home to 21CHOME, and copied the configuration file under the Oracle user home, under the directory /scripts, and called it 21config.cfg, you then enter the following command:

java -jar $21CHOME/rdbms/admin/autoupgrade.jar -config /scratch/scripts/21config.cfg -mode analyze -mode analyze

Oracle Database Release 12.2 (12.2.0.1) or newer Oracle homes have a valid java version by default.

The AutoUpgrade Analyze mode produces two output files, which are given the name of the system identifier (SID) of the database that you check:

• SID.html: View this file using a web browser.

• SID_preupgrade.log: View this file using a text editor.

Each report identifies upgrade errors that would occur if you do not correct them, either by running an automatic fixup script, or by manual correction. If errors occur, then they are reported in the user log file, and also in the status.json file.

The Analyze mode also generates a status directory in the path cfgtoollogs/upgrade/auto/status. This directory contains files that indicate if the analysis was successful or failed. This directory has two JSON files, status.json and progress.json:

• status.json : A high-level status JSON file that contains the final status of the upgrade.
• progress.json: A JSON file that contains the current progress of all upgrades being performed on behalf of the configuration file. If errors occur, then they are reported in the log file of the user running AutoUpgrade, and also in the status.json file.

If your target database Oracle home is not available on the server, then in your configuration file, you must set the source Oracle home parameters to the same path, so that the AutoUpgrade analyze processing mode can run. For example:

#
# Source Home
#
sales3.source_home=d:\app\oracle\product\12.2.0\dbhome_1
#
# Target Oracle Home
#
sales3.target_home=d:\app\oracle\product\21.0.0\dbhome_1

Earlier releases of AutoUpgrade required you to set target_home. In later releases of AutoUpgrade, this restriction has been lifted for both Analyze and Fixups modes.

The AutoUpgrade Fixups (fixups) processing mode analyzes your database, and performs fixups of items that must be corrected before you can perform an upgrade.

When you run AutoUpgrade in Fixups mode, AutoUpgrade performs the checks that it also performs in Analyze mode. After completing these checks, AutoUpgrade then performs all automated fixups that are required to fix before you start an upgrade. When you plan to move your database to a different platform, using the Fixups mode prepares the database for upgrade.

As part of upgrade preparation, if the source database requires corrections for conditions that would cause errors during an upgrade, then AutoUpgrade run in Fixups mode performs automated fixes to the source database. Because running AutoUpgrade in Fixups mode is a step that you perform as you are moving to another system, it does not create a guaranteed restore point. Oracle recommends that you run this mode outside of normal business hours.

You start AutoUpgrade in Fixups mode using the following syntax, where Java-8-home is the location of your Java 8 distribution, or the environment variable set for the Java 8 home:

Java-8-home/bin/java -jar autoupgrade.jar -config yourconfig.txt -mode fixups

If Java 8 is in your source Oracle home, then start AutoUpgrade in Fixups mode using the following syntax, where Oracle_home is the Oracle home directory, or the environment variable set for the Oracle home, and yourconfig.txt is your configuration file:

Oracle_home/jdk8/bin/java -jar autoupgrade.jar -config yourconfig.txt -mode fixups

As AutoUpgrade runs in Fixups mode, it starts out by running the same prechecks that are run in Analyze mode. It then runs automated fixups in the source database in preparation for upgrade, and generates a high-level status file that indicates the success or failure of fixup operations. If errors occur, then they are reported in the log file of the user running AutoUpgrade.

The AutoUpgrade Deploy (deploy) processing mode performs the actual upgrade of the database, and performs any pending fixups.

Before you run Deploy, you must have the target Oracle home already installed, and you must have a backup plan in place, in addition to the backup plan run as part of the AutoUpgrade script.

You start AutoUpgrade in Deploy mode using the following syntax, where Oracle_home is the Oracle home directory, or the environment variable set for the Oracle home, and yourconfig.txt is your configuration file:

Oracle_home/jdk8/bin/java -jar autoupgrade.jar -config yourconfig.txt -mode deploy

When you run AutoUpgrade in Deploy mode, AutoUpgrade runs all upgrade operations on the database, from preupgrade source database analysis to post-upgrade checks. Each operation prepares for the next operation. If errors occur, then the operation is stopped. All errors are logged to relevant log files, and to the console, if enabled. A high level status file is generated for each operation, which shows the success or failure of the operation. If there are fixups that are still pending (for example, if you run AutoUpgrade in Deploy mode without running AutoUpgrade first in Analyze and Fixups mode) then AutoUpgrade can complete fixups during the Deploy mode.

The AutoUpgrade Upgrade (upgrade) processing mode enables you to upgrade either the source or target Oracle home.

You can use the Upgrade mode to divide an upgrade into two parts:

1. (Strongly Recommended) Run the Prefixups mode on the source database running on its Oracle home.

2. (Optional) Move the source database to a new Oracle home on a different system.

3. Perform the upgrade of the database using the Upgrade mode.

   Note:

   When run in the source Oracle home, AutoUpgrade will start processing the upgrade immediately after skipping the PRECHECKS and PREFIXUPS stages. All other stages (except POSTUPGRADE) typically run during a DEPLOY will be run.

To use the Upgrade mode, the database must be up and running in either the source or the target Oracle home before you run AutoUpgrade in Upgrade mode. This option is particularly of value when you have moved your Oracle Database to a different system from the original source system, so that you cannot use the AutoUpgrade Deploy mode.

This procedure runs the upgrade, and postfixups operations on the database in the new Oracle home location.

AutoUpgrade Upgrade Mode in Target Oracle Home

When the database is open in the target Oracle home, the process flow is as follows:

Description of the illustration autoupgrade-upgrade-flow.eps

As AutoUpgrade runs in Upgrade mode, errors are logged to the log file of the user running the AutoUpgrade script. A high level status file is generated for each operation, which shows the success or failure of the operation.

Note:

When you run AutoUpgrade in Upgrade mode, no postupgrade operations are performed, so you must complete those steps separately. For example, the following postupgrade operations are not performed:

• Copy of network files (tnsnames.ora, sqlnet.ora, listener.ora and other listener files, LDAP files, oranfstab
• Removal of the guaranteed restore point (GRP) created during the upgrade
• Final restart of an Oracle Real Application Clusters database