Create and Manage RMAN Stored Scripts

An RMAN stored script is a named sequence of Recovery Manager commands saved in a recovery catalog for later execution. A database administrator can review and test the sequence once, store it under a meaningful name, and then invoke the same commands whenever the operation is required. This approach reduces typing errors and helps a team apply a consistent backup or recovery procedure.

In Oracle AI Database 26ai, the basic workflow is straightforward. Connect RMAN to a registered target database and an open recovery catalog, create a local script with CREATE SCRIPT or a catalog-wide script with CREATE GLOBAL SCRIPT, and execute it from a RUN block with EXECUTE SCRIPT. Use LIST, PRINT, REPLACE, and DELETE SCRIPT to manage the stored definitions.

A stored script makes RMAN commands reusable, but it is not a scheduler. An operating-system scheduler, Oracle Scheduler, enterprise backup product, or another approved orchestration service must start the RMAN job at the required time. The stored script supplies the RMAN procedure that the scheduled job executes.

Requirements for RMAN Stored Scripts

RMAN stores these scripts in a recovery catalog, not in the target database control file. Before creating or using one, confirm that the following requirements are satisfied:

• The recovery catalog database is open and available.
• The target database has been registered in the recovery catalog.
• RMAN is connected to both the target database and the recovery catalog.
• The target connection uses operating-system authentication or an appropriately privileged account, such as an account with the SYSBACKUP administrative privilege.

The following commands illustrate credential-free target authentication and a catalog connection. The catalog connect identifier and owner name are examples and must match the administrator's environment.

RMAN> CONNECT TARGET /;
RMAN> CONNECT CATALOG rco@catdb;

Issue CREATE SCRIPT at the RMAN prompt. It is not a command that belongs inside a RUN block. If a recovery catalog is not in use, an administrator can still place RMAN commands in an operating-system command file and invoke that file with @, but that file is not an RMAN stored script.

Choose Local or Global Script Scope

A stored script can be local or global. The appropriate scope depends on whether the command sequence belongs to one target database or can be applied to multiple databases registered in the same recovery catalog.

A local script and a global script may have the same name. When EXECUTE SCRIPT does not specify a scope, RMAN first searches for a local script associated with the connected target. If no local script has that name, RMAN searches for a global script. A clear naming convention, such as prod_backup_users for a local script and global_full_backup for a global script, makes the intended scope easier to recognize.

A virtual private catalog user can read and run accessible global scripts, but creating or changing a global script requires access to the base recovery catalog. This restriction helps the catalog owner maintain centrally governed definitions.

Create a Local Stored Script

The commands between the braces form the stored-script body. The following example creates backup_users for the currently connected target database. It relies on the target's configured RMAN channels and backup destination instead of embedding a host-specific path.

RMAN> CREATE SCRIPT backup_users
2> COMMENT 'Back up the USERS tablespace'
3> {
4>   BACKUP TABLESPACE users;
5> }

The COMMENT clause documents the purpose of the script. Comments appear when script names are listed, so they can help administrators distinguish similarly named procedures. Because the command omits GLOBAL, the script is local to the target database connected when it was created.

RMAN parses the definition and reports command-syntax errors before it successfully stores the script. Successful creation does not prove that every referenced database object, storage location, media manager, or device will be available when the script runs. In this example, RMAN can recognize the syntax without guaranteeing that the USERS tablespace will be online and accessible during a future execution. Test every stored script under controlled conditions before placing it in a production schedule.

Create a Global Stored Script

Add the GLOBAL keyword when a standard procedure should be available to multiple targets registered in the recovery catalog:

RMAN> CREATE GLOBAL SCRIPT global_full_backup
2> COMMENT 'Back up a registered database and its archived redo logs'
3> {
4>   BACKUP DATABASE PLUS ARCHIVELOG;
5> }

A global script should contain commands that are genuinely portable. Database-specific paths, channel parameters, media settings, and object names can make a global script unsuitable for another target. Prefer persistent RMAN configuration for standard channel and device behavior. Put an ALLOCATE CHANNEL command in a stored script only when that procedure must override the automatic channels configured for the target.

The commands allowed inside a stored script are the commands that are legal inside an RMAN RUN block. Do not place another RUN block inside the stored definition. The command-file operators @ and @@ are also not allowed in a stored-script body. Avoid allocating the same channel in both the stored script and the outer RUN block that executes it.

Create a Stored Script from a File

RMAN can read a script definition from an operating-system file and store the resulting script in the recovery catalog:

RMAN> CREATE SCRIPT full_backup
2> FROM FILE '/u01/rman/full_backup_definition.rman';

The source file must begin with a left brace, end with a right brace, and contain commands that are valid in a RUN block. The CREATE SCRIPT ... FROM FILE operation copies the definition into the recovery catalog. Editing the source file later does not automatically change the catalog copy.

This feature is different from directly executing a command file with @filename. A stored script is a catalog object with local or global scope. A command file remains an operating-system file whose distribution, access control, versioning, and availability must be managed outside the recovery catalog.

Execute a Stored Script

Use EXECUTE SCRIPT inside a RUN block to invoke the stored commands. The following statement runs the local backup_users script for the connected target:

