Starting the Data Guard Command-Line Interface

To start the Data Guard command-line interface (DGMGRL), enter dgmgrl at the command-line prompt on a system where Oracle is installed.

% dgmgrl

The DGMGRL command prompt is displayed:

DGMGRL>

To run DGMGRL, you must have SYSDG or SYSDBA administrative privilege.

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.
DGMGRL Command Format and Parameters
The DGMGRL commands allow you to create and maintain one broker configuration at a time.
DGMGRL Command Usage Notes
The items in this list describe usage notes specific to DGMGRL.
Exiting the Data Guard Command-Line Interface
When you are done working with the DGMGRL interface and want to return to the operating system, enter the EXIT or QUIT command.

Parent topic: Oracle Data Guard Command Reference

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.

Output includes items 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:
- -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.
  
  Note:
  The DGMGRL -logfile option is deprecated as of Oracle Database 12c Release 2 (12.2.0.1). It is supported for backward compatibility only. Instead, the log file should now be specified using the LOGFILE IS clause on the START OBSERVER command.
  See Also:
  - The "START OBSERVER" command
  - Capturing Observer Actions in the Observer Log File
- -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.
- -json
  This option allows DGMGRL to convert command output to JSON format. JSON-formatted output enables easy integration with automation tools and scripting environments. The following example shows the -json option used on the command line:
```
$ dgmgrl -json <connect_auth> "show configuration tracelevel";
{
  "Version" : "26.1.0.24.00",
  "ShowProperty" :
  {
    "Configuration" : "abc",
    "Name" : "TraceLevel",
    "Value" : "USER",
    "Type" : "Configurable"
  }
}
```
  The following example shows the -json option used interactively:
```
$ dgmgrl <connect_auth>
          DGMGRL> set json on;
          DGMGRL> show configuration tracelevel;
          {  
             "Version": "26.1.0.24.00",  
             "ShowProperty":  
              {    
                "Configuration": "abc",    
                "Name": "TraceLevel",    
                "Value": "USER",    
                "Type": "Configurable"  
              }
          }
DGMGRL> set json off;
```
<logon> is:
- username [@connect-identifier]
  
  To connect to the database, enter a username and optionally, a connect-identifier. You will then be prompted for a password. The connect-identifier is a fully specified connect descriptor, a name to be resolved by an Oracle naming method (for example, TNS) including Easy Connect.
  If a fully specified connect descriptor is used, it needs to include quotation marks; otherwise the connections will fail with an invalid option error. The following is an example of connecting using quotation marks:
```
dgmgrl sys@'(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=sales-server)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))'
```
```
Enter password: password
```
  Whether the connect identifier is specified using a fully specified connect descriptor or using the Easy Connect naming method, any of the following syntax is valid (you will be prompted for a password):
  - dgmgrl username@'connect_identifier'
  - dgmgrl username@"connect_identifier"
  - dgmgrl username@"'connect_identifier'"
  WARNING:
  
  Including a password on the command line when invoking DGMGRL is a security risk. This risk can be avoided either by omitting the password when invoking DGMGRL and entering it when prompted, or by using an external authentication method.
- You can connect as '/' when using operating-system authentication (remote database restarts will not work), Secure Sockets Layer (SSL) protocol, or database credentials stored in a wallet.
<command> is a single command.

For example:

dgmgrl sys "show database 'North_Sales'"

Password: password

The following subsections specify the command format that you enter at the DGMGRL> command prompt.

Parent topic: Starting the Data Guard Command-Line Interface

DGMGRL Command Format and Parameters

The DGMGRL commands allow you to create and maintain one broker configuration at a time.

Table 10-1 Summary of DGMGRL Commands

