Skip Headers

Orac le® Data Guard Broker
10g Release 1 (10.1)
Part Number B10822-01
Go to Documentation Home
Home 		Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Inde x		 G o to Master Index
Master Index		 Go to Feedback page
Feedback
Go to previous page
Previous		 Go to next page
Next
 View PDF

7 Data Guard Command-Line Interface Refer ence

The Data Guard command-line interface enables you to manage a Data Guard broker configuration and its databases d irectly from the command line, or from batch programs or scripts. You can use the Data Guard c ommand-line interface as an alternative to the Data Guard graphical user interface (GUI), integrated with Oracle Enterprise Manager, 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 Oracle is installed:

% DGMGRL
DGMGRL for Solaris:  Version 10.1

Copyright (c) 2000, 2003 Oracle. All
rights reserved.

Welcome to DGMGRL, type "help" for information.
DGMGRL>

7. 1.1 DGMGRL Optional Parameters

You can supply optional parameters on the c ommand line to indicate how you want the Data Guard command-line interface to display output such as command prompts, banners, and messages.

Additionally, a s ingle command mode is available. In this mode, DGMGRL executes one command and exits upon the completion of the command. The exit cod e 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>] ]

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

  • <options> can be one of the following choices:

    • -echo

      Displays com mand 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.

  • <logon> is:

    • username/password [@connect-identifier]

      The username and password with which you wa nt to connect to the database. The connect-identifier is a fully specified connect descriptor or a name to be resolved b y 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 db"

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

7.1.2 DGMGRL Command Format and Paramet ers

The DGMGRL commands allow you to create and maintain one broker configuration at a time. A broker configuration ca n 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 7-1. Each command and its associated parameters are described in detail in later sections of this chapter.

Table 7-1 Summary of DGMGRL Comman ds

EDIT INSTANCE (AUTO PFILE)
 < tr align="left" valign="top"> < /table>

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 long er managed by the broker.
DISABLE DATABASE
 Disables broker management of the named standby database.
EDIT CONFIGURATION (Prot ection Mode)
 Changes the current protection mode setting for the broker con figuration.
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.
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.
EXIT
 Exits the Data Guard command-line in terface.
FAILOVER
 Performs a database failover operation in which the standby database, to which th e CLI 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.
REMOVE CONFIGURATION
 Removes the broker configuration including all of its database profiles from the broker c onfiguration file.
REMOV E DATABASE
 Removes the specified standby database profile from the broker configuration.
REMOVE IN STANCE
 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 currentl y running Oracle database.
STARTUP
 Starts an Oracle instance with the same options as SQL*Plus, inc luding mounting and opening a database.
SWITCHOVER
 Performs a switchover operation in which the cur rent primary database becomes a standby database, and the specified standby database becomes the primary database.

N ote:

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

< a id="sthref872" name="sthref872">

7.1.3 DGMGRL Command Usage Notes

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

  • The DG_BROKER_START dynamic initialization parameter is set to true.

  • To enable br oker 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_DG MGRL.db_domain. See Chapter 6 for additional information.

  • The net service name, if used, must be resolvable from any of the hosts in the configuration.



  • You must have SYS DBA 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 pas sword for SYS needs to be identical on all databases, and all databases should use the remote password file (either SHARED or EXCLUSI VE).


    • See Also:

    Section 1.7.5 for i nformation about the listener prerequisites. Chapter 6 for more information about preparing and starti ng Oracle Data Guard broker. See the Oracle Database Administrat or's Guide for more information about setting up the network files and listener on the standby database.

    See Also:

    Oracle Data Guard Concepts and Administration for info rmation about passwords

  • A semicolon i s 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 disti nctive.

  • 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 operatio ns on a broker configuration may require that one or more databases be shut down and restarted. In most cases, the CLI will automatic ally shut down and restart a given database for you if the following are true:

    • The instance- name is the SID (this applies for the GUI as well as the CLI).

    • 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 CONNEC T command was used to connect to another database. Thus, the remote password file for the database must contain the username a nd password given in the last CONNECT command.


      See Also:

      Oracle Database Administrator's Gu ide for more information about setting up remote password files and the default location of the PFILE and SPFILE initializat ion 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;