RMAN> RUN
2> {
3>   EXECUTE SCRIPT backup_users;
4> }

If no local backup_users script exists, RMAN searches for a global script with the same name. When the global definition must be selected explicitly, include GLOBAL:

RMAN> RUN
2> {
3>   EXECUTE GLOBAL SCRIPT global_full_backup;
4> }

The commands from the stored script become part of the active RUN block. If an RMAN command in the stored script fails, the later commands in that block do not continue as though the failure had not occurred. Scheduling systems should therefore capture RMAN output, check the process status, and alert the responsible administrator when a job fails.

List and Print Stored Scripts

Before running or changing a script, identify the available definitions and inspect the stored command text. RMAN provides several forms of LIST ... SCRIPT NAMES:

RMAN> LIST SCRIPT NAMES;
RMAN> LIST GLOBAL SCRIPT NAMES;
RMAN> LIST ALL SCRIPT NAMES;

LIST SCRIPT NAMES shows scripts that can be executed for the connected target. The GLOBAL form lists global names, while ALL lists local and global names in the connected recovery catalog. Descriptive comments supplied during creation or replacement make this output more useful.

Use PRINT SCRIPT to display the stored definition:

RMAN> PRINT SCRIPT backup_users;

Use explicit global syntax when you intend to print the catalog-wide definition:

RMAN> PRINT GLOBAL SCRIPT global_full_backup;

RMAN can also write the displayed definition to an operating-system file. This is useful for review, source-control comparison, or migration to a different catalog:

RMAN> PRINT SCRIPT backup_users
2> TO FILE '/u01/rman/backup_users.rman';

Replace a Stored Script

Use REPLACE SCRIPT to change a local definition. The following replacement validates the tablespace before creating the backup:

RMAN> REPLACE SCRIPT backup_users
2> COMMENT 'Validate and back up the USERS tablespace'
3> {
4>   BACKUP VALIDATE TABLESPACE users;
5>   BACKUP TABLESPACE users;
6> }

If the local script does not exist, REPLACE SCRIPT creates it. This behavior requires care when a global script already has the same name. Omitting GLOBAL does not replace that global definition; it creates or replaces a local script for the connected target. To modify the global definition, use REPLACE GLOBAL SCRIPT explicitly:

RMAN> REPLACE GLOBAL SCRIPT global_full_backup
2> COMMENT 'Back up a registered database and its archived redo logs'
3> {
4>   BACKUP AS BACKUPSET DATABASE PLUS ARCHIVELOG;
5> }

Review the new text with PRINT SCRIPT, test it against the intended target, and preserve an approved copy before replacing an operational script. A successful replacement confirms that the command definition was accepted, not that a future backup will complete under every runtime condition.

Delete a Stored Script

Use DELETE SCRIPT to remove a local script from the recovery catalog:

RMAN> DELETE SCRIPT backup_users;

If no local script of that name exists, RMAN can resolve the name to a global script. To make the intended scope unambiguous, specify GLOBAL when deleting a global definition:

RMAN> DELETE GLOBAL SCRIPT global_full_backup;

Deleting a stored script removes its catalog definition. It does not delete backup pieces created by earlier executions. Before deleting or replacing a shared script, determine which scheduled jobs and registered databases depend on it.

Use Substitution Variables for Controlled Variation

A stored script can accept values through substitution variables such as &1, &2, and &3. This allows a tested procedure to vary selected inputs without duplicating the entire script. The following example accepts a data file number, a tag prefix, and part of the backup filename:

RMAN> CREATE SCRIPT backup_df
2> {
3>   BACKUP DATAFILE &1
4>     TAG &2.1
5>     FORMAT '/u02/backup/&3_%U';
6> }

When the script is created interactively, RMAN requests initial values so that it can parse the completed command. At execution time, supply the actual values with the USING clause:

RMAN> RUN
2> {
3>   EXECUTE SCRIPT backup_df USING 1 df1_backup df1;
4> }

Here, &1 becomes 1, &2 becomes df1_backup, and &3 becomes df1. In the expression &2.1, the period terminates the variable reference, allowing the value to be followed immediately by the digit 1. Validate all supplied values because substitution is textual and can change the meaning of the resulting RMAN command.

Operational Practices for Stored Scripts

Stored scripts reduce manual variation only when their lifecycle is controlled. Apply the same discipline used for other production automation:

• Use descriptive names and comments that identify purpose and scope.
• Prefer configured channels and destinations over unnecessary host-specific values.
• Print and review a script before execution, especially after replacement.
• Test backup scripts and verify that the resulting backups can support the required restore and recovery objectives.
• Capture RMAN output and job status through the scheduling or monitoring platform.
• Control who can create, replace, and delete local or global catalog definitions.
• Document scheduled jobs that depend on each stored script before changing its name or contents.

RMAN stored scripts provide a catalog-managed way to reuse backup and recovery procedures across one target or an entire registered database fleet. Their value comes from combining consistent command definitions with testing, access control, monitoring, and an appropriate scheduling system. In the next lesson, you will examine the RUN command in more detail and see how it controls the execution of stored RMAN procedures.