HOTSTANDBY

Note You cannot use HotStandby with the grid feature so you cannot use the 'global' option with this command.

Runs commands that are available with HotStandby. See also, commands that are available with the High Availability Controller (HACONTROLLER).

▪ cominfo: Returns the connect string used to connect to the other server. This is usually the value of the HotStandby.Connect parameter, but it might also have been set with the command:

ADMIN COMMAND 'hsb parameter connect connect_string';

You can use this information in an application to connect to other servers.

▪ connect: If the connection between the primary and secondary servers is broken or has not yet been established, this command connects the primary server to the secondary server and starts HotStandby replication. This command is always needed to connect the servers since there is no automatic mechanism for connecting between servers. After a successful connect, the state of the primary server is automatically set from PRIMARY ALONE to PRIMARY ACTIVE. If unsuccessful, the state remains PRIMARY ALONE.

This command can be executed on either the primary or the secondary server.

Note When you execute this command, if the primary server and secondary server are connected, but the transaction log is not yet fully copied to the secondary server, the following message is displayed: Catchup is active.

You can use the hsb copy command to initially copy the secondary database from the primary server. This command copies the database into a directory that is local to the primary computer (and also local to the secondary computer). After the copy is completed, you can start the secondary server. After you connect the primary server to the secondary server, the primary server automatically brings the secondary server up-to-date by copying the transaction log to the secondary server.

You can also use this command to synchronize the primary database with a secondary database (when the secondary server has been offline for a considerable period of time) , see Synchronizing primary and secondary servers.

If the optional directory_name is specified, the database files are copied to that directory; otherwise they are copied to the directory that is specified with the copydirectory parameter in the [Hotstandby] section of the solid.ini configuration file. Because the hsb copy command does not copy the solid.ini configuration file or log files, it is recommended that you make this directory different from the normal backup directory.

The hsb copy command can be executed only if the primary is in PRIMARY ALONE state. During and after the command, the server remains in PRIMARY ALONE state. After the command has been completed, you can start the secondary server and connect the two servers.

▪ disconnect: This tells the server to disconnect gracefully from the other member of the HSB pair. A typical reason to use this command is to disconnect the servers before upgrading one of them. (The other server can be set to PRIMARY ALONE state so that it can continue responding to client requests.)

This command normally causes both servers to go into an "Alone" mode; that is, the primary server switches from PRIMARY ACTIVE to PRIMARY ALONE, while the secondary server switches from SECONDARY ACTIVE to SECONDARY ALONE.

You can execute this command on either the primary or the secondary server.

Note Using the shutdown command ADMIN COMMAND 'shutdown' causes the server to do a controlled disconnect before it shuts down. If the secondary server is shut down (and disconnects), the primary server automatically switches to PRIMARY ALONE state.

▪ logpos: This commands returns the log operation ID and the server role (PRIMARY, SECONDARY, STANDALONE) at the time of the last operation.

The following output is typical:

ADMIN COMMAND 'hsb logpos';
RC TEXT
-- ----
0 000000000000000000871:PRIMARY

This command can be used to determine which of two servers should become the primary server. For example, after a failure where both databases have failed, it might not be obvious which server should be made the primary server. (The server that was the primary server before the connection was broken is not necessarily the server that should become the primary server now.)

In principle, the server that has the greater value for the log operation ID has accepted more transactions, and thus should become the primary server. However, if you have made updates to both servers after the HSB connection has failed, the log operation ID values can no longer be compared reliably.

For more information about how to use this command, see Choosing which server to make primary.

▪ netcopy: This command can be used copy the primary database or diskless in-memory data to a secondary server. The database files are copied through the network link, using the connection defined with the HotStandby.Connect parameter in the solid.ini file on the primary server.

You might want to use this command, for example, to synchronize a primary database with a secondary database that has been offline for a long time. You can also use hsb netcopy to replace a corrupt secondary database, to set up a secondary database for a new HotStandby configuration.

The primary server must be in PRIMARY ALONE state to run this command.

After the command has completed (successfully or unsuccessfully), the primary server remains in the PRIMARY ALONE state. If the copy is completed successfully, the secondary server is automatically switched to SECONDARY ALONE state.

Note The hsb netcopy command is usually followed by the hsb connect command to connect the primary and secondary servers. After the primary server is connected to the secondary server, the primary server automatically brings the secondary server up-to-date by copying the transaction log.

For more details on using hsb netcopy, see Synchronizing primary and secondary servers and Copying a primary database to a secondary database over the network.

Note This option is deprecated. Use the following command instead:

ADMIN COMMAND 'parameter hotstandby.param_name = param_value';

▪ set primary alone: Sets the primary server to the PRIMARY ALONE state unconditionally. This command can be run if the server is currently in one of the following states: PRIMARY ACTIVE, SECONDARY ACTIVE, SECONDARY ALONE and STANDALONE.

