7
Data Guard Command-Line Interface Reference

The Data Guard command-line interface allows you to manage a Data Guard configuration and its site and database resource objects directly from the command line, or from batch programs or scripts. You can use the Data Guard command-line interface as an alternative to the Oracle9i Data Guard Manager graphical user interface for managing a Data Guard configuration.

This chapter provides reference information for the Data Guard command-line interface.

7.1 Starting the Data Guard Command-Line Interface

To run the Data Guard command-line interface, you must have SYSDBA privileges.

Start the command-line interface by entering DGMGRL at the command line prompt on a system where Oracle9i Data Guard is installed:

% DGMGRL [options]
DGMGRL for Solaris:  Version 9.2.0.0.0 - Production.
(c) Copyright 2002 Oracle Corporation. All rights reserved.
Welcome to DGMGRL, type "help" for information.
DGMGRL>

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

Specify none, one, or all of the following keywords when you invoke the DGMGRL command-line interface:

-echo

Echoes command input and output to the default display device. If you do not use this parameter, only the output from the command is displayed.
-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.

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

7.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 site and from 1 to 9 standby sites.

After you invoke the command-line interface, you can enter any of the DGMGRL commands listed in Table 7-1. Each command and its associated parameters are described in detail in later sections of this chapter.

Table 7-1 Summary of DGMGRL Commands

Command	Effect
ALTER CONFIGURATION (protection mode)	Alters the protection mode of the overall Data Guard configuration.
ALTER CONFIGURATION (state)	Alters a broker configuration state from online to offline, or from offline to online.
ALTER RESOURCE (property)	Allows you to change the value of a property for the specified database resource object.
ALTER RESOURCE (state)	Allows you to change the state of the specified database resource object.
ALTER SITE (state)	Allows you to change the state of a site object from online to offline, or from offline to online.
ALTER SITE (AUTO PFILE)	Allows you to specify the initialization parameter file used to automatically restart the database of the site as needed by the client. The information you specify with this command is session specific; that is, it resets to the default initialization parameter file when you connect to a database using the `CONNECT` command.
CONNECT	Connects a given username to the specified database.
CREATE CONFIGURATION	Creates a broker configuration, a primary site object, and a database resource object on the primary site.
CREATE SITE	Creates a new standby site object and a database resource object, and adds them to the broker configuration.
DISABLE CONFIGURATION	Disables broker management of a configuration so that the configuration and all of its site objects and database resource objects are no longer managed by the broker.
DISABLE RESOURCE	Disables broker management of a database resource object in the broker configuration.
DISABLE SITE	Disables broker management of the specified standby site object in the broker configuration so that the standby site object and the database resource objects on the standby site are no longer managed by the broker.
ENABLE CONFIGURATION	Enables broker management of the broker configuration.
ENABLE RESOURCE	Enables broker management of a database resource object in the broker configuration.
ENABLE SITE	Enables broker management of a standby site object in the broker configuration.
EXIT	Exits the Data Guard command-line interface.
FAILOVER	Performs a database failover operation in which the standby site to which the CLI is currently connected fails over into the role of primary database. You issue the `FAILOVER` command as a result of an unplanned transition.
HELP	Displays online help for the Data Guard command-line interface.
QUIT	Quits the Data Guard command-line interface.
REMOVE CONFIGURATION	Removes the broker configuration including all of its site objects and database resource objects.
REMOVE SITE	Removes a standby site object from the broker configuration including the database resource object running on the standby site.
SHOW CONFIGURATION	Displays a information about the broker configuration.
SHOW DEPENDENCY TREE	Displays the dependency tree and default online states for the broker configuration.
SHOW LOG	Shows the Data Guard configuration log or the Oracle database alert log.
SHOW RESOURCE	Displays information about the named database resource object and its status.
SHOW SITE	Displays information about the site object in the broker configuration.
SHUTDOWN	Shuts down a currently running Oracle database instance.
STARTUP	Starts an Oracle instance with several options, including mounting and opening a database.
SWITCHOVER	Performs a switchover operation in which the current primary site becomes a standby site, and the standby site becomes the primary site.

7.1.3 DGMGRL Command Usage Notes

To use the Data Guard command-line interface, the following must be true:

The DG_BROKER_START dynamic initialization parameter is set to TRUE.

Oracle Net must be properly configured on the hosts that contain the primary and standby database sites. Specifically, the primary and standby database services must be properly registered with the listener, a net service name should have been created for the primary and standby database sites, and the listener must be started.

See Also:

Chapter 6 for more information about preparing and starting Oracle Data Guard. See the Oracle9i 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.
For systems configured with shared servers, the connect string or Oracle Net service name used for broker communications must specify the use of a dedicated server (SERVER=DEDICATED) process instead of the shared server process. In addition, the connection between the CLI and the database instance must also use a dedicated server link.

To connect to a remote standby database and manage it, you need to set up a remote login password file. You also need to set up a remote login password file for DGMGRL to be able to restart the database automatically.

See Also:

Oracle9i Data Guard Concepts and Administration, the Oracle9i Database Administrator's Guide, and your operating system-specific documentation to set up remote access using the REMOTE_LOGIN_PASSWORDFILE initialization parameter

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, site and SiTe are equivalent, but "site" and "SiTe" are distinctive.
You can use the backslash (\) as an escape character. This makes it possible to embed any character in a character string of a command prompt.
Some operations on a broker configuration may require that one or more sites be shut down and restarted. In most cases, the CLI will automatically shut down and restart a given site for you if the following are true:
- The broker must be able to connect to the site using the username and password given in the last CONNECT command, even if the last CONNECT command was used to connect to another site. Thus, the remote password file for the site must contain the username and password given in the last CONNECT command.
- The PFILE of the site must be set by the ALTER SITE (AUTO PFILE) command, or the PFILE or the SPFILE for the site can be found at the default directory location.
  
  See Also:
  Oracle9i 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

Welcome to DGMGRL, type "help" for information.

DGMGRL> CONNECT sys/change_on_install;
Connected.

Example 2

This example demonstrates how to connect to the DGMGRL command-line interface on a remote system.

DGMGRL> CONNECT sys/change_on_install@remote-stby;
Connected.

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

You can use either the EXIT or the QUIT command to leave the DGMGRL command-line interface.

ALTER CONFIGURATION (protection mode)

Alters the current protection mode setting for broker configuration.

Format

ALTER CONFIGURATION SET PROTECTION MODE AS protection-mode;

Command Parameters

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

Perform the following steps before you use the ALTER CONFIGURATION command to set the protection mode:

If you plan to set the protection mode to either the MAXPROTECTION or MAXAVAILABILITY protection mode, ensure that standby redo logs are configured on a standby site.

Use the ALTER RESOURCE (property) command on a standby database of at least 1 site, to set the log transport mode that minimally corresponds to the protection mode you plan to set. For example, if you plan to set the overall Data Guard configuration to the MAXAVAILABILITY mode, you must use the ALTER RESOURCE command to set the SYNC mode for log transport services. For example:

ALTER RESOURCE 'Sales_db' ON SITE 'Boston' SET PROPERTY LogXptMode=SYNC;

The following table shows the configuration protection modes and the minimum corresponding settings for log transport services:

Protection Mode	Log Transport Mode	Require Physical Standby Database and Standby Redo Logs?
`MAXPROTECTION`	`SYNC`	Yes
`MAXAVAILABILITY`	`SYNC`	No
`MAXPERFORMANCE`	`ARCH` or `ASYNC`	No

See Also:

Chapter 4 for more information about the protection modes and log transport modes

After you change the protection mode, the primary site and database will automatically restart.

Use the SHOW CONFIGURATION VERBOSE command to display the current protection mode for the configuration.

DGMGRL> SHOW CONFIGURATION VERBOSE;
Configuration 
  Name:             'The SUPER cluster' 
  Enabled:          'yes' 
  Default state:    'ONLINE' 
  Intended state:   'ONLINE' 
  Protection Mode:  'MaxPerformance' 
  Number of sites:  2 
  Sites: 
    Primary Site: Primary 
    Standby Site: Standby2 
Current status for "The SUPER cluster": 
SUCCESS

If broker management of the configuration is disabled when you enter the ALTER 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 Examples

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.

After verifying that standby redo logs are configured on the standby site and that the LogXptMode is set properly to support the protection mode, enter the following commands:

DGMGRL> ALTER RESOURCE 'Sales_db' SET PROPERTY LogXptMode=SYNC;
Property "logxptmode" updated.

DGMGRL> ALTER CONFIGURATION SET PROTECTION MODE AS MAXPROTECTION;
Operation requires restart of site "Primary";
Shutting down site Primary...
Database closed.
Database dismounted.
ORACLE instance shut down.
Restarting site Primary...
Started "Primary" as new primary

The broker automatically stops and restarts the primary site and database.

ALTER CONFIGURATION (state)

Alters the intended (runtime) state of the broker configuration.

Format

ALTER CONFIGURATION SET STATE = state;

Command Parameters

state

The state in which you want the configuration to be running when management of the configuration is enabled. The possible states are:

OFFLINE
ONLINE

Usage Notes

Use the SHOW CONFIGURATION command to display the current default and intended states for the configuration.
This command changes only the intended (runtime) state for the configuration; the default state is not altered. If the configuration is set to offline, then all sites and database resources are set to the offline state. This means all databases will be shut down and restarted in nomount mode.
The state of the configuration cannot be changed when the configuration is disabled.

Command Examples

Example 1

In the following example, the broker configuration will be in the online state the next time you enable the configuration.

DGMGRL> ALTER CONFIGURATION SET STATE = ONLINE;
Succeeded.

ALTER RESOURCE (property)

Allows you to change the value of a property for the specified database resource object.

Format

ALTER RESOURCE resource-name [ON SITE site-name]

SET PROPERTY property-name = value;

Command Parameters

resource-name

The name of the database resource object for which you want to set a property value.

site-name

The name of the site object where the database resource object is located.

property-name

The name of the property for which you want to set a new value. Section 2.8 describes the database resource properties in detail.

value

The new value for the property. Section 2.8 describes the values for each property.

Usage Notes