Con
nected.

Example 2

This example demonstrates how t o connect to the Data Guard (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 o r QUIT command at the DGMGRL command prompt. For example:

DGMGRL> EXIT;

ADD DATA BASE

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

Format

ADD DATABASE database-name AS

CONNECT IDENTIFI ER IS connect-identifier

MAINTAINED AS {PHYSICAL | LOGICAL};

Command Parameters

database-name

The name that will be used by the broker to refer to this s tandby 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

  • You must connect to the primary database to issue this command.

  • The broker uses the specified connect-identifier to communicate with the specified database from other databases. Therefore, you must ensure that the connect-identifier can be used to address the specified database from all databases in your co nfiguration. For example, if you use tnsnames.ora files to resolve the connect-identifier, you must ensure it will be re solved to the same connect descriptor at all tnsnames.ora files and the resulting connect descriptor can be used to reach the databas e specified in this ADD DATABASE command.

  • If the connection cannot be made, the broker does not add the new database to the configuration.

Command Example

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.

< p>Format

CONNECT username/password [@connect-identifier];

Command Parameters

username/password

Represents the username and pass word 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.

< a id="sthref895" name="sthref895">

Usage Notes

  • The username and password must be valid for the database to which you are trying to connect. The use rname you specify must have the SYSDBA privilege. You do not have to include AS SYSDBA on the CONNECT comma nd because SYSDBA is the default setting for this command.

  • If the CONNECT command returns a n error, check to see that you specified a valid connect-identifier.

Command Examples


Example 1

This example connects to the default database on the local syst em.

DGMGRL> CONNECT sys/change_on_install;
Connected.

Example 2

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

DGMGRL> CONNECT sys/change_on_install@prmy;
Connected.

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 na mes 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-inse nsitive) 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

  • A bro ker configuration is a named collection of one or more databases that you want to manage as a group. You must specify a value for eac h of the command parameters. There are no default values.

  • You must connect to the primary database to is sue this command.

  • The broker uses the specified connect-identifier to communicate with the specified database from other databases. Therefore, you must ensure that the connect-identifier can be used to address t he specified database from all databases in your configuration. For example, if you use tnsnames.ora files to resolve the conne ct-identifier, you must ensure it will be resolved to the same connect descriptor at all tnsnames.ora files and the resulting connect descriptor can be used to reach the primary database specified in this CREATE CONFIGURATION command.

    • To add standby databases after you create the broker configuration, use the ADD DATABASE co mmand.

Co mmand Example

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

DGMGRL> CREATE CONFIGURATION 'DRSolution' AS
> PRI
MARY DATABASE IS 'North_Sales'
> CONNECT IDENTIFIER IS North_Sales.foo.com;
Configuration "DRSolution" created with primary databa
se "North_Sales".

DISABLE CONFIGURATION

Disables br oker 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

  • A disabled configuration and all of its constituent databases are no longer managed by the broker.

  • < p>The only way to disable broker management of the primary database is to use the DISABLE CONFIGURATION command.

  • This command does not remove the broker configuration. See the REMOVE CONFIGURATION comma nd for more information about removing the configuration.

  • You can edit database properties and modify th e configuration's protection mode while the configuration is disabled. However, any changes made to properties or to the protection m ode will not take effect until the configuration is enabled.

Command Example

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 dis allowed 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

  • You ca nnot specify the name of a primary database.

  • Use the DISABLE CONFIGURATION command to disab le the primary and all standby databases.

  • If the sole standby database is disabled, you have no failover option. This standby database is not viable for failover until it is reenabled.

Command Example

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

