Skip Headers
Oracle® Data Guard Broker
10g Release 2 (10.2)

Part Number B14230-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

8 Data Guard Command-Line Interface Reference

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 - ProductionCopyright (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:

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

DISABLE FAST_START FAILOVER


Disables fast-start failover.

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.


Note:

Existing Oracle9i command-line scripts are supported in Oracle Database 10g for non-RAC databases. See Appendix A for information about deprecated commands.

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.

    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.
  • 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).

    See Also:

    Oracle Data Guard Concepts and Administration for information about passwords
  • 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 password given in the last CONNECT command, even if the last CONNECT 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.

      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.

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 - ProductionCopyright (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;


ADD DATABASE

Creates a new standby database profile and adds it to the existing broker configuration. The standby database type (physical or logical) is specified by the MAINTAINED AS clause.

Format

ADD DATABASE database-name AS

CONNECT IDENTIFIER IS connect-identifier

MAINTAINED AS {PHYSICAL | LOGICAL};

Command Parameters

database-name

The name that will be used by the broker to refer to this standby database. It must match (case-insensitive) the value of the corresponding database DB_UNIQUE_NAME initialization parameter.

connect-identifier

A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS).

Usage Notes

Command Example


Example 1   

The following example shows how to add a database named DR_Sales.

DGMGRL> ADD DATABASE DR_Sales AS 
> CONNECT IDENTIFIER IS DR_Sales.foo.com 
> MAINTAINED AS PHYSICAL;
Database "DR_Sales" added

CONNECT

Connects a given username to the specified database.

Format

CONNECT username/password [@connect-identifier];

Command Parameters

username/password

Represents the username and password with which you want to connect to the database.

connect-identifier

Consists of the Oracle Net Services connect identifier of the database to which you want to connect. The exact syntax depends upon the Oracle Net Services communications protocol your Oracle installation uses.

Usage Notes

Command Examples


Example 1   

This example connects to the default database on the local system.

DGMGRL> CONNECT sys/change_on_install;
Connected.

Example 2   

This example connects to a remote database whose connect-identifier is prmy.

DGMGRL> CONNECT sys/change_on_install@prmy;
Connected.

Example 3   

This example connects to a database using CONNECT '/' so that connection credentials are not visible on the command line:

DGMGRL> CONNECT /@prmy;

You must set up Oracle Wallet to use CONNECT '/'. By setting up Oracle Wallet, you can write a script to securely start and run the observer as a background job without specifying database credentials in the script.

See Also:

Oracle Database Advanced Security Administrator's Guide for more information about Oracle Wallet

CREATE CONFIGURATION

Creates a new broker configuration, and creates and adds a primary database profile to the configuration.

Format

CREATE CONFIGURATION configuration-name AS

PRIMARY DATABASE IS database-name

CONNECT IDENTIFIER IS connect-identifier;

Command Parameters

configuration-name

A user-friendly name for the configuration you are creating. Valid names contain any alphanumeric characters. If spaces are included in the name, the name must be enclosed in double or single quotation marks. The name must consist of 30 or fewer bytes.

database-name

The name that will be used by the broker to refer to the primary database. It must match (case-insensitive) the value of the corresponding database DB_UNIQUE_NAME initialization parameter.

connect-identifier

A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS).

Usage Notes

Command Example


Example 1   

The following example creates a new broker configuration named DRSolution with a primary database named North_Sales.

DGMGRL> CREATE CONFIGURATION 'DRSolution' AS
> PRIMARY DATABASE IS 'North_Sales'
> CONNECT IDENTIFIER IS North_Sales.foo.com;
Configuration "DRSolution" created with primary database "North_Sales"

DISABLE CONFIGURATION

Disables broker management of a configuration so that the configuration and all of its databases are no longer managed by the broker.

Format

DISABLE CONFIGURATION;

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example disables management of the broker configuration and all of its databases.

DGMGRL> DISABLE CONFIGURATION;
Disabled.

DISABLE DATABASE

Disables broker management of the named standby database. This means that broker directed state changes will be disallowed for this database, and the broker will not monitor the database for health status or for monitorable property values.

Format

DISABLE DATABASE database-name;