You do not have to disable broker management of the configuration or database resource to change a database resource property. However, if the database resource is disabled when you use the ALTER RESOURCE command, the property change does not take effect until you enable broker management of the configuration.
If some properties are set with the wrong values while the database resource is disabled, then when the database is later enabled the broker will not set the incorrect values in the database. This results in a health check (a warning saying some properties are inconsistent between the Data Guard configuration file or database, or saying some property values are invalid (for example, returned errors might include ORA-16792, ORA-16801, ORA-16804). When this happens, check which property has the problem by investigating monitorable properties, InconsistentProperties, InconsistentLogXptProps, and by looking at the Data Guard console logs. Reset the property with the correct value.
If multiple log transport properties are set incorrectly in the Data Guard configuration file, then resetting one property to correct its value will not work because all of the properties correspond to one attribute of the LOG_ARCHIVE_DEST_n initialization parameter to be successful. In this case, disable the database resource, correct all property values, and then re-enable the resource again.
If you change the value of a property that corresponds to a static initialization parameter, you must shut down and start up the database for the change to take effect. For example, changing the DbFileNameConvert property (which corresponds to the DB_FILE_NAME_CONVERT initialization parameter) would require that you stop and start the database. See Chapter 8 for information about which properties are static and dynamic.
If you do not specify a site, the broker searches each site for the specified database resource. If it finds more than one database resource with the specified name (for example, if the database resource name you specified is not unique within the broker configuration), the ALTER RESOURCE command returns an error message. You must re-issue the ALTER RESOURCE command and specify a site name with the ON SITE option.

Use this command on the standby database to set the log transport mode that corresponds to the protection mode you set with the ALTER CONFIGURATION (protection mode)command. For example, if you plan to set the overall Data Guard configuration to the MAXAVAILABILITY protection mode, you must use the ALTER RESOURCE command to set the SYNC mode for log transport services. For example:

ALTER RESOURCE 'Sales_db' ON SITE 'Boston' SET PROPERTY LogXptMode=SYNC;

The following table shows the configuration protection modes and the corresponding settings for log transport services:

Protection Mode	Log Transport Mode	Require Physical Standby Database and Standby Redo Logs?
`MAXPROTECTION`	`SYNC`	Yes
`MAXAVAILABILITY`	`SYNC`	No
`MAXPERFORMANCE`	`ARCH` or `ASYNC`	No

Use the SHOW RESOURCE command to display the current property values for the database resource object.
See Section 2.8 for detailed information about each property.

Command Examples

Example 1

The ALTER RESOURCE command in the following example changes the value of the LogArchiveTrace property to be 127 for the database resource object named Sales_db.

DGMGRL> ALTER RESOURCE 'Sales_db' ON SITE 'Boston' SET PROPERTY 'LogArchiveTrace'='127';
Property "LogArchiveTrace" updated.

The command-line interface returns the following message to indicate that the LogArchiveTrace property was updated successfully in the Data Guard configuration file:

Property "LogArchiveTrace" updated

If broker management of the configuration is currently disabled, the property does not affect the actual database, until the next time you enable the broker configuration with the ENABLE CONFIGURATION command.

ALTER RESOURCE (state)

Allows you to change the state of the specified database resource object.

Format

ALTER RESOURCE resource-name [ON SITE site-name]

SET STATE = state;

Command Parameters

resource-name

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

site-name

The name of the site object that contains the database resource object that you want to alter.

state

The state to which the database resource will transition when it is enabled.

Usage Notes

Use the SHOW RESOURCE command to display information, such as the current runtime state of a database resource object.
If you do not specify a site, the broker searches each site for the specified database resource. If it finds more than one database resource with the specified name (for example, if the database resource name you specified is not unique within the broker configuration), the ALTER RESOURCE command returns an error message. You must issue the ALTER RESOURCE command again and specify a site name with the ON SITE option.

The database can be in an ONLINE or OFFLINE state. The ONLINE state has the following substates:

PHYSICAL-APPLY-READY
PHYSICAL-APPLY-ON (default state for a physical standby database)
READ-ONLY
LOGICAL-APPLY-READY
LOGICAL-APPLY-ON (default state for a logical standby database)
READ-WRITE
READ-WRITE-XPTON (default state for a primary database)

Command Examples

Example 1

The ALTER RESOURCE command in the following example changes the state of the Sales_db database resource to read/write.

DGMGRL> ALTER RESOURCE 'Sales_db' ON SITE 'Boston' SET STATE='read-write';
Succeeded.

ALTER SITE (state)

Allows you to change the state of a site object.

Format

ALTER SITE site-name

SET STATE = state;

Command Parameters

site-name

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

state

The state to which the site will transition when management of the site is enabled. The possible states are:

OFFLINE
ONLINE

Usage Notes

Use the SHOW SITE command to display information about a site object.
A site will operate either in the primary or standby role. When you change the state of the site to online, the site and its dependent database resource object begins operating in that role.

Command Examples

Example 1

DGMGRL> ALTER SITE 'Boston' SET STATE='online';
Succeeded.

ALTER SITE (AUTO PFILE)

Allows you to specify an initialization parameter file that will be used to automatically restart the database of the site.

Format

ALTER SITE site-name

SET AUTO PFILE= initialization-file | OFF ;

Command Parameters

site-name

The name of the site object for which you want to specify the automatic restart initialization parameter file.

initialization-file

The name of the PFILE initialization parameter file that will be used to automatically restart the database of the site.

Usage Notes

The broker requires that you specify a server parameter file (SPFILE) in the initialization parameter file. See the Oracle9i Database Administrator's Guide for more information about creating and using the server parameter file (SPFILE).
If you set the SET AUTO PFILE=OFF option and you receive a message telling you to restart a site, use the SHUTDOWN and STARTUP commands to restart your databases.
The default mode is SET AUTO PFILE='', which indicates using the default PFILE name to restart databases.
The information you specify with this command is session specific; that is, it resets to the default initialization parameter file when you connect to a database using the CONNECT command.
Use the SHOW SITE command with the VERBOSE option to display the current parameter file information for a site.

Command Examples

Example 1

DGMGRL> ALTER SITE 'Boston' SET AUTO PFILE='/oracle/dbs/initbs.ora';
Succeeded.

Example 2

DGMGRL> ALTER SITE 'Boston' SET AUTO PFILE=OFF;
Succeeded.

CONNECT

Connects a given username to the specified database.

Format

CONNECT username/password[@net-service-name];

Command Parameters

username/password

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

net-service-name

Consists of the Oracle Net service name of the site to which you want to connect. The exact syntax depends upon the Oracle Net communications protocol your Oracle installation uses.

Usage Notes

The username and password must be valid for the database to which you are trying to connect. The username you specify must have the SYSDBA privilege.
If the CONNECT command returns an error, check to see that you specified a valid service name.
The Data Guard broker communications must be configured over a dedicated server. (The connect string or the Oracle Net service name in the LISTENER.ORA file must specify the use of a dedicated server (SERVER=DEDICATED) process, not a shared (SERVER=SHARED) process.)

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 service name is prmy.

DGMGRL> CONNECT sys/change_on_install@prmy;
Connected.

CREATE CONFIGURATION

Creates a new broker configuration, and creates and adds a primary site object and a database resource object to the configuration.

Format

CREATE CONFIGURATION configuration-name AS

PRIMARY SITE IS site-name

RESOURCE IS resource-name

HOSTNAME IS host-name

INSTANCE NAME IS instance-name

SERVICE NAME IS net-service-name

SITE IS MAINTAINED AS standby-type;

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.

site-name

A user-friendly name for the primary site object.

resource-name

A user-friendly name for the database resource object to be created for the primary site.

host-name

The host name of the primary site, as shown in the V$INSTANCE view.

instance-name

The instance name of the primary database, as shown in the V$INSTANCE view.

net-service-name

Consists of the Oracle Net service name for the primary site. The exact syntax depends upon the Oracle Net communications protocol your Oracle installation uses. For more information, refer to the Oracle Net documentation.

standby-type

Specify PHYSICAL or LOGICAL for this parameter to indicate the type of standby database that this site will contain as a result of a switchover operation.

Usage Notes

A broker configuration is a named collection of one or more site objects and database resource objects that you want to manage as a group. You must specify a value for each of the parameters. There are no default values.
To add more standby sites and databases after you create the broker configuration, use the CREATE SITE command.

The Data Guard broker communications must be configured over a dedicated server. (The connect string or the net service name in the LISTENER.ORA file must specify the use of a dedicated server (SERVER=DEDICATED) process, not a shared (SERVER=SHARED) process.)
The host-name and instance-name parameters specify information the broker requires to uniquely identify a site in the configuration. To obtain the proper values for the host-name and instance-name parameters, use the values returned from the V$INSTANCE fixed view.

The following example shows a SQL*Plus statement that selects these values from the V$INSTANCE fixed view. In the example, the values boston and bstn should be supplied for the hostname and instance-name parameters in the CREATE CONFIGURATION command.
```
SQL> CONNECT sys/change_on_install AS SYSDBA;
SQL> SELECT HOST_NAME, INSTANCE_NAME FROM V$INSTANCE;
HOST_NAME                          INSTANCE_NAME
---------------------------------------------------------------
boston                             bstn
```

Command Examples

Example 1

The following example creates a new broker configuration named Sales with a database that will have the physical standby characteristics if the primary database transitions to the standby role in a future switchover operation.

DGMGRL> CREATE CONFIGURATION 'Sales' AS
  PRIMARY SITE IS 'Boston'
  RESOURCE IS 'Sales_db'
  HOSTNAME IS 'boston'
  INSTANCE NAME IS 'bstn'
  SERVICE NAME IS 'bstn'
    SITE IS MAINTAINED AS PHYSICAL;

Configuration "Sales" added with primary site "Boston"
Database resource "Sales_db" added.

CREATE SITE

Creates a new standby site object and database resource object and adds it to an existing broker configuration.

Format

CREATE SITE site-name

RESOURCE IS resource-name

HOSTNAME IS host-name

INSTANCE NAME IS instance-name

SERVICE NAME IS net-service-name

SITE IS MAINTAINED AS standby-type;

Command Parameters

site-name

A user-friendly name for the site object 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.

resource-name

A user-friendly name for the database resource object to be created for the standby site.

host-name

The host name of the standby site.

instance-name

The instance name of the primary database.

net-service-name

Consists of the Oracle Net service name of the standby site that you want to add. The exact syntax depends upon the Oracle Net communications protocol your Oracle installation uses. For more information, see the Oracle Net documentation.

standby-type

Specify PHYSICAL or LOGICAL for this parameter to indicate the type of standby database that this site will contain.

Usage Notes

The standby database must already exist on the site before you can add the site object to a broker configuration.

See Also:
Oracle9i Data Guard Concepts and Administration for information about creating a standby database
Before you can add standby sites with the CREATE SITE command, you must create the broker configuration using the CREATE CONFIGURATION command.
Use the CREATE SITE command after you have connected to the primary database using the CONNECT command.
You can add up to nine standby sites to an existing configuration.
The broker configuration can be in any state (online, offline) when you create a site.
If management of the broker configuration is enabled when you issue the CREATE SITE command, the site object is created in a disabled state to allow you to change properties before the site goes online.
A resource can be associated with only 1 broker configuration. Site names must be unique within the configuration

The Data Guard broker communications must be configured over a dedicated server. (The connect string or the net service name in the LISTENER.ORA file must specify the use of a dedicated server (SERVER=DEDICATED) process, not a shared (SERVER=SHARED) process.)
The host-name and instance-name parameters specify information the broker requires to uniquely identify a site in the configuration. To obtain the proper values for the host-name and instance-name parameters, use the values returned from the V$INSTANCE fixed view.

The following example shows a sample SQL*Plus statement that selects these values from the V$INSTANCE fixed view. In the example, the values sf and sfdb should be supplied for the host-name and instance-name parameters in the CREATE SITE command.
```
SQL> CONNECT sys/change_on_install AS SYSDBA;
SQL> SELECT HOST_NAME, INSTANCE_NAME FROM V$INSTANCE;
HOST_NAME                          INSTANCE_NAME
---------------------------------------------------------------
sf                                 sfdb
```

Command Examples

Example 1

The following example demonstrates how to add a standby site called San Francisco to the broker configuration.

DGMGRL> CREATE SITE 'San Francisco'
  RESOURCE IS 'reportingdb'
  HOSTNAME IS 'sf'
  INSTANCE NAME IS 'sfdb'
  SERVICE NAME IS 'dest2'
    SITE IS MAINTAINED AS PHYSICAL;

Site "San Francisco" added to configuration.
Database resource "reportingdb" added.

DISABLE CONFIGURATION

Disables broker management of a broker configuration and all of its site objects and database resource objects.

Format

DISABLE CONFIGURATION;

Command Parameters

None.

Usage Notes

A disabled configuration is no longer managed by the broker.
The only way to disable broker management of the primary site is to use the DISABLE CONFIGURATION command.
This command does not remove or delete the broker configuration. See the REMOVE CONFIGURATION command for more information about removing the configuration.

Command Examples

Example 1

The following example disables management of the broker configuration and all of its sites and database resources.

DGMGRL> DISABLE CONFIGURATION;
Disabled.

DISABLE RESOURCE

Disables broker management of a database resource object.

Format

DISABLE RESOURCE resource-name [ON SITE site-name];

Command Parameters

resource-name

The name of the database resource object that you want to disable.

site-name

The name of the site containing the database resource that you want to disable.

Usage Notes

A disabled database resource is no longer managed by the broker.
If you do not specify a site, the broker searches each site for the specified database resource. If it finds more than one database resource with the specified name (for example, if the database resource name you specified is not unique within the configuration), the DISABLE RESOURCE command returns an error message. You must re-issue the DISABLE RESOURCE command and specify a site name with the ON SITE option.
This command does not remove or delete the database resource from the broker configuration.

Command Examples

Example 1

The following example demonstrates how to disable management of the database resource reportingdb from the San Francisco site.

DGMGRL> DISABLE RESOURCE 'reportingdb' ON SITE 'San Francisco';
Disabled.

DISABLE SITE

Disables broker management of the specified standby site object in the broker configuration and any database resource objects on the site.

Format

DISABLE SITE site-name;

Command Parameters

site-name

The name of the standby site that you want to disable.

Usage Notes

When you disable broker management of a standby site in the configuration, management of the database resource configured on the standby site is also disabled.
You cannot disable the primary site with the DISABLE SITE command. Use the DISABLE CONFIGURATION command to disable the primary site.

Command Examples

Example 1

The following example demonstrates how to disable broker management of the San Francisco standby site.

DGMGRL> DISABLE SITE 'San Francisco';
Disabled.

ENABLE CONFIGURATION

Enables the broker to actively manage the broker configuration including all of its site objects and database resource objects.

Format

ENABLE CONFIGURATION;

Command Parameters

None.

Usage Notes

This command enables the broker to manage the broker configuration including all of the sites and database resources in the configuration.
Use this command to enable broker management of the primary site object.
When you enable broker management of a broker configuration, its default state is online. To change the intended runtime state of the configuration, use the ALTER CONFIGURATION (state) command.
By default, broker management of the primary database resource object is enabled in the online state with the log shipping turned on (READ-WRITE-XPTON state), a physical standby database resource object is enabled in the PHYSICAL-APPLY-ON state, and a logical standby database resource object is enabled in the LOGICAL-APPLY-ON state. You can change the state of the database resource using the ALTER RESOURCE (state) command, but not when the resource or a configuration is disabled.
See the SHOW CONFIGURATION command to display information about the configuration.

Command Examples

Example 1

The following example enables management of a broker configuration.

DGMGRL> ENABLE CONFIGURATION;
Enabled.

ENABLE RESOURCE

Enables the broker to actively manage the specified database resource object.

Format

ENABLE RESOURCE resource-name [ON SITE site-name];

Command Parameters

resource-name

The name of the database resource object you want to manage with the broker.

site-name

The name of the site object containing the database resource object that you want to enable.

Usage Notes

If broker management of the site where the database resource is located is disabled, the database resource you specify with the ENABLE RESOURCE command will remain disabled (and cannot be managed by the broker) until you enable the site. See the ENABLE SITE command.
By default, broker management of the standby database resource object is enabled with log apply services started (a physical standby database is in the PHYSICAL-APPLY-ON state and a logical standby database resource object is enabled in the LOGICAL-APPLY-ON state). You can change the state of the database resource using the ALTER RESOURCE (state) command, but not when the database resource, site, or configuration is disabled.
If you do not specify a site, the broker searches each site for the specified database resource. If it finds more than one database resource with the specified name (for example, if the database resource name you specified is not unique within the configuration), the ENABLE RESOURCE command returns an error message. You must re-issue the ENABLE RESOURCE command and specify a site name with the ON SITE option.
Use the SHOW RESOURCE command to display information about the database resource, including its default and intended states, and the properties of the database resource.

Command Examples

Example 1

The following example enables broker management of the database resource object named Sales_db.

DGMGRL> ENABLE RESOURCE 'Sales_db';
Enabled.

ENABLE SITE

Enables the broker to actively manage the specified standby site object, including its database resource object.

Format

ENABLE SITE site-name;

Command Parameters

site-name

The name of the standby site object you want to manage with the broker.

Usage Notes

This command enables the broker to actively manage the standby site object.
To enable broker management of a primary site object, use the ENABLE CONFIGURATION command.
When you enable broker management of a standby site object, the database resource object on the standby site is also enabled (unless it has been explicitly disabled with the DISABLE command).
By default, management of the standby database resource object is enabled with log apply services started (in the PHYSICAL-APPLY-ON or LOGICAL-APPLY-ON state. You can change the state of the database resource using the ALTER RESOURCE (state) command.

Command Examples

Example 1

The following example enables management of the standby site named San Francisco.

DGMGRL> ENABLE SITE 'San Francisco';
Enabled.

EXIT

Exits the command-line interface.

Format

EXIT;

Usage Notes

This command has the same effect as the QUIT command.
A database connection is not required to execute this command. However, if you are connected, this command breaks the connection.

Command Examples

Example 1

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

DGMGRL> EXIT;

FAILOVER

A failover operation changes one of the standby sites and its database into the role of a primary site and database.

Note:

Because a failover operation results in a role transition that may result in the loss of application data, you should perform a failover operation only if the primary database has failed. If you want the current primary database and a standby database to switch roles, then use the SWITCHOVER command.

Format

FAILOVER TO site-name {GRACEFUL | FORCED};

Command Parameters

site-name

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

Usage Notes

You must include one of the following options on the FAILOVER command:
- GRACEFUL: A graceful failover automatically recovers some or all of the original primary database application data. A graceful failover allows the new primary database to communicate with the bystanders and attempt to keep the active (enabled) bystanders in the configuration. This is the recommended failover option.
- FORCED: A forced failover may result in lost application data even when standby redo logs are configured on the standby database.
To be considered as a viable candidate for the failover operation, the specified standby site and its database must be enabled before the failover operation can proceed.
The failover operation operates on the site object, and its dependent database resource object. Thus, the failover operation changes one of the standby databases into the role of a primary database. Any other bystanders remain in the standby role.
Before you issue the FAILOVER command, verify that you are connected to the standby site that will become the new primary site. If necessary, issue a CONNECT command to connect to the standby site.
If the standby site that is transitioning into the role of primary site contains a physical standby database, then the instance will be restarted after the failover operation completes. If the site contains a logical standby database, the instance does not need to be restarted.
Once you have failed over, you can only configure the original primary database to be a standby database; you cannot restart the original primary site or database to run in the primary role.

Command Examples

Example 1

The following example performs a graceful failover in which the standby site, Standby2, transitions to the primary role:

DGMGRL> FAILOVER TO 'Standby2' GRACEFUL;
Performing failover NOW. Please wait...
Operation requires restart of site "Standby2"
Shutting down site Standby2...
database not mounted
ORACLE instance shut down.
Restarting site Standby2...
Started "Standby2" as new primary
Failover succeeded. New primary is "Standby2"

Example 2

The following example performs a forced failover operation:

DGMGRL> FAILOVER TO 'Standby4' FORCED;
Performing failover NOW. Please wait...
Operation requires restart of site "Standby4"
Shutting down site Standby4...
database not mounted
ORACLE instance shut down.
Restarting site Standby4...
Started "Standby4" as new primary
Failover succeeded. New primary is "Standby4"

HELP

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

Format

HELP [<topic>];

Command Parameters

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:

ALTER
CONNECT
CREATE
DISABLE
ENABLE
EXIT
FAILOVER
HELP
QUIT
REMOVE
SHOW
SHUTDOWN
STARTUP
SWITCHOVER

Usage Notes

A database connection is not required to execute this command.

Command Examples

Example 1

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

DGMGRL> HELP HELP;
Display the help for a given command
DGMGRL> HELP CONNECT;
Connect to a server
connect <user>/<password>@<connect>;

Example 2

DGMGRL> HELP ALTER;
edit a configuration, site or resource
alter configuration set state = '[ONLINE|OFFLINE]'

alter configuration set protection mode as
  '[MaxProtection|MaxAvailability|MaxPerformance]'

alter site '<site name>' set state = '[ONLINE|OFFLINE]'

alter site '<site name>' set auto pfile='<pfile>'

alter resource '<resource name>'
   [ on site '<site name>'] set state = '<state>'

alter resource '<resource name> [ on site <site name> ] '
   set property '<property name>' = '<value>';

QUIT

Exits the Data Guard command-line interface.

Format

QUIT;

Usage Notes

This command has the same effect as the EXIT command.
A database connection is not required to execute this command. However, if you are connected, this command breaks the connection.

Command Examples

Example 1

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

DGMGRL> QUIT;

REMOVE CONFIGURATION

Removes all of the broker configuration information from the Data Guard configuration file, and removes management of all of the site and database resource objects associated with the broker configuration.

Caution:

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

Format

REMOVE CONFIGURATION;

Command Parameters

None.

Usage Notes

When you remove a broker configuration, management of all of the site objects and database resource objects associated with that configuration is removed.
This command does not remove or affect the actual primary or standby database instances, databases, datafiles, or control files.

Command Examples

Example 1

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

DGMGRL> REMOVE CONFIGURATION;
Removed configuration.

REMOVE SITE

Removes the specified standby site object from the broker configuration.

Caution:

When you use the REMOVE SITE command, all of the information about the standby site and its database resource is deleted from the Data Guard configuration file and cannot be recovered.

Format

REMOVE SITE site-name;

Command Parameters

site-name

The name of the standby site that you want to remove.

Usage Notes

When you remove a standby site, management of the database resource object associated with that standby site is removed. However, this command does not remove or affect the actual standby site and database.
You cannot remove the primary site with this command. Use the REMOVE CONFIGURATION command to remove the primary site object.

Command Examples

Example 1

The following example shows how to remove information about the site object named San Francisco.

DGMGRL> REMOVE SITE 'San Francisco';
Removed site "San Francisco" from configuration.

SHOW CONFIGURATION

Displays a brief or a detailed summary about the broker configuration.

Format

SHOW CONFIGURATION [VERBOSE] [property-name];

Command Parameters

property-name

The name of the property for which you want to display summary information. Available properties are:

ENABLED
EXPLICIT_DISABLE
INTENDED_STATE
HEALTH_CHECK_INTERVAL
STATUS

See Section 2.8 for complete information about properties.

Usage Notes

The default is to display a brief summary of the configuration. Use the VERBOSE option to display a detailed summary of the configuration.
Use the ALTER CONFIGURATION (state) command to change the intended state of a configuration.
Use the SHOW DEPENDENCY TREE command to display the dependency tree and default path information for the configuration.

Command Examples

Example 1

The following example provides a brief summary of the Sales configuration.

DGMGRL> SHOW CONFIGURATION;
Configuration 'Sales' is
  Primary Site is 'Boston'
  Standby Site is 'San Francisco'
Current status for "Sales":
SUCCESS

Example 2

The following example uses the VERBOSE option to show complete information about the Sales configuration.

DGMGRL> SHOW CONFIGURATION VERBOSE; 
Configuration 
  Name:             'The SUPER cluster' 
  Enabled:          'yes' 
  Default state:    'ONLINE' 
  Intended state:   'ONLINE' 
  Protection Mode:  'MaxPerformance' 
  Number of sites:  2 
  Sites: 
    Primary Site is 'Primary'
    Standby Site is 'Standby2' 
Current status for "The SUPER cluster": 
SUCCESS

Example 3

The following example shows the STATUS property for the Sales configuration.

DGMGRL> SHOW CONFIGURATION STATUS;
  STATUS = 'SUCCESS'

SHOW DEPENDENCY TREE

Displays a dependency tree that shows a static map of the broker configuration and the default online states for each database resource in the configuration.

Format

SHOW DEPENDENCY TREE;

Usage Notes

For detailed information about the configuration, use the SHOW CONFIGURATION command.

Command Examples

Example 1

The following example shows a configuration named Sales with two sites (Boston and San Francisco) and database resource objects called Sales_db and reportingdb. The database resource object (Sales_db) is brought online in its default state of READ_WRITE_XPTON when Boston is running as the primary site. The other database resource object, reportingdb, is brought online in its default state of PHYSICAL_APPLY_ON when San Francisco is running as the standby site.

DGMGRL> SHOW DEPENDENCY TREE;
Sales
Sales[ONLINE]->Boston
Sales[ONLINE]->Boston[PRIMARY]->Sales_db
Sales[ONLINE]->Boston[STANDBY]->Sales_db
Sales[ONLINE]->San Francisco
Sales[ONLINE]->San Francisco[PRIMARY]->reportingdb
Sales[ONLINE]->San Francisco[STANDBY]->reportingdb

Default Path:
Sales[ONLINE]->Boston[PRIMARY]
Sales[ONLINE]->Boston[PRIMARY]->Sales_db[READ-WRITE-XPTON]
Sales[ONLINE]->San Francisco[STANDBY]
Sales[ONLINE]->San Francisco[STANDBY]->reportingdb[PHYSICAL-APPLY-ON]

In the example, the reportingdb database resource has a dependency on whether or not the San Francisco site is in the primary or the standby role. Furthermore, the reportingdb database resource object will go to the PHYSICAL-APPLY-ON state when the San Francisco site is a standby site.

Example 2

The following example shows the dependency tree output for a configuration that has multiple standby sites.

DGMGRL> SHOW DEPENDENCY TREE;
The SUPER cluster
The SUPER cluster[ONLINE]->Primary
The SUPER cluster[ONLINE]->Primary[PRIMARY]->db
The SUPER cluster[ONLINE]->Primary[STANDBY]->db
The SUPER cluster[ONLINE]->Standby2
The SUPER cluster[ONLINE]->Standby2[PRIMARY]->reportdb2
The SUPER cluster[ONLINE]->Standby2[STANDBY]->reportdb2
The SUPER cluster[ONLINE]->Standby3
The SUPER cluster[ONLINE]->Standby3[PRIMARY]->reportdb3
The SUPER cluster[ONLINE]->Standby3[STANDBY]->reportdb3

Default Path:
The SUPER cluster[ONLINE]->Primary[PRIMARY]
The SUPER cluster[ONLINE]->Primary[PRIMARY]->db[READ-WRITE-XPTON]
The SUPER cluster[ONLINE]->Standby2[STANDBY]
The SUPER cluster[ONLINE]->Standby2[STANDBY]->reportdb2[PHYSICAL-APPLY-ON]
The SUPER cluster[ONLINE]->Standby3[STANDBY]
The SUPER cluster[ONLINE]->Standby3[STANDBY]->reportdb3[PHYSICAL-APPLY-ON]

SHOW LOG

Displays the Data Guard configuration log or database alert log from the named site object.

Format

SHOW LOG [ALERT] [LATEST] ON SITE site-name;

Command Parameters

ALERT

Displays the database alert log for the specified site object.

LATEST

Specifies the last 20 lines of the SHOW LOG command output.

site-name

The user-friendly name of the site for which you want to display the Data Guard configuration log or the database alert log.

Usage Notes

If you omit the ALERT parameter, then the Oracle Data Guard configuration log for the named site is displayed (if the site is enabled).

Command Examples

Example 1

The following example displays the last 20 lines of the SHOW LOG command output for the Boston site.

DGMGRL> SHOW LOG LATEST ON SITE 'Boston';
DRSLOG
LINE  OBJECT_ID DATE                LOG
--------------------------------------------------------------------------------
 2961       913 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2962       914 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2963       915 2000-11-02-09:29:33  Parent 33554433 child 33554690 vinst
33554690 state 5 (PRIMARY) name reportingdb
 2964       915 2000-11-02-09:29:33  Parent 33554433 child 33554691 vinst
33554691 state 6 (STANDBY) name reportingdb
 2965       915 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=219)
 2966       916 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2967       917 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2968       918 2000-11-02-09:29:33  Parent 1 child 16777217 vinst 16777217
state 1 (ONLINE) name Boston
 2969       918 2000-11-02-09:29:33  Parent 1 child 33554433 vinst 33554433
state 1 (ONLINE) name San Francisco
 2970       918 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=204)
 2971       920 2000-11-02-09:29:33  Parent 16777217 child 16777474 vinst