Command	Effect	SQLcl
@ (at sign) Command	Executes a DGMGRL script.
/ (slash) Command	Repeats the last command entered at the DGMGRL command prompt.
ADD CONFIGURATION	Adds a relationship between two Data Guard broker configurations by adding a broker configuration to the current configuration.	YES
ADD DATABASE	Adds a new standby database to the existing broker configuration.	YES
ADD PLUGGABLE DATABASE	This command instantiates a target PDB in the target database.
CONNECT	Connects to the specified database using the specified username.
CONVERT DATABASE	Converts the specified database to either a snapshot standby database or a physical standby database.
CREATE CONFIGURATION	Creates a broker configuration and adds a primary database to that configuration.	YES
CREATE FAR SYNC	Creates a new far sync instance and adds it to the broker 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.	YES
DISABLE DATABASE	Disables broker management of the named standby database.	YES
DISABLE FAR_SYNC	Disables broker management of a far sync instance.	YES
DISABLE FAST_START FAILOVER	Disables fast-start failover.	YES
DISABLE FAST_START FAILOVER CONDITION	Allows a user to remove conditions for which a fast-start failover should be performed.
DISABLE RECOVERY_APPLIANCE	Disables broker management of the named Zero Data Loss Recovery Appliance (Recovery Appliance).	YES
EDIT ALL MEMBERS RESET (Parameter)	Resets the value of the specified parameter for all members in the broker configuration.
EDIT ALL MEMBERS RESET (Property)	Resets the value of the specified property for all members in the broker configuration.
EDIT ALL MEMBERS SET (Parameter)	Changes the value of the specified parameter for all members in the broker configuration.
EDIT ALL MEMBERS SET (Property)	Changes the value of the specified configurable property for all members in the broker configuration.
EDIT CONFIGURATION (Property)	Changes the value of a property for the broker configuration.	YES
EDIT CONFIGURATION (Protection Mode)	Changes the current protection mode setting for the broker configuration.
EDIT CONFIGURATION (RENAME)	Changes the configuration name.
EDIT CONFIGURATION RESET (Property)	Resets the specified configuration property to its default value.
EDIT CONFIGURATION RESET TAG	Removes the tag and its value-pair.
EDIT CONFIGURATION SET TAG	Changes or asssigns a value-par tag for the configuration.
EDIT DATABASE (Property)	Changes the value of a property for the named database.
EDIT DATABASE (Parameter)	Changes the value of a database initialization parameter 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.	YES
EDIT DATABASE RESET (Property)	Resets the specified property for the named database to its default value.
EDIT DATABASE RESET (Parameter)	Resets the specified database initialization parameter for the named database.
EDIT DATABASE RESET TAG	Removes the tag and its value-pair.
EDIT DATABASE SET TAG	Changes or assigns a value-pair tag for the specified database.
EDIT FAR_SYNC	Changes the name, state, or properties of a far sync instance.
EDIT FAR_SYNC RESET (Property)	Resets the specified property for the named far sync instance to its default value.	YES
EDIT FAR_SYNC RESET (Parameter)	Resets the specified database initialization parameter for the named far sync instance
EDIT FAR_SYNC RESET TAG	Removes the tag and its value-pair.
EDIT FAR_SYNC SET TAG	Changes or creates the value-pair assigned to the specified far-sync database.
EDIT MEMBER RESET TAG	Removes the tag and its value-pair.
EDIT MEMBER SET TAG	Changes or creates the value-pair assigned to the specified member database.
EDIT RECOVERY_APPLIANCE (Property)	Changes the value of the property for the named Zero Data Loss Recovery Appliance (Recovery Appliance).
EDIT RECOVERY_APPLIANCE (Rename)	Changes the name used by the broker to refer to the specified Zero Data Loss Recovery Appliance (Recovery Appliance), as recorded in that Recovery Appliance's profile in the broker configuration.
EDIT RECOVERY_APPLIANCE RESET (Property)	Resets the specified property for the named Zero Data Loss Recovery Appliance (Recovery Appliance) to its default value.	YES
ENABLE CONFIGURATION	Enables broker management of the broker configuration and all of its databases.	YES
ENABLE DATABASE	Enables broker management of the specified database.	YES
ENABLE FAR_SYNC	Enables broker management of the specified far sync instance.	YES
ENABLE FAST_START FAILOVER	Enables the broker to automatically failover from the primary database to a target standby database.	YES
ENABLE FAST_START FAILOVER CONDITION	Allows a user to add conditions for which a fast-start failover should be performed.
ENABLE RECOVERY_APPLIANCE	Enables broker management of the specified Zero Data Loss Recovery Appliance (Recovery Appliance).	YES
EXIT	Exits the Data Guard command-line interface.
EXPORT CONFIGURATION	Saves the metadata contained in the broker configuration file to a text file.
FAILOVER	Performs a database or pluggable database failover operation in which the standby database, to which DGMGRL is currently connected, fails over to the role of primary database.	YES
HELP	Displays online help for the Data Guard command-line interface.
HOST or ! (exclamation point)	Executes operating system command(s) directly through the DGMGRL console without leaving DGMGRL.
IMPORT CONFIGURATION	Import the broker configuration metadata that was previously exported using the `EXPORT CONFIGURATION` command.
MIGRATE PLUGGABLE DATABASE	Migrates a PDB from one CDB to another on the same host.
PREPARE DATABASE FOR DATA GUARD	Prepares a primary database for a Data Guard environment.
QUIT	Quits the Data Guard command-line interface.
REINSTATE DATABASE	Reinstates the database after a failover.	YES
REMOVE CONFIGURATION	Removes the broker configuration and ends broker management of its members.	YES
REMOVE DATABASE	Removes the specified standby database from the broker configuration.	YES
REMOVE PLUGGABLE DATABASE	Removes the specified pluggable database from the broker configuration.
REMOVE FAR_SYNC	Removes a far sync instance from an Oracle Data Guard broker configuration.	YES
REMOVE INSTANCE	Removes an instance from the broker configuration.
REMOVE RECOVERY_APPLIANCE	Removes the specified Zero Data Loss Recovery Appliance (Recovery Appliance) from the broker configuration and terminates broker management of the Recovery Appliance.	YES
SET ECHO	Controls whether or not to echo commands that are issued either at the command-line prompt or from a DGMGRL script.
SET FAST_START FAILOVER TARGET	Sets the fast-start failover target to the named standby database.
SET MASTEROBSERVER TO	Lets you manually designate which observer is recognized as the master observer.
SET MASTEROBSERVERHOSTS	Sets the master observer of a broker configuration to the observer on the target host.
SET ObserverConfigFile	Sets the full path and file name of an observer configuration file.
SET TIME	Turns timestamp printing on and off.
SET TRACE_LEVEL	Specifies the amount of tracing done by DGMGRL.
SHOW ALL	Shows the values of DGMGRL CLI properties.
SHOW ALL MEMBERS (Parameter)	Displays the value of the specified initialization parameter for all members in the configuration.
SHOW ALL MEMBERS (Property)	Displays the value of the specified property for all members in the configuration.
SHOW CONFIGURATION	Displays information about the broker configuration.	YES
SHOW CONFIGURATION TAG	Shows the configurations associated with the tag.
SHOW CONFIGURATION WHEN PRIMARY IS	Shows the redo transport configuration that would be in effect if the specified database were the primary database.
SHOW DATABASE	Displays information about the specified database.	YES
SHOW DATABASE TAG	Shows the databases associated with the tag..
SHOW FAR_SYNC	Shows information about a far sync instance.
SHOW FAR_SYNC TAG	Shows the far-sync databases associated with the tag.
SHOW FAST_START FAILOVER	Displays all fast-start failover related information.
SHOW INSTANCE	Displays information about the specified instance.
SHOW MEMBER TAG	Shows the member databases associated with the given tag.
SHOW OBSERVER	Shows information about all registered observers in a Data Guard broker configuration.
SHOW PLUGGABLE DATABASE	Displays information about the specified pluggable database.
SHOW ObserverConfigFile	Shows the value of the `ObserverConfigFile` property.
SHOW OBSERVERS	Shows information about all observers for all broker configurations in a specific configuration group.
SHOW RECOVERY_APPLIANCE	Displays information or property values of the specified Zero Data Loss Recovery Appliance (Recovery Appliance).
SHUTDOWN	Shuts down a currently running Oracle database.
SPOOL	Records the input and output of DGMGRL to a file.
SQL	Allows you to enter SQL statements from the Data Guard command-line interface (DGMGRL).
START OBSERVER	Starts the observer.
START OBSERVER IN BACKGROUND	Starts a fast-start failover observer as a background process on the host where the DGMGRL session is running.
START OBSERVING	Starts a new observer for each broker configuration in the specified group.
STARTUP	Starts an Oracle instance with the same options as SQL*Plus, including mounting and opening a database.
STOP OBSERVER	Stops the observer.
STOP OBSERVING	Stops all local observers running on the host where this DGMGRL session is running, for all broker configurations in a specific group.
SWITCHOVER	Performs a switchover operation in which the current primary database becomes a standby database, and the specified standby database becomes the primary database.	YES
VALIDATE DATABASE	Performs a comprehensive set of database checks prior to a role change.
VALIDATE DATABASE DATAFILE	Performs validation of data files across the primary database and standby databases.
VALIDATE DATABASE SPFILE	Performs a comparison of server parameter file (SPFILE) entries between the primary database and a specified standby database.
VALIDATE DGConnectIdentifier	Enables users to check to see whether a connection string is valid for the DGConnectidentifier property.
VALIDATE FAR_SYNC	Performs a comprehensive set of checks for a far sync instance.
VALIDATE FAST_START FAILOVER	Validates the the fast-start failover configuration settings.
VALIDATE NETWORK CONFIGURATION	Performs network connectivity checks between members of the configuration.
VALIDATE PLUGGABLE DATABASE	Performs a comprehensive set of pluggable database checks prior to a role change.
VALIDATE STATIC CONNECT IDENTIFIER	Validates database static connect identifier(s).