Command Parameter

database-name

Name of the standby database to be disabled.

Usage Notes

Command Example


Example 1   

The following example shows how to disable a database named DR_Sales.

DGMGRL> DISABLE DATABASE 'DR_Sales';
Disabled.

DISABLE FAST_START FAILOVER

Disables fast-start failover and prevents the observer from initiating a failover to the target standby database. See Section 5.5.4, "Disabling Fast-Start Failover" for complete information.

Format

DISABLE FAST_START FAILOVER [ FORCE ];

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example shows how to disable fast-start failover.

DGMGRL> DISABLE FAST_START FAILOVER;
Disabled.

EDIT CONFIGURATION (Property)

Changes the value of a property for the broker configuration.

Format

EDIT CONFIGURATION SET PROPERTY FastStartFailoverThreshold = threshold-seconds;

Command Parameter

property-name

The FastStartFailoverThreshold property

Usage Notes

Command Example


Example 1   

The following example shows how to set the FastStartFailoverThreshold property to 90 seconds.

DGMGRL> EDIT CONFIGURATION SET PROPERTY FastStartFailoverThresdhold=90;

EDIT CONFIGURATION (Protection Mode)

Edits the current protection mode setting for the broker configuration.

Format

EDIT CONFIGURATION SET PROTECTION MODE AS protection-mode;

Command Parameter

protection-mode

The data protection mode in which you want the configuration to run when the configuration is enabled. The possible protection modes are:


MAXPROTECTION
MAXAVAILABILITY
MAXPERFORMANCE

Usage Notes

If broker management of the configuration is disabled when you enter the EDIT CONFIGURATION command, the protection mode of the configuration does not take effect until the next time you enable the configuration with the ENABLE CONFIGURATION command.

Command Example


Example 1   

The following example shows how to upgrade the broker configuration to the MAXPROTECTION protection mode. The broker configuration will have the maximum amount of data protection after these commands complete.

Verify that standby redo log files are configured on the standby database and that the redo transport service is set to SYNC, for example:

DGMGRL> EDIT DATABASE 'DR_Sales' SET PROPERTY 'LogXptMode'='SYNC';
Property "LogXptMode" updated

DGMGRL> EDIT CONFIGURATION SET PROTECTION MODE AS MAXPROTECTION;
Operation requires shutdown of instance "sales1" on database "North_Sales"
Shutting down instance "sales1"...
Database closed.
Database dismounted.
ORACLE instance shut down.
Operation requires startup of instance "sales1" on database "North_Sales"
Starting instance "sales1"...
ORACLE instance started.
Database mounted.

The broker automatically stops and restarts the primary database.


EDIT DATABASE (Property)

Changes the value of a property for the named database.

Format

EDIT DATABASE database-name

SET PROPERTY property-name = value;

Command Parameters

database-name

The name of the database for which you want to change a property value.

property-name

The name of an existing database-specific property. If this is a RAC database, this property change affects all instances of the database.

See Also:

Chapter 4 and Chapter 9 for information about properties.
value

The new value for the property.

Caution:

This command can be used to change the value of a per-instance property if and only if just one instance is known by the broker for the named database. An attempt to use this command to change a per-instance property when the broker knows of multiple instances of the database will be rejected. It is recommended to only use EDIT INSTANCE (property) to change the value of a per-instance property.

Command Examples


Example 1   

Edit a database level property.

DGMGRL> EDIT DATABASE 'North_Sales' SET PROPERTY 'ArchiveLagTarget'=1200;
Property "ArchiveLagTarget" updated

Example 2   

Edit an instance level property of a non-RAC database.

DGMGRL> EDIT DATABASE 'DR_Sales' SET PROPERTY 
> 'StandbyArchiveLocation'='/archfs/arch/';
Property "StandbyArchiveLocation" updated

Example 3   

Edit an instance level property of a RAC database. This will not succeed because it is not clear to which instance the property change should be applied.

DGMGRL> EDIT DATABASE 'North_Sales' SET PROPERTY
> 'StandbyArchiveLocation'='/archfs/arch/';
Error: ORA-16587: ambiguous object specified to Data Guard broker

Failed.