16777474 state 5 (PRIMARY) name Sales_db
 2972       920 2000-11-02-09:29:33  Parent 16777217 child 16777475 vinst
16777475 state 6 (STANDBY) name Sales_db
 2973       920 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=201)
 2974       922 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2975       925 2000-11-02-09:29:33  Parent 33554433 child 33554690 vinst
33554690 state 5 (PRIMARY) name reportingdb
 2976       925 2000-11-02-09:29:33  Parent 33554433 child 33554691 vinst
33554691 state 6 (STANDBY) name reportingdb
 2977       925 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=219)
 2978       928 2000-11-02-09:29:33  DMON: DRS OP 204: success. (len=61)
 2979       929 2000-11-02-09:29:33  DMON: DRS OP 207: success. (len=79)
 2980       935 2000-11-02-09:29:34  DMON: DRS OP 207: success. (len=79)

Example 2

The following example displays the last 20 lines of the database alert log for the Boston site.

DGMGRL> SHOW LOG ALERT LATEST ON SITE 'Boston';
DRSLOG
LINE LOG
--------------------------------------------------------------------------------
 1672 Thu Nov  2 09:28:07 2000
 1673 ALTER SYSTEM SET fal_server='' SCOPE=MEMORY SID='bstn';
 1674 ALTER SYSTEM SET fal_client='bstn' SCOPE=MEMORY SID='bstn';
 1675 Thu Nov  2 09:29:31 2000
 1676 ALTER SYSTEM SET fal_server='' SCOPE=MEMORY SID='bstn';
 1677 ALTER SYSTEM SET fal_client='bstn' SCOPE=MEMORY SID='bstn';
 1678 Thu Nov  2 09:29:31 2000
 1679 Beginning log switch checkpoint up to RBA [0x11.2.10], SCN:0x0000.00011b11
 1680 Thread 1 advanced to log sequence 17
 1681   Current log# 2 seq# 17 mem# 0: /ade/ctrezza_bstn/oracle/dbs/t_log2.f
 1682 Thu Nov  2 09:29:31 2000
 1683 ARC0: Beginning to archive log# 1 thread 1 seq# 16
 1684 ARC0: Completed archiving  log# 1 seq# 16 thrd# 1
 1685 Thu Nov  2 09:29:32 2000
 1686 ALTER SYSTEM SET fal_server='' SCOPE=MEMORY SID='bstn';
 1687 ALTER SYSTEM SET fal_client='bstn' SCOPE=MEMORY SID='bstn';
 1688 ALTER SYSTEM SET fal_server='' SCOPE=MEMORY SID='bstn';
 1689 ALTER SYSTEM SET fal_client='bstn' SCOPE=MEMORY SID='bstn';
 1690 Thu Nov  2 09:29:33 2000
 1691 Completed checkpoint up to RBA [0x11.2.10], SCN: 0x0000.00