DGMGRL> DISABLE DATABASE 'DR_Sales';
Di
sabled.

EDIT CONFIGURATION (Protection Mode)

Edits the current protectio n 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:


MAXPROTECTIO N
MAXAVAILABILITY
MAXPERFORMANCE

< strong>Usage Notes

  • Before you use the EDIT CONFIGURATION command to set the protection mode to either the MAXPROTECTION or MAXAVAIL ABILITY mode, ensure that standby redo log files are configured on a standby database.

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

    Protection Mode Log Transport Mode Standby Redo Log Files Needed?
    MAXPROTECTION SYNC Yes
    MAXAVAILABILITY SYNC Yes
    MAXPERFORMANC E ARCH or ASYNC Yes for ASYNC

    The default protectio n mode for the configuration is MAXPERFORMANCE.


    See Also:

    Chapter 3 for more information about the protection modes and lo g transport modes

  • After you change th e protection mode, the primary database will automatically restart, if necessary.

  • Use the SHOW CON FIGURATION command to display the current protection mode for the configuration.

    DGMGRL> SHOW
 CONFIGURATION;

Configuration
  Name:            DRSolution
  Enabled:         YES
Protection Mode: MaxPerformance
  Databases:
    North_Sales - Primary database
    DR_Sales    - Physical standby database

Current status for "DRSolution":
SUCCESS

If broker management of the configuration is disabled when you enter the EDIT CONFIGURATION comma nd, 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

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 log transport mode 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 shutd
own of instance "sales1" on database "North_Sales".
Shutting down instance "sales"...
Database closed.
Database dismounted.
ORACLE in
stance shut down.
Operation requires startup of instance "sales1" on database "North_Sales".
Starting instance "sales1"...
ORACLE ins
tance started.
Database mounted.

The broker automatically stops and restarts the primary database.

EDIT DATABASE (Prop erty)

Changes the value of a property fo r 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 3 and Chapter 8 for information about properties.

value

The ne w 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 br oker for the named database. An attempt to use this command to change a per-instance property when the broker knows of multiple insta nces of the database will be rejected. It is recommended to only use EDIT INSTANCE (property) to change the value of a p er-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 datab ase.

DGMGRL> EDIT DATABASE 'DR_Sales' SET PROPERTY 
> 'StandbyArchiveLocation'='/archfs/arch/';
P
roperty "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 ch ange should be applied.

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

Failed.

  • This command can only be done wh en broker management of the database that you are renaming is disabled.

    • Command Example

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

    DGMGRL> EDIT DATABASE 'DR_Sales_typo' RENAME TO 'DR_Sales';
Succeede
d.

DGMGRL> ENABLE DATABASE 'DR_Sales';
Enabled.

    EDIT DATABASE (State)

    Changes the state of the specified database.

    < strong>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 d atabase 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)
    < code>OFFLINE
    instance-name

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

    Usage Notes

    • If the target state is ONLINE and this database is currently in the standby role, the optional WITH AP PLY INSTANCE clause specifies which instance will become the apply instance.

    • If the target state is not ONLINE or if the database is currently in the primary role, the WITH APPLY INSTANCE clause is ignore d even if it is specified.

    • All instances of a RAC database are affected by this database state change.

    Command Ex ample

    The following example shows how to change the state of a database.

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

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 dismo
unted.
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 (SI D) 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 s tart that instance, you must start it manually. If you do not specify SET AUTO PFILE for the instance, the automatic sta rtup operation looks for the initialization parameter file at the default location.

    Usage Notes

    • T he instance-name can be unique across the configuration. If instance-name is not unique, you must specify both the database-name and the instance-name to fully identify the insta nce.

    • SET AUTO PFILE is valid only for the duration of the current DGMGRL session. You must specify SET AUTO PFILE again if you quit and reenter DGMGRL.

    < strong>Command Example

    The following example shows h ow 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-na me

    [ON DATABASE database-name]

    SET PROPERTY property-name = value;

    Command Parameters

    < strong>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 3 and Chapter 8 for information about properties.

    value

    The new value for the property.

    Usage Notes

    • The instance-name can be unique across the configuration. If instance-name is not unique, you must specify both the databa se-name and the instance-name to fully identify the instance.

    • This com mand cannot be used to change a database-specific property.

    Command Examples


    Example 1

    Edit an instance level property.

    DGMGRL> EDIT INSTAN