EDIT DATABASE (Rename)

Changes the name used by the broker to refer to the specified database, as recorded in that database's profile in the broker configuration.

Format

EDIT DATABASE database-name

RENAME TO new-database-name;

Command Parameters

database-name

The name of the database that you want to change.

new-database-name

The name of the new database.

Usage Notes

Command Example


Example 1   

The following example shows how to edit and rename a database.

DGMGRL> EDIT DATABASE 'DR_Sales_typo' RENAME TO 'DR_Sales';
Succeeded.

DGMGRL> ENABLE DATABASE 'DR_Sales';
Enabled.

EDIT DATABASE (State)

Changes the state of the specified database.

Format

EDIT DATABASE database-name

SET STATE = state

[WITH APPLY INSTANCE = instance-name];

Command Parameters

database-name

The name of the database for which you want to change the state.

state

The state in which you want the database to be running. The possible states are:


ONLINE
LOG-TRANSPORT-OFF (primary database only)
LOG-APPLY-OFF (standby database only)
READ-ONLY (physical standby database only)
OFFLINE
instance-name

The name of the instance you want to become the apply instance if this is a RAC standby database.

Usage Notes

Command Example

The following examples show how to change the state of a database.


Example 1   

DGMGRL> EDIT DATABASE 'DR_Sales' SET STATE='READ-ONLY';
Succeeded.

Example 2   

DGMGRL> EDIT DATABASE 'North_Sales' SET STATE='OFFLINE';
Operation requires shutdown of instance "sales1" on database "North_Sales"
Shutting down instance "sales1"...
Database closed.
Database dismounted.
ORACLE instance shut down.

EDIT INSTANCE (AUTO PFILE)

Sets the name of the initialization parameter file for the specified instance.

Format

EDIT INSTANCE instance-name

[ON DATABASE database-name]

SET AUTO PFILE [= { initialization-file | OFF } ];

Command Parameters

instance-name

The name of the instance (SID) for which you want to specify its initialization parameter file.

database-name

The name of the database to which the instance-name is associated.

initialization-file

Executes the startup operation for the instance when a subsequent broker operation requires the instance to be started automatically. If SET AUTO PFILE is set to OFF, automatic restart of that instance is disabled. When a subsequent operation needs to start that instance, you must start it manually. If you do not specify SET AUTO PFILE for the instance, the automatic startup operation looks for the initialization parameter file at the default location.

Usage Notes

Command Example


Example 1   

The following example shows how to edit an instance of a database.

DGMGRL> EDIT INSTANCE 'dr_sales1' ON DATABASE 'DR_Sales' 
> SET AUTO PFILE='initsales1.ora';
Instance 'dr_sales1' updated

EDIT INSTANCE (Property)

Changes the value of a property for the specified instance.

Format

EDIT INSTANCE instance-name

[ON DATABASE database-name]

SET PROPERTY property-name = value;

Command Parameters

instance-name

The name of the instance (SID) for which you want to change a per-instance property value.

database-name

The name of the database to which the instance-name is associated.

property-name

The name of the per-instance property for which you want to set a new value.

See Also:

Chapter 4 and Chapter 9 for information about properties.
value

The new value for the property.

Usage Notes

Command Examples


Example 1   

Edit an instance level property.

DGMGRL> EDIT INSTANCE 'sales1' ON DATABASE 'North_Sales' 
> SET PROPERTY 'StandbyArchiveLocation'='/archfs/arch/';
Property "StandbyArchiveLocation" updated.

Example 2   

Edit a database level property. This will not be allowed.

DGMGRL> EDIT INSTANCE 'sales1' ON DATABASE 'North_Sales' 
> SET PROPERTY 'LogXptMode'='SYNC';
Error: ORA-16586: could not edit database property through instance

Failed.

ENABLE CONFIGURATION

Enables the broker to actively manage the broker configuration including all of its databases.

Format

ENABLE CONFIGURATION;

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example enables management of a broker configuration.

DGMGRL> ENABLE CONFIGURATION;
Enabled.

ENABLE DATABASE

Enables broker management of the specified standby database.

Caution:

Do not issue the ENABLE DATABASE command on a standby database that needs to be reinstated. See Section 5.4.3 for more details.