SHOW RESOURCE

Displays a brief or a detailed summary and status of the specified database resource object.

Format

SHOW RESOURCE [VERBOSE] resource-name [property-name] [ON SITE site-name];

Command Parameters

resource-name

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

property-name

The name of the property for which you want to display summary information. See Section 4.3 for a list of database resource properties.

site-name

The name of the site object that has the database resource for which you want a brief summary.

Usage Notes

The default is to display a brief summary of the database resource object. Specify the VERBOSE option to display a detailed summary.
Use the ALTER RESOURCE (property) command to alter the properties of a database resource object, or use the ALTER RESOURCE (state) command to alter the state of a database resource object.
If you do not specify a site, the broker searches each site for the specified database resource. If it finds more than one database resource with the specified name (for example, if the database resource name you specified is not unique within the configuration), the SHOW RESOURCE command returns an error message. You must re-issue the SHOW RESOURCE command and specify a site name with the ON SITE option.
To display dependency information, use the SHOW DEPENDENCY TREE command.
Use the SHOW RESOURCE resource-name property-name command to show monitorable properties.

Command Examples

Example 1

The following example shows a brief summary of the database resource object called Sales_db.

DGMGRL> SHOW RESOURCE 'Sales_db';
Resource 'Sales_db' on site 'Boston'
  depends on 'Boston'