This command can be used to implement fast failovers. When the secondary server is in the SECONDARY ACTIVE state, the server will not make any attempt to communicate with the primary server, having received this command. Instead, it will immediately switch to the PRIMARY ALONE state. This behavior can be used in cases when the information about the primary server failure reaches the High Availability Controller (HAC) before the secondary server has detected the failure (the delay is dictated by the PingTimeout and PingInterval parameters).

However, if it happens (for example, because of incorrect failure detection) that the primary server is "alive" and in the PRIMARY ACTIVE state when this command is executed in the secondary server, the primary server is automatically switched to PRIMARY UNCERTAIN state. The primary server can then be switched to the SECONDARY ALONE state and reconnected without any loss of transactions.

In the PRIMARY ALONE state, the connection to the secondary server is broken, but this state allows the primary server to run with continuous updates to the transaction log. The PRIMARY ALONE state persists until the primary server is shut down, a connection is successfully made to the secondary server, or the server runs out of space for the transaction log.

When you set a server to PRIMARY ALONE state, it does not automatically make any attempt to re-establish connections with the other server.

Note Before executing this command on a server, make sure that the other server in the pair is not already in PRIMARY ALONE state (or STANDALONE state). This is to avoid dual primaries – see Network partitions and dual primary servers.

See also, the command 'hsb switch primary'.

– PRIMARY ACTIVE, if the connected server is a normal primary server. In this state, transactions on the primary server are sent to the secondary server.

– STANDALONE, indicating that the primary server accepts transactions and stores them in the database, but it does not store the transactions to forward them to the secondary server.

– PRIMARY UNCERTAIN, if the primary server has a broken connection to the secondary server and has not yet been switched to another state, such as PRIMARY ALONE. Only read-only transactions can be executed in the primary server.

– PRIMARY ALONE, if the primary server is working by itself. The connection to the secondary server is broken, but transactions are accepted and stored in the primary server transaction log so that they can be forwarded to the secondary server.

– SECONDARY ACTIVE, if the connected server is a normal secondary server. This means the server receives and applies transactions from the primary server.

If ADMIN COMMAND 'hsb state' is run on a server that is not configured for HSB, the following error message is returned: 14527: This is a non-HotStandby Server.

This command returns the same information as the SQL function: HOTSTANDBY_STATE. See Using the HOTSTANDBY_STATE function for details on this function.

See Server state transitions for an overview of HSB state transitions that occur while performing administrative and troubleshooting operations.

▪ status option: Returns the HSB status information of the last successfully started operation where option is one of the following values:

– catchup: Indicates whether or not the server is doing catchup, that is, when the secondary server reads the primary server transaction log and applies the changes.

– CONNECTING - The primary server and secondary server are connecting to each other. This information is returned from both the primary and secondary servers.

– CATCHUP - The primary server is connected to the secondary server, but the primary HotStandby database log is not fully copied to the secondary server. This information is returned from both the primary and secondary servers.

– BROKEN - Connection between the primary and secondary server is broken. This information is returned from both the primary and secondary servers.

Note This command returns the same information as the SQL function HOTSTANDBY_CONNECTSTATUS, see Using the HOTSTANDBY_CONNECTSTATUS function.

– copy: Checks the result of the last hsb copy or hsb netcopy command. This status command always uses the keyword copy, even if you are checking the result of an hsb netcopy rather than an hsb copy.

▪ switch primary: Switches the database server to a PRIMARY state. The command starts a switch process, which can be monitored using command hsb status switch.

If the servers are connected at the time that you execute this command, the servers simply reverse states — that is, the old primary server switches from PRIMARY ACTIVE to SECONDARY ACTIVE, and the old secondary server switches from SECONDARY ACTIVE to PRIMARY ACTIVE.

If the servers are not connected and the server is in SECONDARY ALONE state, when you switch the server to PRIMARY, the server switches to PRIMARY ALONE state. The new primary server will not automatically try to connect to the other server and switch to PRIMARY ACTIVE state.

Because the command is available both in the SECONDARY ACTIVE and SECONDARY ALONE states, it can be used to perform failovers. However, because the server always attempts to communicate with the primary server, the network timeout might be involved. Thus, this method is slower than using the hsb set primary alone command. However, this method is more likely to prevent the occurrence of dual primary servers.

▪ switch secondary: Switches the database to a SECONDARY state. All active write transactions are terminated.

If the connected database server is a primary server, it becomes a secondary server. If the old secondary server is available, the old secondary server is switched to a PRIMARY state.

Note If the hsb switch secondary command is run inside an open transaction (in Windows environments, after the transaction has started and before you execute the COMMIT statement), then, when you execute the COMMIT statement, the statement fails with an error: Replicated transaction is aborted. All transactions are rolled back during the switch, including the transaction in which the switch statement is executed. However, the switch itself is successful (that is, it is not rolled back).