Format

ENABLE DATABASE database-name;

Command Parameter

database-name

The name of the standby database for which you want to enable broker management.

Usage Notes

Command Example


Example 1   

The following example shows how to enable a database named DR_Sales.

DGMGRL> ENABLE DATABASE 'DR_Sales';
Enabled.

ENABLE FAST_START FAILOVER

Enables the broker to fail over to a specifically-chosen, synchronized standby database in the event of loss of the primary database, without requiring you to perform any manual steps to invoke the failover. See Section 5.5.2, "Enabling Fast-Start Failover" for complete information.

Format

ENABLE FAST_START FAILOVER;

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example enables fast-start failover.

DGMGRL> ENABLE FAST_START FAILOVER;
Enabled.

Example 2   

The following example attempts to enable fast-start failover when the configuration protection mode is MAXPERFORMANCE.

DGMGRL> SHOW CONFIGURATION;
 
Configuration
  Name:                The SUPER cluster
  Enabled:             YES
  Protection Mode:     MaxPerformance
  Fast-Start Failover: DISABLED
  Databases:
    dgb1  - Primary database
    dgb12 - Physical standby database
 
Current status for "The SUPER cluster":
SUCCESS
 
DGMGRL> ENABLE FAST_START FAILOVER;
Error: ORA-16651: requirements not met for enabling Fast-Start Failover
 
Failed.

EXIT

Exits (quits) the command-line interface.

Format

EXIT;

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example demonstrates how to exit (quit) the command-line interface.

DGMGRL> EXIT;

FAILOVER

Invokes a failover that transitions the named (target) standby database into the role of a primary database. This type of failover is referred to as manual failover. See Section 5.4, "Manual Failover" for more information.

Note:

Because a failover results in a transition of a standby database to the primary role, it should be performed only in the event of a catastrophic failure of the primary database when there is no possibility of recovering the primary database in a timely manner. Failover may or may not result in data loss depending on the protection mode in effect at the time of the failover and whether the target standby database was synchronized with the primary database.

Use the SWITCHOVER command if you want the current primary database and a standby database to switch roles with no data loss.

Format

FAILOVER TO database-name

[ IMMEDIATE ];

Command Parameters

database-name

The name of the standby database you want to fail over to the primary database role.

Usage Notes

Command Examples


Example 1   

The following example performs a failover in which the standby database, DR_Sales, transitions to the primary role:

DGMGRL> FAILOVER TO "DR_Sales";
Performing failover NOW, please wait...
Operation requires shutdown of instance "dr_sales1" on database "DR_Sales"

Shutting down instance "dr_sales1"...
ORA-01109: database not open
Database dismounted.
ORACLE instance shut down.
Operation requires startup of instance "dr_sales1" on database "DR_Sales"
Starting instance "dr_sales1"...
ORACLE instance started.
Database mounted.
Failover succeeded, new primary is "DR_Sales"


HELP

Displays online help for the Data Guard command-line interface.

Format

HELP [topic];

Command Parameter

topic

The topic for which you want to display help information. If you do not specify a topic, the command lists all of the topics and the format. Valid topics are:


ADD
CONNECT
CREATE
DISABLE
EDIT
ENABLE
EXIT
FAILOVER
HELP
QUIT
REINSTATE
REM
REMOVE
SHOW
SHUTDOWN
START
STARTUP
STOP
SWITCHOVER

Usage Note

Command Examples


Example 1   

The following examples get help on the HELP and CONNECT commands.

DGMGRL> HELP HELP;

Display description and syntax for a given command

Syntax:

  HELP [<command>];

DGMGRL> HELP CONNECT;

Connect to an Oracle instance

Syntax:

  CONNECT <username>/<password>[@<connect identifier>]

Example 2   

The following example gets help on the EDIT commands.

DGMGRL> HELP EDIT

Edit a configuration, database or instance