Current status for "Sales_db":
SUCCESS

Example 2

The following example uses the VERBOSE option to show complete information about the database resource object called Sales_db on the Boston site.

DGMGRL> SHOW RESOURCE VERBOSE Sales_db;
Resource
  Name:             reportdb2
  Manager Type:     internal
   Standby Type:     PHYSICAL
Online States:
  ONLINE
  PHYSICAL-APPLY-READY
  PHYSICAL-APPLY-ON
  READ-ONLY
  LOGICAL-APPLY-READY
  LOGICAL-APPLY-ON
  READ-WRITE
  READ-WRITE-XPTON
Properties:
  INTENDED_STATE                  = 'PHYSICAL-APPLY-ON'
  ENABLED                         = 'yes'
  IGNORE_STATUS                   = 'no'
  LogXptMode                      = 'ARCH'
  Dependency                      = ''
  Alternate                       = ''
  DelayMins                       = '0'
  Binding                         = 'OPTIONAL'
  MaxFailure                      = '0'
  ReopenSecs                      = '300'
  AsyncBlocks                     = '2048'
  LogShipping                     = 'ON'
  ApplyNext                       = '0'
  ApplyNoDelay                    = 'no'
  ApplyParallel                   = '1'
  StandbyArchiveDest              = '/oracle/dbs/a2'
  LogArchiveTrace                 = '4095'
  StandbyFileManagement           = 'AUTO'
  ArchiveLagTarget                = '0'
  LogArchiveMaxProcesses          = '5'
  LogArchiveMinSucceedDest        = '1'
  DbFileNameConvert               = 'dbs/t, dbs/s2t, dbs/s3t, dbs/s2t'
  LogFileNameConvert              = 'dbs/t, dbs/s2t, dbs/s3t, dbs/s2t'
  LogArchiveFormat                = 'r_%t_%s.arc'
  InconsistentProperties          = '(monitor)'
  InconsistentLogXptProps         = '(monitor)'
  SendQEntries                    = '(monitor)'
  LogXptStatus                    = '(monitor)'
  SbyLogQueue                     = '(monitor)'
