HotStandby commands (ADMIN COMMAND)

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:

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.

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, the following message is displayed: Catchup is active.

You can use the hsb copy command to initially create the Secondary database from the Primary. This command copies the database into a directory that is local to the Primary node (and also local to the Secondary node). After the copy is completed, you may start the Secondary server. After you connect the Primary to the Secondary, the Primary 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 it has been offline for a considerable period of time) that is in a directory local to the Primary node. Read 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 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 Primary can execute the hsb copy command 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 may start the Secondary server and connect the two servers.

This tells the server to disconnect gracefully from the other member of the HSB pair. This command is valid on either the Primary or the Secondary server. 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.

Note Using the shutdown command ADMIN COMMAND 'shutdown' causes the server to do a controlled disconnect before it shuts down. If the Secondary is shut down (and disconnects), the Primary knows that it is safe to go to PRIMARY ALONE state, and will do so.

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

This command can be used to determine which of two servers should become Primary, for example, after a failure where both databases have failed and you do not know which server should be made the Primary. (The server that was the Primary before the connection was broken is not necessarily the server that should become the Primary 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. 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.

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 Primary’s solid.ini file.

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 create a new Secondary database, for example, to replace a corrupt Secondary database, to set up a Secondary database for a new HotStandby configuration, or add a new Secondary to an existing configuration.

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.

Tip: 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, the Primary automatically brings the Secondary up-to-date by copying the transaction log.

This command allows you to set HSB-specific parameters such as AutoPrimaryAlone, Connect, and PingTimeout. For a complete description of each of these parameters, see HotStandby configuration parameters.

When you set the value of one of some parameters, the command takes effect immediately, but is not written to the solid.ini configuration file before a shutdown is executed.

▪PRIMARY, if the connected server is a normal Primary server. In this role, the transactions at the Primary server are sent to the Secondary server.

▪PRIMARY NOHSBLOG, indicating that the Primary server accepts transactions and stores them in the database. However, it does not store the transactions in a log so that it could later send them to the Secondary. To resynchronize the Secondary with the Primary, the entire database at the Primary must be copied to the Secondary server.

▪PRIMARY BROKEN, if the Primary server has a broken connection to the Secondary server. 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 is broken, but transactions are accepted and added to the transaction log at the Primary so that later they can be sent to the Secondary.

▪PRIMARY CATCHUP, if the catchup is in progress. During catchup, the Primary automatically sends the transaction log changes to the Secondary server after the 'hsb connect' command has been issued at the Primary. After the catchup process is completed, the role of the server is switched automatically to PRIMARY. The Primary can continue to accept transactions if its role was PRIMARY ALONE before the connect.

▪SECONDARY, if the connected server is a normal Secondary server. This means the server receives and applies transactions from the Primary.

▪SECONDARY CATCHUP, if the Secondary server is catching up with the changes from the Primary server after the 'hsb connect' command was issued at the Primary server. After the catchup process is completed, the role of the Secondary is switched automatically to SECONDARY.

If you issue hsb role on a server that is not configured for HotStandby, the following error message is returned: 14527: This is a non-HotStandby Server.

This command sets the Primary server to the PRIMARY ALONE state unconditionally. This command is available 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 is in the SECONDARY ACTIVE state, the server will not make any attempt to communicate with the Primary, having received this command. Instead, it will immediately switch to the PRIMARY ALONE state. This behavior may be utilized in cases when the information about the Primary failure reaches HAC before the Secondary 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 is “alive” and in the PRIMARY ACTIVE state when this command is executed in the Secondary, the Primary will be automatically forced to PRIMARY UNCERTAIN state. It can then be moved to the SECONDARY ALONE state and reconnected without any loss of transactions.

Note The alternative way of executing failovers is to use the hsb switch primary command.

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.

Important: 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 primaries.

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

▪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 is broken, but transactions are accepted and stored in the Primary’s transaction log so that they can be forwarded to the Secondary.

▪SECONDARY ACTIVE, if the connected server is a normal Secondary server. This means the server receives and applies transactions from the Primary.

If ADMIN COMMAND 'hsb state' is issued on a server that is not configured for is issued on a server that is not configured for HotStandby, 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 HotStandby state transitions that occur while performing administrative and troubleshooting operations.

This command returns HotStandby status information of the last successfully started operation. The option may be any of the following:

The status command gives information about the outcome of operations that take a prolonged time, after they have started successfully. If the starting of operation fails (for example, because of incorrect state) the status command will not return the status of that operation but the one executed previously.

This command indicates whether or not the server is doing catchup, that is, when the Secondary reads the Primary’s 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 function HOTSTANDBY_CONNECTSTATUS” in Switching the application to the new primary for details on this function.

This command allows you to check 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 a hsb netcopy rather than a hsb copy.

This command switches the database server to PRIMARY. 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 changes from PRIMARY ACTIVE to SECONDARY ACTIVE, and the 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, it will end up in 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 will always make attempt to communicate with the Primary, the network timeout may be involved. Thus, this method is slower than using the hsb set primary alone command. On the other hand, this method secures better against a possibility of dual primaries.

Note 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 Primary (see the hsb switch primary command).

Note If the hsb switch secondary command is issued inside an open transaction (in Windows environments, after the transaction has started and before you execute the COMMIT statement), when you issue the COMMIT statement, it 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. The switch itself is successful (that is, it is not rolled back) because ADMIN COMMANDs are not transactional commands. However, administrative commands force the start of a new transaction if one is not already open.