Syntax:

  EDIT CONFIGURATION SET PROTECTION MODE AS
    {MaxProtection|MaxAvailability|MaxPerformance};
  EDIT CONFIGURATION SET PROPERTY <property name> = <value>;

  EDIT DATABASE <database name> SET PROPERTY <property name> = <value>;

  EDIT DATABASE <database name> RENAME TO <new database name>;

  EDIT DATABASE <database name> SET STATE = <state>
    [WITH APPLY INSTANCE = <instance name>];

  EDIT INSTANCE <instance name> [ON DATABASE <database name>]
    SET AUTO PFILE [ = {<initialization file path>|OFF} ];

  EDIT INSTANCE <instance name> [ON DATABASE <database name>]
    SET PROPERTY <property name> = <value>;

QUIT

Quits (exits) the Data Guard command-line interface.

Format

QUIT;

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following example shows how to quit (exit) the command-line interface.

DGMGRL> QUIT;

REINSTATE DATABASE

Reinstates a former primary database as a new standby database in the broker configuration for the current primary database.

Format

REINSTATE DATABASE database-name;

Command Parameter

database-name

The name of the database that is to be reinstated in the broker configuration.

Usage Notes

Command Examples


Example 1   

The following example reinstates the DR_Sales database as a standby database in the broker configuration.

DGMGRL> REINSTATE DATABASE 'North_Sales';
Reinstating database "North_Sales", please wait...
Operation requires shutdown of instance "sales1" on database "North_Sales"
Shutting down instance "sales1"...
ORA-01109: database not open
 
Database dismounted.
ORACLE instance shut down.
Operation requires startup of instance "sales1" on database "North_Sales"
Starting instance "sales1"...
ORACLE instance started.
Database mounted.
Continuing to reinstate database "North_Sales" ...
Reinstatement of database "North_Sales" succeeded

REMOVE CONFIGURATION

Removes all of the broker configuration information, including all database profiles, from the Data Guard configuration file, and terminates broker management of all of the databases associated with the broker configuration.

Caution:

When you use the REMOVE CONFIGURATION command, all profile information is deleted from the Data Guard configuration file and cannot be recovered.

Format

REMOVE CONFIGURATION [ PRESERVE DESTINATIONS ];

Command Parameters

None.

Usage Notes

Command Example

The following examples show a successful and an unsuccessful REMOVE CONFIGURATION command.


Example 1   Successful REMOVE CONFIGURATION Command

The following command shows how to remove configuration information from the configuration file.

DGMGRL> REMOVE CONFIGURATION;
Removed configuration
DGMGRL> SHOW CONFIGURATION;
Error: ORA-16532: Data Guard broker configuration does not exist
 
Configuration details cannot be determined by DGMGRL

Example 2   Unsuccessful REMOVE CONFIGURATION Command

The following command is unsuccessful because fast-start failover is enabled.

DGMGRL> REMOVE CONFIGURATION;
Error: ORA-16654: Fast-Start Failover was enabled
 
Failed.
DGMGRL> SHOW CONFIGURATION VERBOSE;
 
Configuration
 Name:                DRSolution
 Enabled:             YES
 Protection Mode:     MaxAvailability
 Fast-Start Failover: ENABLED
 Databases:
   North_Sales  - Primary database
   West_Sales   - Logical standby database
                - Fast-Start Failover target
   DR_Sales     - Physical standby database
 
Fast-Start Failover
 Threshold: 45 seconds
 Observer:  stacm29
 
Current status for "DRSolution":
SUCCESS

REMOVE DATABASE

Removes the specified standby database's profile from the broker configuration and terminates broker management of the standby database.

Caution:

When you use the REMOVE DATABASE command, the database's profile information is deleted from the broker configuration file and cannot be recovered.

Format

REMOVE DATABASE database-name [ PRESERVE DESTINATIONS ];

Command Parameter

database-name

The name of the standby database whose profile you want to remove from the broker configuration.

Usage Note

Command Example


Example 1   

The following example shows how to remove a database from the Data Guard configuration.

DGMGRL> SHOW CONFIGURATION;

Configuration
 Name:                DRSolution
 Enabled:             NO
 Protection Mode:     MaxPerformance
 Fast-Start Failover: DISABLED
 Databases:
   North_Sales  - Primary database
   DR_Sales     - Physical standby database
 
Current status for "DRSolution":
SUCCESS