Parent topic: Starting the Data Guard Command-Line Interface

DGMGRL Command Usage Notes

The items in this list describe usage notes specific to DGMGRL.

The DG_BROKER_START dynamic initialization parameter is set to TRUE.
To enable broker operations that require restarting databases that are not configured within Clusterware, Oracle Net Services must be configured with a static service on the host that contains the database. By default, broker assumes a static service with the name <db_unique_name>_DGMGRL.<db_domain>. If the static service name is different, the StaticConnectIdentifier broker property for the database must be updated to the connect identifier that references the configured static service. 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>. This is not required if the database is managed by Oracle Clusterware or Oracle Restart for single instance databases. See Prerequisites for additional information.
DGMGRL will automatically shut down and restart a database instance, if the following are true:
- The instance-name is the SID (this applies to Cloud Control as well as DGMGRL).
- he broker must be able to connect to the database using the same credentials given in the last CONNECT command, even if the last CONNECT command was used to connect to another database.
The connect identifier used while creating the configuration or adding a database, must be resolvable from any of the hosts in the configuration.
You must have SYSDG or SYSDBA privileges to use the Oracle Data Guard command-line interface. If you do not include AS SYSDG or AS SYSDBA on the CONNECT command, DGMGRL first attempts an AS SYSDG connection; if that fails, it then attempts an AS SYSDBA connection. Note that although most commands can be executed with either SYSDG or SYSDBA privileges, some commands that create or significantly modify configuration members can be executed only with SYSDBA privileges.
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.

Command Examples

Example 10-1 Connecting to a Database Instance on a Local System

This example demonstrates how to connect to a database instance on the local system.

% dgmgrl
.
.
.
Welcome to DGMGRL, type "help" for information.

DGMGRL> CONNECT sysdg;
Password: password
Connected to "North_Sales"
Connected as SYSDG.

Example 10-2 Connecting to a Database Instance on a Remote System

This example demonstrates how to connect to a database instance on a remote system.

DGMGRL> CONNECT sysdg@remote-stby;
Password: password
Connected to "remote-stdby"
Connected as SYSDG.

Example 10-3 Connecting Using the AS Option

This example demonstrates how to connect to a database instance using the CONNECT AS option:

DGMGRL> CONNECT sys@remote-stby AS SYSDBA;
Password: password
Connected to "remote-stdby"
Connect as SYSDBA.

Parent topic: Starting the Data Guard Command-Line Interface

Exiting the Data Guard Command-Line Interface

When you are done working with the DGMGRL interface and want to return to the operating system, enter the EXIT or QUIT command.

For example:

DGMGRL> EXIT;

Parent topic: Starting the Data Guard Command-Line Interface