Properties for 'PRIMARY' state:
  DEFAULT_STATE    = 'READ-WRITE-XPTON'
  EXPLICIT_DISABLE = 'no'
  REQUIRED         = 'yes'
Properties for 'STANDBY' state:
  DEFAULT_STATE    = 'PHYSICAL-APPLY-ON'
  EXPLICIT_DISABLE = 'no'
  REQUIRED         = 'yes'
Current status for "Sales_db":
SUCCESS

Example 3

If you see the ORA-16792 error message when you use the SHOW RESOURCE command, you can specify the "InconsistentProperties" property on the command to show a detailed report of the properties that are causing the error.

DGMGRL> SHOW RESOURCE db ; 
Resource 'db' on site 'Primary' 
  depends on 'Primary' 
Current status for "db": 
Warning: ORA-16792: Some configurable property value is inconsistent with the 
database setting 
DGMGRL> SHOW RESOURCE db 'InconsistentProperties' ;

INCONSISTENT PROPERTIES 
       PROPERTY_NAME       DATABASE_VALUE         SPFILE_VALUE       METADATA_VALUE 
    ArchiveLagTarget                  100                  100                   -1

SHOW SITE

Displays a brief or detailed summary of the specified site object.

Format

SHOW SITE [VERBOSE] site-name [property-name];

Command Parameters

site-name

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

property-name

The name of the property for which you want to display summary information. Available properties are:

ENABLED
EXPLICIT_DISABLE
INTENDED_STATE
HEALTH_CHECK_INTERVAL
STATUS

See Section 2.8 for complete information about site properties.

Usage Notes

The default is to display a brief summary of the site object. Specify the VERBOSE option to display a detailed summary.
Use the SHOW DEPENDENCY TREE command to display dependency tree information about a site object.
Use the ALTER SITE (state) command to change the state of a site object.

Command Examples

Example 1

The following example shows a brief summary of the site object called Boston.

DGMGRL> SHOW SITE 'Boston';
Site 'Boston' is
  Hostname is 'boston'
  Instance name is 'bstn'
  Service name is 'bstn'
  Standby is maintained as 'physical'
  Site has 1 resource
    Resource is 'Sales_db'
Current status for "Boston":
SUCCESS

Example 2

The following example uses the VERBOSE option to show complete information about the site object called Boston.

DGMGRL> SHOW SITE VERBOSE 'Boston';
Site
  Name:                          'Boston'
  Hostname:                      'boston'
  Instance name:                 'bstn'
  Service Name:                  'bstn'
  Standby Type:                  'physical'
  Number Built-in Processes:     '2'
  Number Generic  Processes:     '0'
  Enabled:                       'yes'
  Required:                      'yes'
  Default State:                 'PRIMARY'
  Intended State:                'PRIMARY'
  PFILE: 
  Number of resources:  1
  Resources:
    Name: Sales_db (default) (verbose name='Sales_db')

Example 3

The following example shows the status property of the site object called Boston.

DGMGRL> SHOW SITE 'Boston' STATUS;
  STATUS = SUCCESS

SHUTDOWN

Shuts down a currently running Oracle instance.

Format

SHUTDOWN [ ABORT | IMMEDIATE | NORMAL ];

Command Parameters

None.

Usage Notes

Before you shut down a database, disable the database resource object in the broker configuration first. When you later restart the database, use the STARTUP NOMOUNT command, then enable the database resource object and allow the broker bring the database to the correct state.
Using the SHUTDOWN command with no arguments is equivalent to using the SHUTDOWN NORMAL command.
You must be connected to a database as SYSOPER or SYSDBA. If connecting through an Oracle Net service name, it must be a dedicated server connection. For more information about connecting to a database, see the CONNECT command.
The following list describes the options to the SHUTDOWN command:
- ABORT
  
  Proceeds with the fastest possible shutdown of the database without waiting for calls to complete or for users to disconnect from the database. Uncommitted transactions are not rolled back. Client SQL statements currently being processed are terminated. All users currently connected to the database are implicitly disconnected, and the next database startup will require instance recovery. You must use this option if a background process terminates abnormally.