DGMGRL> REMOVE DATABASE 'DR_Sales';
Removed database "DR_Sales" from the configuration

DGMGRL> SHOW CONFIGURATION;
Configuration
 Name:                DRSolution
 Enabled:             NO
 Protection Mode:     MaxPerformance
 Fast-Start Failover: DISABLED
 Databases:
   North_Sales  - Primary database
 
Current status for "DRSolution":
SUCCESS


REMOVE INSTANCE

Removes an instance from an existing database profile in the broker configuration.

Format

REMOVE INSTANCE instance-name

[ON DATABASE database-name];

Command Parameters

instance-name

The name of the instance (SID) that you want to remove from the broker configuration.

database-name

The name of the database to which the instance-name is associated.

Usage Notes

Command Example


Example 1   

The following example shows how to remove an instance of the database.

DGMGRL> REMOVE INSTANCE 'dr_sales3' ON DATABASE 'DR_Sales';
Removed instance "dr_sales3" from the database "DR_Sales"

SHOW CONFIGURATION

Displays a summary and status of the broker configuration. The summary lists all databases included in the broker configuration and other information pertaining to the broker configuration itself, including the fast-start failover status.

Format

SHOW CONFIGURATION [VERBOSE];

Command Parameters

None.

Usage Notes

Command Examples


Example 1   Showing a Summary of the DRSolution Configuration

The following example provides a summary of the DRSolution configuration.

DGMGRL> SHOW CONFIGURATION;
 
Configuration
 Name:                DRSolution
 Enabled:             YES
 Protection Mode:     MaxPerformance
 Fast-Start Failover: DISABLED
 Databases:
   North_Sales  - Primary database
   DR_Sales     - Physical standby database
 
Current status for "DRSolution"
SUCCESS

Example 2   Verifying the Readiness of Fast-Start Failover

The following example verifies the readiness of the fast-start failover configuration:

DGMGRL> SHOW CONFIGURATION VERBOSE;

Configuration
 Name:                DRSolution
 Enabled:             YES
 Protection Mode:     MaxAvailability
 Fast-Start Failover: ENABLED
 Databases:
   North_Sales - Primary database
   DR_Sales    - Physical standby database
               - Fast-Start Failover target
Fast-Start Failover
 Threshold: 45 seconds
 Observer:  observer.foo.com
Current status for "DRSolution":
SUCCESS 

SHOW DATABASE

Displays information or property values of the specified database and its instances.

Format

SHOW DATABASE [VERBOSE] database-name [property-name];

Command Parameters

database-name

The name of the database for which you want to display information.

property-name

The name of the property for which you want to display a value.

See Also:

Chapter 4 and Chapter 9 for information about properties.

Usage Notes

Command Examples


Example 1   

Shows database information in an abbreviated format.

DGMGRL> SHOW DATABASE 'DR_Sales';
Database
  Name:            DR_Sales
  Role:            PHYSICAL STANDBY
  Enabled:         YES
  Intended State:  ONLINE
  Instance(s):
    dr_sales1

Current status for "DR_Sales":
SUCCESS

Example 2   

Shows database information in an extended format.

DGMGRL> SHOW DATABASE VERBOSE 'North_Sales'
Database
 Name:            North_Sales
 Role:            PRIMARY
 Enabled:         YES
 Intended State:  ONLINE
 Instance(s):
   sales1
 Properties:
   InitialConnectIdentifier        = 'North_Sales.foo.com'
   LogXptMode                      = 'ARCH'
   Dependency                      = ''
   DelayMins                       = '0'
   Binding                         = 'OPTIONAL'
   MaxFailure                      = '0'
   MaxConnections                  = '0'
   ReopenSecs                      = '30'
   NetTimeout                      = '180'
   LogShipping                     = 'ON'
   PreferredApplyInstance          = ''
   ApplyInstanceTimeout            = '0'
   ApplyParallel                   = 'AUTO'
   StandbyFileManagement           = 'AUTO'
   ArchiveLagTarget                = '0'
   LogArchiveMaxProcesses          = '5'
   LogArchiveMinSucceedDest        = '1'
   DbFileNameConvert               = 'dbs/s2t, dbs/t'
   LogFileNameConvert              = 'dbs/s2t, dbs/t'
   FastStartFailoverTarget         = ''
   StatusReport                    = '(monitor)'
   InconsistentProperties          = '(monitor)'
   InconsistentLogXptProps         = '(monitor)'
   SendQEntries                    = '(monitor)'
   LogXptStatus                    = '(monitor)'
   RecvQEntries                    = '(monitor)'
   HostName                        = 'north.foo.com'
   SidName                         = 'sales1'
   LocalListenerAddress            = '(ADDRESS=(PROTOCOL=TCP)(HOST=north.foo.com)(PORT=1514))'
   StandbyArchiveLocation          = '/archfs/arch/'
   AlternateLocation               = ''
   LogArchiveTrace                 = '255'
   LogArchiveFormat                = 'r_%d_%t_%s_%r.arc'
   LatestLog                       = '(monitor)'
   TopWaitEvents                   = '(monitor)'
