UPGRADE CATALOG

3.24 UPGRADE CATALOG

Purpose

Use the UPGRADE CATALOG command to upgrade a recovery catalog schema from an older version to the version required by the RMAN client.

Prerequisites

RMAN must be connected to the recovery catalog database, which must be open, as the owner of the recovery catalog. You cannot use the UPGRADE CATALOG command while connected to a virtual private catalog (see CREATE CATALOG command). Only the base catalog can be upgraded.

The recovery catalog must not already be at a version greater than needed by the RMAN executable; otherwise, RMAN issues an error. RMAN displays all error messages generated during the upgrade in the message log.

The Oracle Database 10gR1 version of the recovery catalog schema requires the CREATE TYPE privilege. If you created the recovery catalog owner in a release before 10gR1, and if you granted the RECOVERY_CATALOG_OWNER role to this user when the role did not include the CREATE TYPE privilege, then you must grant CREATE TYPE to this user explicitly before performing the upgrade.

If you are upgrading a recovery catalog to Oracle Database 12c Release 2 (12.2) or higher, then you must run the dbmsrmansys.sql script that manages recovery catalog privileges. Additionally, if virtual private catalogs are used, then you must run the dbmsrmanvpc.sql script that upgrades virtual private catalogs. Starting with Oracle Database 12c Release 1 (12.1.0.2), the recovery catalog database must use Oracle Database Enterprise Edition.

Usage Notes

RMAN prompts you to enter the UPGRADE CATALOG command two consecutive times to confirm the upgrade. To bypass the additional confirmation step, enter the UPGRADE CATALOG command with the NOPROMPT option while running it the first time.

RMAN permits the command to be run if the recovery catalog is already current so that the packages can be re-created if necessary.

If an upgrade to a base recovery catalog requires changes to an existing virtual private catalog, then RMAN makes these changes automatically the next time RMAN connects to that virtual private catalog.

The UPGRADE CATALOG command does not run scripts to perform an upgrade. Instead, RMAN sends various SQL DDL statements to the recovery catalog to update the recovery catalog schema with new tables, views, columns, and so on.

Starting from Oracle Database 23ai, you can achieve better control over catalog schema connections while performing a recovery catalog upgrade. You can use options to:

Run the UPGRADE CATALOG command after a given time delay, so that blocking connections can complete
Run the UPGRADE CATALOG command to start immediately by forcibly terminating all blocking connections
Run the UPGRADE CATALOG command to start after a given time delay and after forcibly terminating any blocking connections at the end of the time delay
When the UPGRADE CATALOG command is in execution, you can connect RMAN to the recovery catalog in the maintenance mode. You can then take action on catalog schema connections, particularly if blocking or waiting catalog connections are affecting the progress of the recovery catalog upgrade.

To learn about managing recovery catalog upgrades, see Using the Maintenance Mode for Monitoring Catalog Upgrade in the Backup and Recovery User's Guide.

Syntax

upgradeCatalog::=

Description of the illustration upgradecatalog.eps

Semantics

NOPROMPT: Bypasses the confirmation step while upgrading the catalog.
TABLESPACE tablespace_name NOPROMPT: Bypasses the confirmation step while upgrading the specified tablespace.

Syntax Element	Description
`NOPROMPT`	Bypasses the confirmation step while upgrading the catalog.
`TABLESPACE` tablespace_name `NOPROMPT`	Bypasses the confirmation step while upgrading the specified tablespace.
`WAIT` integer	Specifies a time delay, in seconds, to start the recovery catalog upgrade. Use the `WAIT` option to introduce a specific time delay to start the upgrade. This is particularly useful if you want to allow time for blocking connections to complete before starting the recovery catalog upgrade. Blocking connections are catalog schema connections which started before you issued the `UPGRADE CATALOG` command. If there are blocking connections at the end of the wait time, then the `UPGRADE CATALOG` command exits with an error message.
`TERMINATE CONNECTED USERS`	Use the `UPGRADE CATALOG` command with the `TERMINATE CONNECTED USERS` option to start the recovery catalog upgrade immediately after forcibly terminating blocking connections. Combine the `WAIT` option and the `TERMINATE CONNECTED USERS` option to run `UPGRADE CATALOG` after a given delay and after forcibly terminating all blocking connections at the end of the time delay.

Example

Example 3-86 Upgrading a Recovery Catalog

This example connects RMAN to recovery catalog database catdb and then upgrades it to a more current version:

RMAN> CONNECT CATALOG rco@catdb

recovery catalog database Password: password
connected to recovery catalog database 
PL/SQL package RCO.DBMS_RCVCAT version 11.02.00.04 in RCVCAT database is too old

RMAN> UPGRADE CATALOG;

recovery catalog owner is RCO 
enter UPGRADE CATALOG command again to confirm catalog upgrade 

RMAN> UPGRADE CATALOG;

recovery catalog upgraded to version 12.02.00.00
DBMS_RCVMAN package upgraded to version 12.02.00.00
DBMS_RCVCAT package upgraded to version 12.02.00.00

Example 3-87 Overriding the default behavior of the UPGRADE CATALOG command

In this example, the UPGRADE CATALOG command executes after a given time delay of 600 seconds. RMAN completes the catalog upgrade by terminating a blocking connection at the end of the time delay.

RMAN> CONNECT CATALOG rco@catdb;
UPGRADE CATALOG WAIT 600 TERMINATE CONNECTED USERS; 
UPGRADE CATALOG WAIT 600 TERMINATE CONNECTED USERS;

#RMAN-06008: connected to recovery catalog database

#RMAN-06435: recovery catalog owner is RMAN2
#RMAN-06442: enter UPGRADE CATALOG command again to confirm catalog upgrade

RMAN-07558: Following sessions are connected to catalog schema
RMAN-07559: =============================================
RMAN-07560: Logon_time             SID   Serial User
RMAN-07559: =============================================
RMAN-07561: 2023-08-01 11:17:13     53    34909 RMAN
RMAN-07561: 2023-08-01 11:18:12     54    29938 RMAN3
RMAN-07561: 2023-08-01 11:19:02     51     4252 RMAN
RMAN-07559: =============================================
RMAN-07556: Following sessions are blocking the catalog schema upgrade
RMAN-07559: =============================================
RMAN-07560: Logon_time             SID   Serial User
RMAN-07559: =============================================
RMAN-07561: 2023-08-01 11:17:13     53    34909 RMAN
RMAN-07559: =============================================
RMAN-07556: Following sessions are blocking the catalog schema upgrade
RMAN-07559: =============================================
RMAN-07560: Logon_time             SID   Serial User
RMAN-07559: =============================================
RMAN-07561: 2023-08-01 11:17:13     53    34909 RMAN
RMAN-06958: Executing: alter system kill session '53, 34909'
RMAN-07559: =============================================
#RMAN-06408: recovery catalog upgraded to version 23.01.00.23.02
#RMAN-06452: DBMS_RCVMAN package upgraded to version 23.01.00.23
#RMAN-06452: DBMS_RCVCAT package upgraded to version 23.01.00.23.
#
#Recovery Manager complete.