The Data Guard command-line interface (DGMGRL) enables you to manage a Data Guard broker configuration and its databases directly from the command line, or from batch programs or scripts. You can use the Data Guard command-line interface as an alternative to Oracle Enterprise Manager for managing a Data Guard configuration.
This chapter provides reference information for the Data Guard command-line interface.
8.1 Starting the Data Guard Command-Line Interface
To run DGMGRL, you must have SYSDBA privileges.
Start the command-line interface by entering DGMGRL at the command-line prompt on a system where Oracle is installed:
% dgmgrl
DGMGRL for Linux: Version 10.2.0.1.0 - Production Copyright (c) 2000, 2005, Oracle. All rights reserved.
Welcome to DGMGRL, type "help" for information.
DGMGRL>
8.1.1 DGMGRL Optional Parameters
You can supply optional parameters on the command line to indicate how you want the Data Guard command-line interface to display output such as command prompts, banners, and messages.
Additionally, a single command mode is available. In this mode, DGMGRL executes one command and exits upon the completion of the command. The exit code is the result of the command. If the exit code is 0, the command completed successfully.
Otherwise, there was an error.
The command line of DGMGRL appears as follows:
% DGMGRL [<options>] [<logon> [<command>] ]
Specify any of the following keywords when you invoke the DGMGRL command-line interface:
■ <options> can be one of the following choices:
Starting the Data Guard Command-Line Interface
– -echo
Displays command input and output to the default display device. If you do not use this parameter, only the output from the command is displayed.
– -logfile <file-spec> "<dgmgrl-command>"
Specifies a file into which you can capture the actions of the DGMGRL command-line interface. This is particularly useful when DGMGRL is being invoked to serve as the fast-start failover observer. See the "START OBSERVER"
command for more information.
– -silent
Suppresses the display of the DGMGRL (DGMGRL>) command prompt on your default display device. This option is useful if you are directing the command output to a file or to another display tool.
■ <logon> is:
– username/password [@connect-identifier]
The username and password used to connect to the database. The
connect-identifier is a fully specified connect descriptor or a name to be resolved by an Oracle naming method (for example, TNS). The
connect-identifier is optional.
■ <command> is a single command.
For example:
% DGMGRL sys/knl_test7@primary "show database 'North_Sales'"
The following subsections specify the command format that you enter at the DGMGRL>
command prompt.
8.1.2 DGMGRL Command Format and Parameters
The DGMGRL commands allow you to create and maintain one broker configuration at a time. A broker configuration can consist of a primary database and up to 9 standby databases.
After you invoke the command-line interface, you can enter any of the DGMGRL commands listed in Table 8–1. Each command and its associated parameters are described in detail in later sections of this chapter.
Table 8–1 Summary of DGMGRL Commands
Command Effect
ADD DATABASE Adds a new standby database profile to the existing broker configuration.
CONNECT Connects to the specified database using the specified username.
CREATE CONFIGURATION Creates a broker configuration and creates and adds a primary database profile to the configuration.
DISABLE CONFIGURATION Disables broker management of a configuration so that the configuration and all of its databases are no longer managed by the broker.
DISABLE DATABASE Disables broker management of the named standby database.
Starting the Data Guard Command-Line Interface
EDIT CONFIGURATION (Property)
Changes the value of a property for the broker configuration.
EDIT CONFIGURATION (Protection Mode)
Changes the current protection mode setting for the broker configuration.
EDIT DATABASE (Property) Changes the value of a property for the named database.
EDIT DATABASE (Rename) Changes the name used by the broker to refer to the specified database.
EDIT DATABASE (State) Changes the state of the specified database.
EDIT INSTANCE (AUTO PFILE)
Sets the name of the initialization parameter file for the specified instance.
EDIT INSTANCE (Property) Changes the value of a property for the specified instance.
ENABLE CONFIGURATION Enables broker management of the broker configuration and all of its databases.
ENABLE DATABASE Enables broker management of the specified database.
ENABLE FAST_START FAILOVER
Enables the broker to automatically failover from the primary database to a target standby database.
EXIT Exits the Data Guard command-line interface.
FAILOVER Performs a database failover operation in which the standby database, to which DGMGRL is currently connected, fails over to the role of primary database.
HELP Displays online help for the Data Guard command-line interface.
QUIT Quits the Data Guard command-line interface.
REINSTATE DATABASE Reinstates the database after a failover.
REMOVE CONFIGURATION Removes the broker configuration including all of its database profiles from the broker configuration file.
REMOVE DATABASE Removes the specified standby database profile from the broker configuration.
REMOVE INSTANCE Removes knowledge of an instance from an existing database profile in the broker configuration.
SHOW CONFIGURATION Displays information about the broker configuration.
SHOW DATABASE Displays information about the specified database.
SHOW INSTANCE Displays information about the specified instance.
SHUTDOWN Shuts down a currently running Oracle database.
START OBSERVER Starts the observer.
STARTUP Starts an Oracle instance with the same options as SQL*Plus, including mounting and opening a database.
STOP OBSERVER Stops the observer.
SWITCHOVER Performs a switchover operation in which the current primary database becomes a standby database, and the specified standby database becomes the primary database.
Table 8–1 (Cont.) Summary of DGMGRL Commands
Command Effect
Starting the Data Guard Command-Line Interface
8.1.3 DGMGRL Command Usage Notes
To use DGMGRL, the following must be true:
■ The DG_BROKER_START dynamic initialization parameter is set to TRUE.
■ To enable broker operations that require restarting instances without manual intervention, Oracle Net Services must be configured on each of the hosts that contain the primary and standby database instances. Specifically, the listener.ora file must contain static configuration information about the instance. The GLOBAL_DBNAME attribute must be set to db_unique_name_DGMGRL.db_
domain. See Section 2.2 for additional information.
■ The net service name, if used, must be resolvable from any of the hosts in the configuration.
■ You must have SYSDBA privileges to use the Data Guard command-line interface.
Do not include AS SYSDBA on the CONNECT command because SYSDBA is the default setting for this command.
■ The password for SYS needs to be identical on all databases, and all databases should use the remote password file (either SHARED or EXCLUSIVE).
■ If you specify more than one option on the command, you can specify the options in any order.
■ A semicolon is required at the end of each DGMGRL command.
■ Characters specified in a DGMGRL command string value are interpreted as lowercase characters, unless enclosed in double (") or single (') quotation marks.
For example, database and DatAbaSe are equivalent, but "database" and
"DatAbaSe" are not.
■ You can use the backslash (\) to escape a single quotation mark ('), a double quotation mark ("), and the backslash character (\) itself if these characters appear in a character string.
■ Some operations on a broker configuration may require that one or more
databases be shut down and restarted. In most cases, DGMGRL will automatically shut down and restart a given database for you if the following are true:
– The instance-name is the SID (this applies to Enterprise Manager as well as DGMGRL).
– The broker must be able to connect to the database using the username and Note: Existing Oracle9i command-line scripts are supported in
Oracle Database 10g for non-RAC databases. See Appendix A for information about deprecated commands.
See Also: Section 2.1 for information about the listener
prerequisites. Chapter 7 for more information about preparing and starting Oracle Data Guard broker. See the Oracle Database
Administrator's Guide for more information about setting up the network files and listener on the standby database.
See Also: Oracle Data Guard Concepts and Administration for information about passwords
Stopping the Data Guard Command-Line Interface
command was used to connect to another database. Thus, the remote
password file for the database must contain the username and password given in the last CONNECT command.
Command Examples
Example 1
This example demonstrates how to connect to the DGMGRL command-line interface on a local system.
% dgmgrl
DGMGRL for Linux: Version 10.2.0.1.0 - Production Copyright (c) 2000, 2005, Oracle. All rights reserved.
Welcome to DGMGRL, type "help" for information.
DGMGRL> CONNECT sys/change_on_install;
Connected.
Example 2
This example demonstrates how to connect to the Data Guard (DGMGRL) command-line interface on a remote system.
DGMGRL> CONNECT sys/change_on_install@remote-stby;
Connected.
8.2 Stopping the Data Guard Command-Line Interface
When you are done working with the command-line interface and want to return to the operating system, enter the EXIT or QUIT command at the DGMGRL command prompt. For example:
DGMGRL> EXIT;
See Also: Oracle Database Administrator's Guide for more
information about setting up remote password files and the default location of the PFILE and SPFILE initialization parameter files.