Current status for "North_Sales":
SUCCESS 

SHOW INSTANCE

Displays information or property value of the specified instance.

Format

SHOW INSTANCE [VERBOSE] instance-name [property-name]

[ON DATABASE database-name];

Command Parameters

instance-name

The name of the instance for which you want to display information.

property-name

The name of the property for which you want to display a value.

See Also:

Chapter 4 and Chapter 9 for information about properties.
database-name

The name of the database to which is associated the instance for which you want to show information.

Usage Notes

Command Example


Example 1   

The following example shows information about a specific instance of a database.

DGMGRL> SHOW INSTANCE sales1;

Instance 'sales1' of database 'North_Sales'
  Host Name:       north.foo.com

Current status for "sales1":
SUCCESS

Example 2   

Shows instance information in an extended format.

DGMGRL> SHOW INSTANCE VERBOSE sales1;
 
Instance 'sales1' of database 'North_Sales'
 Host Name:       north.foo.com
 PFILE:
 
 Properties:
   HostName                        = 'north.foo.com'
   SidName                         = 'sales1'
   LocalListenerAddress            = '(ADDRESS=(PROTOCOL=TCP)(HOST=north.foo.com)(PORT=1514))'
   StandbyArchiveLocation          = '/archfs/arch'
   AlternateLocation               = ''
   LogArchiveTrace                 = '255'
   LogArchiveFormat                = 'r_%d_%t_%s_%r.arc'
   LsbyMaxSga                      = '0'
   LsbyMaxServers                  = '0'
   LatestLog                       = '(monitor)'
   TopWaitEvents                   = '(monitor)'
 
Current status for "sales1":
SUCCESS

SHUTDOWN

Shuts down a currently running Oracle instance.

Format

SHUTDOWN [ ABORT | IMMEDIATE | NORMAL ];

Command Parameters

None.

Usage Notes

Command Example


Example 1   

The following command shuts down the primary database in normal mode.

DGMGRL > SHUTDOWN;

Database closed. 
Database dismounted. 
Oracle instance shut down.

START OBSERVER

Starts the fast-start failover observer.

Format

START OBSERVER [ FILE=observer_configuration_filename ];

Command Parameters

filename

Specifies an explicit directory path and file name on the observer computer.

Usage Notes

Command Examples


Example 1   

The following example shows...

DGMGRL> CONNECT sys/password@North_Sales.foo.com;
DGMGRL> START OBSERVER;
Observer started

Example 2   

The following example shows how to start the observer using CONNECT '/' so that connection credentials are not visible on the command line:

DGMGRL> CONNECT /@North_Sales.foo.com;
DGMGRL> START OBSERVER;
Observer started.

You must set up Oracle Wallet to use CONNECT '/'. By setting up Oracle Wallet, you can write a script to securely start and run the observer as a background job without specifying database credentials in the script.

See Also:

Oracle Database Advanced Security Administrator's Guide for more information about Oracle Wallet

STARTUP

Starts an Oracle database instance with any of the following options:

Format

STARTUP

[FORCE]

[RESTRICT]

[PFILE=filename]

[MOUNT] | OPEN [open-options] | NOMOUNT];

Command Parameters

filename