- IMMEDIATE
  
  Does not wait for current calls to complete or users to disconnect from the database. Further connections are prohibited. The database is closed and dismounted. The instance is shut down, and no instance recovery is required on the next database startup.
- NORMAL
  
  This is the default option which waits for users to disconnect from the database. Further connections are prohibited. The database is closed and dismounted. The instance is shut down, and no instance recovery is required on the next database startup.

Command Examples

Example 1

The following command shuts down the database in normal mode.

DGMGRL > SHUTDOWN;

Database closed. 
Database dismounted. 
Oracle instance shut down.

STARTUP

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

Force: shuts down the current Oracle instance in the SHUTDOWN ABORT mode before restarting it.
Restrict: allows only Oracle users with the RESTRICTED SESSION system privilege to connect to the instance.
Pfile: specifies the PFILE initialization parameter file to be used when the database instance is started.
Mount: mounts the specified database without opening it. If you do not specify a database name, the database name is taken from the initialization parameter DB_NAME.
Open: mounts and opens the specified database.
Nomount: starts the specified database instance without mounting the database.

Format

STARTUP

[FORCE]

[RESTRICT]

[PFILE=filename]

[MOUNT [database-name] | OPEN [open-options] [database-name] | 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 SPFILE startup parameter file (specific to your operating system) is used.

database-name

The name of the database to mount or open. If you do not specify the database-name parameter, the database name is taken from the initialization parameter DB_NAME.

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

Before you shut down a database, disable the database resource object in the broker configuration first. When you later restart the database, use the STARTUP NOMOUNT command, then enable the database resource object and allow the broker bring the database to the correct state.
You cannot use the STARTUP command if the broker management of the configuration is enabled.
You must be connected to the instance as SYSOPER or SYSDBA. If connecting through an Oracle Net service name, it must be a dedicated server connection. For more information about connecting to the instance, see the CONNECT command.
Using the STARTUP command with no arguments is equivalent to using the STARTUP OPEN command.
If you do not use the FORCE option when you use the STARTUP command and the current database instance is running, an error results. The FORCE option is useful when you are debugging and when error conditions are occurring. Otherwise, it should not be used.
Use the RESTRICT option to allow only Oracle users with the RESTRICTED SESSION system privilege to connect to the instance. Later, you can use the ALTER SYSTEM command to disable the restricted session feature.
If you do not use the PFILE option to specify the initialization parameter file, the STARTUP command uses the default SPFILE server parameter file, if it exists. Else, it uses the default initialization parameter file. The default files are platform specific. For example:
- On a UNIX system, the default initialization parameter file might be similar to the following:
```
$oracle_home/DBS/INIT$oracle_sid.ORA
```
- On a Windows system, the default initialization parameter file might be similar to the following:
```
%oracle_home%\DATABASE\INITORCL.ORA  
```
See your operating system-specific documentation for more information about the default parameter files.
Use the MOUNT option to mount a primary database or a logical standby database without opening it. If you do not specify a database name, the database name is taken from the initialization parameter DB_NAME.
Use the OPEN option to mount and open the specified database.
The NOMOUNT option starts the database instance without mounting the database. You cannot use the NOMOUNT option with the MOUNT or OPEN options.

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 database;

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 command shuts down a particular database, immediately restarts and opens it in parallel mode, allows access only users with restricted session privileges, and uses the parameter file MYINIT.ORA.

DGMGRL > STARTUP FORCE RESTRICT PFILE=myinit.ora SHARED OPEN database;

Example 5

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

DGMGRL> STARTUP MOUNT;

SWITCHOVER

A switchover operation is a planned transition in which the primary site changes roles with one of the standby sites. When you issue the switchover command, the current primary site becomes a standby site, and the selected target standby site becomes the primary site.

Format

SWITCHOVER TO site-name;

Command Parameters

site-name

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

Usage Notes

If the standby site that is assuming the primary role contains a physical standby database, then both the primary and standby databases will be restarted after the SWITCHOVER operation completes. If the standby site contains logical standby databases, then neither the primary database nor the logical standby database is restarted.
The broker verifies that the primary and standby sites and databases are in the following states prior to starting the switchover operation:
- The primary site and database must be enabled and online, with log transport services started (READ-WRITE-XPTON substate).
- If switching to a physical standby site, the site and database must be enabled and online, with log apply services started (PHYSICAL-APPLY-ON substate).
- If switching to a logical standby site, the site and database must be enabled and online, with log apply services started (LOGICAL-APPLY-ON substate).
The broker allows the switchover operation to proceed as long as there are no log transport services errors for the standby site that you selected to participate in the switchover operation. However, errors occurring for any bystanders will not prevent the switchover operation from proceeding.

Command Examples

Example 1

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

DGMGRL> SWITCHOVER TO 'Standby2'
Performing switchover NOW. Please wait...
Operation requires restart of site "Primary"
Operation requires restart of site "Standby2"
Shutting down site Primary...
database not mounted
ORACLE instance shut down.
Shutting down site Standby2...
database not mounted
ORACLE instance shut down.
Restarting site Primary...
Restarting site Standby2...
Started "Primary" as standby
Started "Standby2" as new primary
Switchover succeeded. New primary is "Standby2"

Example 2

This switchover example shows a switchover operation that succeeded but returns an error because the CLI cannot shut down and start up the primary and standby databases.

DGMGRL> SWITCHOVER TO 'Standby2';
Performing switchover NOW. Please wait...
Operation requires restart of site "Primary"
Operation requires restart of site "Standby2"
Shutting down site Primary...
ORA-01031: insufficient privileges

You are no longer connected to ORACLE
Please connect again.
Unable to shut down Primary
You must restart site "Primary" manually.
You must restart site "Standby2" manually.
Switchover succeeded. New primary is "Standby2"

Note:

For the CLI 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 operation. 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.

7 Data Guard Command-Line Interface Reference

7.1 Starting the Data Guard Command-Line Interface

7.1.1 DGMGRL Optional Parameters

7.1.2 DGMGRL Command Format and Parameters

Table 7-1 Summary of DGMGRL Commands

7.1.3 DGMGRL Command Usage Notes

Command Examples

Example 1

Example 2

7.2 Stopping the Data Guard Command-Line Interface

ALTER CONFIGURATION (protection mode)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

ALTER CONFIGURATION (state)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

ALTER RESOURCE (property)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

ALTER RESOURCE (state)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

ALTER SITE (state)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

ALTER SITE (AUTO PFILE)

Format

Command Parameters

Usage Notes

Command Examples

Example 1

Example 2

CONNECT

Format

Command Parameters

Usage Notes

Command Examples

Example 1

Example 2

CREATE CONFIGURATION

Format

Command Parameters

Usage Notes

Command Examples

Example 1

CREATE SITE

Format

Command Parameters

Usage Notes

Command Examples

Example 1

DISABLE CONFIGURATION

Format

Command Parameters

Usage Notes

Command Examples

Example 1

DISABLE RESOURCE

Format

Command Parameters

Usage Notes

Command Examples

Example 1

DISABLE SITE

Format

7
Data Guard Command-Line Interface Reference