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 database on which you want to run AutoUpgrade is both up and running, with the correct binaries for the type of processing mode that you want to run.
  • On container databases (CDBs), the pluggable databases (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.
  • You have the AutoUpgrade jar file (autoupgrade.jar) downloaded or available, and you are able to run it using a Java 8 distribution.

As of the January 2019 Release Updates (DBJAN2019RU), AutoUpgrade support is available for Oracle Database 12c Release 2 (12.2) and Oracle Database 18c (18.5) target homes. For both Oracle Database 12c Release 2 (12.2) and Oracle Database 18c (18.5) target homes, you must download the AutoUpgrade kit from My Oracle Support Document 2485457.1.

In Oracle Database 19c (19.3) and later target Oracle homes, the autoupgrade.jar file exists by default. However, before you use AutoUpgrade, Oracle 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

If Java 8 is in your source Oracle home, then 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.

Note:

The hostname for your target database must be registered in the host file for the server (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, then the target database hostname should be returned when you enter the command hostname. For example:

$ hostname
sales3

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 and target 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

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 the earlier release database (source database) 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. If your target Oracle home is not available, then when you modify your configuration file to run fixups on the source database system, you can set the target_home Oracle home value to the same path as the source_home Oracle home.

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 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 of 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. If necessary, it can also perform fixups on the database.

Before you run Deploy, you must have the target version 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.eps follows
Description of the illustration autoupgrade-deploy-flow.eps

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.

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