CE '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 PROPE
RTY '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< /p>

    ENABLE CONFIGURATION;

    Command Parameters

    None.

    Usage Notes

    • Use this command to enable broker management of the primary database.

    • By default, broker man agement of the configuration's databases is enabled in the ONLINE state with log transport services turned on at the pri mary database and log apply services turned on at the standby databases. You can change the state of any database using the EDIT DATABASE (State) command, but not when the database or the entire configuration is disabled.

    • Use the SHOW CONFIGURATION command to display information about the configuration.

    Command Example

    The following example enables management of a broker configuration.

    DGMGRL> ENABLE CONFIGU
RATION;
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 t o be re-created until it has been re-created as described in Section 4.2.5.

    Format

    ENABLE DATABASE database-name;

    Command Parameter

    database-name

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

    Usage Notes

    • A standby database may have been disabled by the broker as a consequence of a prior failover or switchover operation. Recovery of the database is required as described in Section 4.2.5 before this command should be issued.

    • By default, broker management of the standby database is enabled in the ONLINE state with log apply services enabled. You can change the st ate of the standby database using the EDIT DATABASE (State) command, but only when the database is enabled.

    • Use the SHOW DATABASE command to display information about the database.

    • For a RAC database, only one instance is required to be started and mounted for this command to succeed.

    Command Example

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

    DGMGRL> ENABLE DATABASE 'DR_Sales';
Enabled.

    EXIT

    Exits (quits) the command-line interface.

    Format

    EXIT;

    < a id="sthref987" name="sthref987">

    Command Parameters

    None.

    Usage Notes

    • This command has the same effect as the QUIT comm and.

    • A database connection is not required to execute this command. However, if you are connected, this command breaks the connection.

    Command Example

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

    DGMGRL> EXIT;
    < hr noshade="noshade" size="3" />

    FAILOVER

    A failover operation changes the named standby database into the role of a primary database.


    Note:

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

    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

    • To be considered a viable candidate for the failover operation, the specified standby database must be enabled before the primary fails. However, an enabled standby database that was taken offline can be a candidate for the failover ope ration. In this case, restart the standby database using the CLI STARTUP command, then issue the FAILOVER c ommand.

    • The failover operates on the specified database. Thus, the failover changes one of the standby d atabases into the role of a primary database. Any other standby databases not involved in the failover remain in the standby role.

    • Before you issue the FAILOVER command, verify that you are connected to the standby database that will become the new primary database. If necessary, issue a CONNECT command to connect to the standby data base.

    • If the FAILOVER command is issued without any options, the standby database chosen as the failover target recovers all log files received before changing to the primary role.

    • If the standby database that you want to fail over to the primary role is a RAC database, the broker will shut down all of the instances except the apply instance before it continues the failover operation. The broker will restart instances that it shut down prior to the failover . See Section 4.2 for details.

    • If the standby database that is transitioning into the role of primary database is a physical standby database, then the database instance (or instances) will be restarted after the failover completes. If the database is a logical standby database, the database instance (or instances) does not need to be restarted.

    • If t he broker configuration is in either MAXPROTECTION or MAXAVAILABILITY protection mode, the failover operati on will force the protection mode to be MAXPERFORMANCE. The log transport mode settings are unaffected. You need to rest ore the desired protection mode for the resulting configuration after the failover operation.

    • If the FAILOVER command is issued with the IMMEDIATE option, no attempt is made to recover available log files. This option more likely results in lost application data even when standby redo log files are configured on the standby database. Addition ally, any remaining standby databases in the configuration cannot function as such until they are re-created.

    • The original primary database can only participate in the configuration as a standby database after it is re-created.


      Caution:

      You should shut down the original primary database if it still has any active instances running.


      See Also:

      Section 4.2.5 about re-creating the original primary database so that it could serve as a standby database to the p rimary database

    Command Examples

    The following exa mple 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_sales
