Replication node commands

You can use commands to create, modify, or drop replication nodes.

The commands are as follows:

CREATE REPLICATION NODE repslet.<node_name> ROLE [MASTER | SUBORDINATE] [HOST NAME <host_name>] [DESCRIPTION <desc>]
Creates either a primary or a replica node in a specified replication set. The first time that you run the command, you must run it from the node where you created the replication set and must specify that node’s name and the ROLE MASTER option. For subsequent CREATE REPLICATION NODE commands, you must either specify the ROLE SUBORDINATE option or not specify the ROLE option (the default value of the option is SUBORDINATE).

Issuing the CREATE REPLICATION NODE...ROLE command initiates by-value replication, which can degrade performance. After you initialize the node or recover it by using the nzreplanalyze -needsrecovery, nzreplbackup, and nzreplrestore commands, by-SQL replication resumes.
DROP REPLICATION NODE repslet.<node_name>
Drops the specified node from the specified replication set. Run this command from the primary node, if you defined one. If there is no current primary, you can run the command on any node in the replication set.

You must drop replica nodes in the replication set before dropping the primary node. When you drop either type of node from the replication set, all of its replicated databases are automatically altered to have a non-replicated state.
ALTER REPLICATION NODE repslet.<node_name> RENAME TO <new_name>
Changes a node’s name. After the NODE_NAME parameter sets the name initially, this command is the only way to change the name. Execute the command from the node that you want to change, which you specify by using the <node_name> option.
ALTER REPLICATION NODE repslet.<node_name> HOST NAME <host_name>
Associates a host name with a node. The name is optional because replication does not use it directly; it is shown in output to help you to identify a node. You can run this command on any node in the replication set.
ALTER REPLICATION NODE repslet.<node_name> DESCRIPTION <desc>
Associates a description with a node. The description is optional because replication does not use it directly; it is shown in output to help you to identify a node. You can run this command on any node in the replication set.
ALTER REPLICATION NODE repslet.<node_name> STATE {ACTIVE | SUSPENDED}
Changes the activation state of the specified node. You must run this command on the node whose state you are modifying, regardless of whether it is a primary or replica.

Suspending replication on a primary node causes all subsequent update transactions against replicated data to fail. Suspending replication on a replica node causes the apply agent to stop applying replicated transactions from its associated replication log server. Activating replication, on the primary or replica, reverses the suspension. Reversing the suspension on the replica causes the system to apply any accumulated transactions that ran against the primary while the replica was suspended, synchronizing the systems.
ALTER REPLICATION NODE repslet.<node_name> ROLE {MASTER | SUBORDINATE} [OVERRIDE]
Alters the node’s role in the replication set. You can run this command on a primary or a replica. Altering a node’s role (to or from primary or replica) always resets the node’s replication state to SUSPENDED. You must issue the ALTER REPLICATION NODE STATE command to change the state to ACTIVE before replication can resume. If there is no active primary, no new replicated transactions can occur. However, any existing unapplied transactions on the replicas are still applied, until the replicas catch up to the most current position. There can only be one active primary at any particular time.

Normally, all control is done from the primary, but if the primary is inaccessible, use this command with the OVERRIDE option. The OVERRIDE option, which forces a transition, is necessary when executing a change that does not provide a smooth transition from an old primary to a new primary. Examples include demoting a primary from a replica node or promoting a replica node to primary when there was no clean demotion of the prior primary. When no primary is defined, you can promote any of the replica nodes to primary.
Possible role changes that you can implement by using the ALTER REPLICATION NODE ROLE command are as follows:
Update role from primary to replica

You can run the command without the OVERRIDE option from the primary node to initiate an orderly transfer of the primary role. When you run the command at the primary, the command first suspends replication at the node, which means that update transactions against replicated data fail. If there are any currently executing update transactions against replicated data, the command fails, and you must retry it when the existing transactions are complete (commit or abort). When this command succeeds, it writes a final CSN to the replication metadata.
You can specify this command with the OVERRIDE option at a node other than the current primary as part of a forced transfer of the primary role, for example, if the primary fails or becomes inaccessible.

Update role from replica to primary
You must execute this command from the node whose role you are updating to primary. The command fails if a primary is already defined, so before issuing the command, you must set the current primary's role to replica. The command checks that the soon-to-be primary node has applied all replicated transactions that are available from the replication queue manager. If not, the command fails, and you must retry it after the node is caught up. (To check the state of the database’s synchronization, use either the _v_replication_state or _v_replication_sync view.) If the NPS® node is caught up to the replication queue manager, the possible behaviors are as follows:
- There was an orderly transition of the prior primary to replica, and the node that is becoming the new primary applied all replicated transactions up to the final CSN that was written by the prior primary. The command succeeds and updates the replication metadata to reflect the role change.
- There was a forced transition and no final CSN is available from the prior primary, or the replication queue manager cannot deliver all update transactions from the current CSN through to the final CSN. In this case, the command fails unless you specified the OVERRIDE option.
  Forcing a transition to the primary role when the node did not apply all replicated transactions that were committed on the prior primary can cause a fork in the transaction stream. For example, the previous primary might continue to execute replicated transactions because of a communication issue that prevented it from receiving the instruction that it was demoted. NPS detects this scenario when conflicting transactions appear on the replication queue manager from the prior primary and suspends all replication nodes. Fix this by running the nzreplfork command and then proceeding with recovery steps. The command selects the correct branch to keep and then outputs the additional required steps for recovery.