The name of the initialization parameter file to be used when starting the database instance. If you do not specify the PFILE parameter option, then the default server parameter file (specific to your operating system) is used.

open-options

The mode of access in which you want the specified database to start. The possible modes are:


READ ONLY
READ WRITE

Usage Notes

Command Examples


Example 1   

The following examples show two different methods for starting a database instance. Each command starts a database instance using the standard parameter file, mounts the default database in exclusive mode, and opens the database.

DGMGRL> STARTUP;
DGMGRL> STARTUP OPEN;

Example 2   

The following command shuts down the current instance, immediately restarts it without mounting or opening the database, and allows only users with restricted session privileges to connect to it.

DGMGRL > STARTUP FORCE RESTRICT NOMOUNT;

Example 3   

The following command starts an instance using the parameter file testparm without mounting the database.

DGMGRL > STARTUP PFILE=testparm NOMOUNT;

Example 4   

The following example starts and mounts a database instance, but does not open it.

DGMGRL> STARTUP MOUNT;

Note:

If the broker is enabled (DG_BROKER_START=TRUE) and the specified database is a primary database or a logical standby database, the broker will attempt to open the database if the database profile indicates the database should be opened.

STOP OBSERVER

Stops the fast-start failover observer.

Format

STOP OBSERVER;

Command Parameters

None.

Usage Notes

Command Examples


Example 1   

The following example stops the observer.

DGMGRL> STOP OBSERVER;

SWITCHOVER

A switchover operation is a planned transition in which the primary database exchanges roles with one of the standby databases. When you issue the SWITCHOVER command, the current primary database becomes a standby database, and the specified standby database becomes the primary database.

Format

SWITCHOVER TO database-name;

Command Parameter

database-name

The name of the standby database you want to change to the primary database role.

Usage Notes

Command Examples


Example 1   

The following example shows a successful switchover in which the standby database, DR_Sales, transitions into the primary role.

DGMGRL> SWITCHOVER TO DR_Sales;
Performing switchover NOW, please wait...
Operation requires shutdown of instance "sales1" on database "North_Sales"
Shutting down instance "sales1"...
ORA-01109: database not open
 
Database dismounted.
ORACLE instance shut down.
Operation requires shutdown of instance "dr_sales1" on database "DR_Sales"
Shutting down instance "dr_sales1"...
ORA-01109: database not open
 
Database dismounted.
ORACLE instance shut down.
Operation requires startup of instance "sales1" on database "North_Sales"
Starting instance "sales1"...
ORACLE instance started.
Database mounted.
Operation requires startup of instance "dr_sales1" on database "DR_Sales"
Starting instance "dr_sales1"...
ORACLE instance started.
Database mounted.
Switchover succeeded, new primary is "DR_Sales"

Example 2   

If you connect to the database using operating system authentication, you can use any username and password to connect. However, DGMGRL may not be able to shut down and start up the primary and standby database automatically because it cannot remotely authenticate itself.

The following example shows a switchover that succeeded but returns an error because DGMGRL cannot shut down and start up the primary and standby databases.

DGMGRL> CONNECT /
Connected
 
DGMGRL> SWITCHOVER TO "DR_Sales";
Performing switchover NOW, please wait...
Operation requires shutdown of instance "sales1" on database "North_Sales"
Shutting down instance "sales1"...
ORA-01017: invalid username/password; logon denied
 
You are no longer connected to ORACLE
Please connect again.
Unable to shut down instance "sales1"
You must shut down instance "sales1" manually
Operation requires shutdown of instance "dr_sales1" on database "DR_Sales"
You must shut down instance "dr_sales1" manually.
Operation requires startup of instance "sales1" on database "North_Sales"
You must start instance "sales1" manually.
Operation requires startup of instance "dr_sales1" on database "DR_Sales"
You must start instance "dr_sales1" manually.
Switchover succeeded, new primary is "DR_Sales"

Note:

For DGMGRL to restart instances automatically, you must connect to the database as SYSDBA using the username and password you specified in the remote password file before you begin the switchover. The username and password must be the same on the primary and standby databases.

You must manually issue the SHUTDOWN and STARTUP commands to restart the new primary and standby database instances in this configuration.