1" on database "DR_Sales".
Shutting down instance "dr_sales1"...
ORA-01109: database not open
Database dismounted.
ORACLE instance sh
ut 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 co mmand-line interface.

    Format

    HELP [topic];

    Command Parameter

    topic

    The topic for which you want to di splay 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
    REMO VE
    SHOW
    SHUTDOWN
    STARTUP
    SWITCHOVER

    Usage Note

    • 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 description and syntax for a
given command

Syntax:

  HELP [<command>];

DGMGRL> HELP CONNECT;

Connect to an Oracle instance

Syntax:

  CONNECT <us
ername>/<password>[@<connect identifier>]

    Example 2

    The following example gets help on the EDIT commands.

    DGMGRL> HELP ED
IT

Edit a configuration, database or instance

Syntax:

  EDIT CONFIGURATION SET PROTECTION MODE AS
    {MaxProtection|MaxAvailabili
ty|MaxPerformance};

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

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

  EDIT DATABASE <database name> SET STATE = <state>
    [WITH APPL
Y 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 PROPER
TY <property name> = <value>;

    QUIT

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

    Format

    QUIT;< /font>

    Command Pa rameters

    None.

    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 Example

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

    DGMGRL> QUIT;

    REMOVE CONFIGURATION

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


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


    Format

    REMOVE CONFIGURATION [ PRESERVE DESTINATIONS ];

    Command Parameters

    None.

    Usage Notes

    • When you remove a broker configuration, management of all of the databases asso ciated with that configuration is disabled.

    • By default, the command removes the corresponding broker set tings of the LOG_ARCHIVE_DEST_n initialization parameter on the primary database and the LOG _ARCHIVE_CONFIG initialization parameters on all databases in the configuration. To preserve these settings, use the PRE SERVE DESTINATIONS option.

    • This command does not remove or affect the actual primary or standby d atabase instances, databases, datafiles, control files, initialization parameter files, server parameter files, or log files of the u nderlying Data Guard configuration.

    Command Example

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

    DGMGRL> REMOVE CONFIGURATION;
Removed configuration.

DGMGRL> SHO
W CONFIGURATION;
Error: ORA-16532: Data Guard configuration does not exist

    REMOVE DATABASE

    Removes the specified standb y 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 < font style="font-family: Arial, Helvetica" face="Helvetica, Arial">database-name [ PRESERVE DESTINATIONS ];

    Command Parameter

    database-name

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

    Usage Note

    • An error is returned if you specify the name of the primary database in the broker configuration.

    • By default, the command removed the corresponding broker settings of the LOG_ARCHIVE_DEST_n initi alization parameter on the primary database and the LOG_ARCHIVE_CONFIG initialization parameter on all databases in the configuration. To preserve these settings, use the PRESERVE DESTINATIONS option.

    Command Example

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

    DGMGRL> SHOW CONFIG
URATION;

Configuration
  Name:            DRSolution
  Enabled:         YES
  Protection Mode: MaxPerformance
  Databases:
    North
_Sales - Primary database
    DR_Sales    - Physical standby database

Current status for "DRSolution":
SUCCESS

DGMGRL> REMOVE DA
TABASE 'DR_Sales';
Removed database "DR_Sales" from the configuration.

DGMGRL> SHOW CONFIGURATION;

Configuration
  Name:
    DRSolution
  Enabled:         YES
  Protection Mode: MaxPerformance
  Databases:
    North_Sales - Primary database

Current stat
us for "DRSolution":
SUCCESS

    REMOVE INSTANCE

    Removes an instance from an existing database profile in the broker confi guration.

    Format< /font>

    REMOVE INSTANCE instance-name

    [ON DATABASE database-name];

    Command Parameters

    instance-name

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

    database-name

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

    Usage Notes

  • In a RAC database, the broker automatically adds started instances into the corresponding database profile. Ho wever, the broker may not automatically remove instances from the database profile. The REMOVE INSTANCE command can be u sed to manually remove any instance that no longer exists from the database profile.

  • The insta nce-name can be unique across the configuration. If instance-name is not unique, you must specify b oth the database-name and the instance-name to fully identify the instance.

  • This command is rejected for an instance that is currently active in the broker configuration.

  • This command is rejected if this is the only instance currently associated with a database profile.

    • Command Example

    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".
    < /a>

    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.

    Format

    SHOW CONFIGURATION;

    Command P arameters

    None.

    Usage Notes

    None.

    Command Examples

    The following example provides a summary of the DRSolution configuration.

    DGMGRL> SHOW CONFIGURATION;

Configuration
  Name:
  DRSolution
  Enabled:         YES
  Protection Mode: MaxPerformance
  Databases:
    North_Sales - Primary database
    DR_Sales
 - Physical standby database

Current status for "DRSolution":
SUCCESS

    SHOW DATABASE

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

    Format< /font>

    SHOW DATABASE [VERBOSE] database-name [proper ty-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 displ ay a value.


    < /table>

    Usage Notes

    • The SHOW DATABASE com mand shows a brief summary of the database. SHOW DATABASE VERBOSE shows properties of the database in addition to the br ief summary. They both show the status of the database.

    • The SHOW DATABASE VERBOSE command s hows database-specific properties and instance-specific properties. For a non-RAC database, the values of the instance-specific prope rties are those of the only instance of the database. For a RAC database, the values of the instance-specific properties will not be shown, although the property names are still listed. To see the instance-specific values of these properties, use the SHOW INST ANCE command.

    • The properties that the SHOW DATABASE VERBOSE command shows depend on the database role and the configuration composition:

      • For the primary database, properties specific to physical standby databases are shown only if there is at least one physical standby database in the configuration. The properties spe cific to logical standby databases are shown only if there is at least one logical standby database in the configuration.

        • For physical standby databases, properties specific to logical standby databases are not shown.

      • For logical standby databases, properties specific to physical standby databases are not shown.

    • This command is rejected if you use SHOW DATABASE property-name command to show an instance-specific property in a RAC database.

    Command Examples


    Example 1

    Shows database information in an abbreviated format.

    DGMGRL> SH
OW DATABASE 'DR_Sales';

Database
  Name:            DR_Sales
  Role:            PHYSICAL STANDBY
  Enabled:         YES
  Intended S
tate:  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
  I
ntended State:  ONLINE
  Instance(s):
    sales1

  Properties:
    InitialConnectIdentifier        = 'North_Sales.foo.com'
    LogXp
tMode                      = 'ARCH'
    Dependency                      = ''
    DelayMins                       = '0'
    Binding
                      = 'OPTIONAL'
    MaxFailure                      = '0'
    ReopenSecs                      = '300'
    AsyncBlo
cks                     = '2048'
    NetTimeout                      = '30'
    LogShipping                     = 'ON'
    PreferredA
pplyInstance          = ''
    ApplyInstanceTimeout            = '120'
    RealTimeApply                   = 'OFF'
    ApplyNoDelay
                  = 'NO'
    ApplyNext                       = '0'
    ApplyParallel                   = 'AUTO'
    StandbyFileManage
ment           = 'AUTO'
    ArchiveLagTarget                = '0'
    LogArchiveMaxProcesses          = '5'
    LogArchiveMinSucceedD
est        = '1'
    DbFileNameConvert               = 'dbs/s2t, dbs/t'
    LogFileNameConvert              = 'dbs/s2t, dbs/t'
    St
atusReport                    = '(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))'
    AlternateLocation               = ''
    StandbyArchiveLocation          = '/archfs/arch/'
    LogArchiveTrace                 = '4095'
    LogArchiveFormat
  = 'r_%t_%s_%r_%d.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 3 and Chapter 8 for information about properties.

    See Also:

    Chap ter 3 and Chapter 8 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

    • The SHOW INSTANCE command shows a brief summary of the instance. SHOW INSTANCE VERBO SE shows properties of the instance in addition to the brief summary. They both show the status of the instance.

    • The SHOW INSTANCE VERBOSE command only shows instance-specific properties.

    • The properties that the SHOW INSTANCE VERBOSE command shows depend on the database role and the configuration compositio n:

      • For instances of the primary database, properties specific to physical standby instances are shown only if there is at least one physical standby database in the configuration. The properties specific to logical standby instances ar e shown only if there is at least one logical standby database in the configuration.

      • For instances of physical standby databases, properties specific to logical standby instances are not shown.

      • For instan ces of logical standby databases, properties specific to physical standby instances are not shown.

    • The instance-name can be unique across the configuration. If instance-name is not un ique, you must specify both the database-name and the instance-name to fully identify the instance .

    Comma nd Example


    Example 1

    The follo wing 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                 = '4095'
    LogArchiveFormat
             = 'r_%d_%t_%s_%r.arc'
    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

    • Using the SHUTDOWN command with no arguments is equivalent to using the SHUTDOWN NORMAL command.

    • The following list describes the options to the S HUTDOWN command:

      • ABORT

        Proceeds with the fastest possible shutdown of the d atabase without waiting for calls to complete or for users to disconnect from the database. Uncommitted transactions are not rolled b ack. Client SQL statements being processed are terminated. All users connected to the database are implicitly disconnected, and the n ext 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 data base. 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. The p rocess waits for users to disconnect from the database. Further connections are prohibited. The database is closed and dismounted. Th e instance is shut down, and no instance recovery is required on the next database startup.

    Command Example

    The following command shuts down the database in normal mode.

    DGMGRL > SHUTDOWN;

Database closed.

Database dismounted. 
Oracle instance shut down.

    STARTUP

    Starts an Oracle datab ase instance with any of the following options:

    • FORCE: shuts down the current Oracle instan ce in the SHUTDOWN ABORT mode before restarting it.

    • RESTRICT: all ows 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 start ed.

    • MOUNT: mounts the specified database without opening it. If you do not specify a databa se name, the database name is taken from the initialization parameter DB_NAME.

    • OPEN: mounts and opens the specified database.

    • NOMOUNT: starts the specified database inst ance without mounting the database.

    Format

    STARTUP

    [FORCE]

    [RESTRICT]

    [PFILE=filename]

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

    Command Parameters

    filename

    The name of the initializatio n 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.

    db_name

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

    open-options

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


    READ ONLY
    READ WRITE

    Usage Notes

    • Using the STARTUP command with no arguments is equivalent to using the STARTUP OPEN command.

    • If you do not use the FORCE clause when you use the STARTUP command and the current database instance is running, an error results. The FORCE clause is useful when you are debu gging or when error conditions are occurring. Otherwise, it should not be used.

    • Use the RESTRICT clause to allow only Oracle users with the RESTRICTED SESSION system privilege to connect to the instance. Later, you can use the ALTER SYSTEM command through SQL*Plus to disable the restricted session feature.

    • If you do not use the PFILE clause to specify the initialization parameter file, the STARTUP command uses the default server parameter file, if it exists. Otherwise, the STARTUP command uses the default initialization par ameter file. The default files are platform specific.

      See your operating system-specific documentation for more information ab out the default parameter files.

    • Use the MOUNT clause to mount a primary database or a logi cal standby database without opening it. If you do not specify a database name, the database name is taken from the initialization pa rameter DB_NAME.

    • Use the OPEN clause to mount and open the specified database.

    • The NOMOUNT clause starts the database instance without mounting the database. You cannot use the NOMOUNT clause 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 data base in exclusive mode, and opens the database.

    DGMGRL> STARTUP;
DGMGRL> STARTUP OPEN database;
<
/pre>


    Example 2
    

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

    DGMGRL > STARTUP FORCE RESTRICT NOMOUNT;

    


    Example 3
    

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

    DGMGRL > STARTUP PFILE=testparm NOMOUNT;

    


    Example 4
    

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

    DGMGRL> STARTUP MOUNT;

    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

    • The broker verifies that the primary and standby databases are in the following states befo re starting the switchover:

      • The primary database must be enabled and ONLINE, with log tra nsport services started.

      • The standby database must be enabled and ONLINE, with log apply services started.

    • The broker allows the switchover to proceed as long as there are no log tran sport services errors for the standby database that you selected to participate in the switchover. However, errors occurring for any other standby database not involved in the switchover will not prevent the switchover from proceeding.

    • I f the broker configuration is in either MAXPROTECTION or MAXAVAILABILITY mode, the switchover maintains the protection mode even after the operation (see Section 4.1.1). The switchover will not be all owed if the mode cannot be maintained because the target standby database of the switchover was the only standby that satisfied the p rotection mode requirement.

    • If the standby database that is assuming the primary role is a physical stan dby database, then both the primary and standby databases will be restarted after the switch over completes. If the standby database is a logical standby database, then neither the primary database nor the logical standby data base is restarted.

    • If the standby database that is assuming the primary role is a physical standby datab ase, then the original primary becomes a physical standby database. Otherwise, it becomes a logical standby database.

    • If the primary database is a RAC database, the broker will keep only one instance running and shut down all other insta nces before it continues the switchover. If the standby database you want to switch to the primary role is a RAC database, the broker will shut down all instances except the apply instance before it continues the switchover. The broker will restart instances that it shut down prior to the switchover. See Section 4.1 for details.

    • If the standby database that is assuming the primary role is a logical standby database and there are physical standby databases in the configuration, after the switchover, the physical standby databases will not be able to participate as such until they are re-cre ated.


      Caution:

      For this r eason, Oracle generally recommends that you specify your physical standby database for switchover instead of your logical standby dat abase. If you must switch over to your logical standby database, see Section 4.2.5 to re-crea te your physical standby database.

    Command Examples


    Example 1

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

    D
GMGRL> SWITCHOVER TO "DR_Sales";
Performing switchover NOW. Please wait...
Operation requires shutdown of instance "sales1" on dat
abase "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: databas
e 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 datab
ase "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 u sing operating system authentication, you can use any username and password to connect. However, the CLI may not be able to shut down and start up the primary and standby database automatically because it cannot remotely authenticate itself.

    The following exa mple shows a switchover that succeeded but returns an error because the CLI cannot shut down and start up the primary and standby dat abases.

    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-01
017: invalid username/password; logon denied

You are no longer connected to ORACLE
Please connect again.
Unable to shut down instanc
e "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 mu
st start instance "sales1" manually.
Operation requires startup of instance "dr_sales1" on database "DR_Sales".
You must start instan
ce "dr_sales1" manually.
Switchover succeeded. New primary is "DR_Sales"

    Note:

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

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

    Go to previous page
    Previous    		 Go to next page
    Next
    		 Oracle
    Copyright © 2000, 2003 Oracle Corporation
    All Rights Reserved.
    Go to Documentation Home
    Home    		 Go to Book List
    Book L ist    		 Go to Table of Contents
    Contents    		 Go to Index
    Index    		 Go to Master Index
    Master Index    		 Go to Feedback page
    Feedback