About AutoUpgrade Processing Modes

The four AutoUpgrade processing modes (Analyze, Fixup, Deploy, and Upgrade) characterize the actions that AutoUpgrade performs as it runs.

Preparations for Running AutoUpgrade Processing Modes

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.

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.

About the AutoUpgrade Analyze Processing Mode

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:

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

Oracle Database Release 12.2 (12.2.0.1) or newer Oracle homes have a valid java version by default. Start AutoUpgrade in Analyze 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 analyze
Description of autoupgrade-analyze-flow.eps follows
Description of the illustration autoupgrade-analyze-flow.eps

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.1.0\dbhome_1
#
# Target Oracle Home
#
sales3.target_home=d:\app\oracle\product\12.1.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.

About the AutoUpgrade Fixup Processing Mode

The AutoUpgrade Fixup (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 Fixup 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 Fixup mode prepares the database for upgrade.

Caution:

Oracle recommends that you run AutoUpgrade in Analyze mode separately before running AutoUpgrade in Fixup mode. Fixup mode can make changes to the source database.

As part of upgrade preparation, if the source database requires corrections for conditions that would cause errors during an upgrade, then AutoUpgrade run in Fixup mode performs automated fixes to the source database. Because running AutoUpgrade in Fixup 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 Fixup 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 fixup

If Java 8 is in your source Oracle home, then start AutoUpgrade in Fixup 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 fixup
Description of autoupgrade-fixup-flow.eps follows
Description of the illustration autoupgrade-fixup-flow.eps

As AutoUpgrade runs in Fixup 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.

Caution:

AutoUpgrade in Fixup mode does not create a guaranteed restore point. Before starting AutoUpgrade in Fixup mode, ensure that your database is backed up.

About the AutoUpgrade Deploy Processing Mode

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
Description of autoupgrade-deploy-flow.png follows
Description of the illustration autoupgrade-deploy-flow.png

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

About the AutoUpgrade Upgrade Processing Mode

The AutoUpgrade Upgrade (upgrade) processing mode enables you to upgrade the target Oracle home in cases where you do not have access to the source Oracle home.

You can use the Upgrade mode to divide an upgrade into two parts: First, if you choose, you can run the prefixups mode on the source database running on its Oracle home. Second, you use the Upgrade mode to perform the upgrade of the database on its new home. To use the Upgrade mode, the database must be up and running in the target Oracle home before you run AutoUpgrade in Upgrade mode.

You start AutoUpgrade in Upgrade 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 upgrade
Description of autoupgrade-upgrade-flow.eps follows
Description of the illustration autoupgrade-upgrade-flow.eps

This command runs the upgrade and postupgrade operations on the database. Use this option 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.

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. When you run AutoUpgrade in Upgrade mode, no postupgrade operations are performed.