8.18.3.7. trepctl heartbeat Command

Inserts a heartbeat into the replication stream, which can be used to
identify replication points.

trepctl heartbeat [ -name ]

The heartbeat system is a way of inserting an identifiable event into
the THL that is independent of the data being replicated. This can be
useful when performing different operations on the data where specific
checkpoints must be identified.

To insert a standard heartbeat:

shell> trepctl heartbeat

When performing specific operations, the heartbeat can be given an name:

shell> trepctl heartbeat -name dataload

Heartbeats insert a transaction into the THL using the transaction
metadata and can be used to identify whether replication is operating
between replicator hosts by checking that the sequence number has been
replicated to the slave. Because a new transaction is inserted, the
sequence number is increased, and this can be used to identify if
transactions are being replicated to the slave without requiring changes
to the database. To check replication using the heartbeat:

Heartbeats are given implied names, but can be created with explicit
names that can be tracked during specific events and operations.

For example, when loading a specific set of data, the information may be
loaded and then a backup executed on the slave before enabling standard
replication. This can be achieved by configuring the slave to go offline
when a specific heartbeat event is seen, loading the data on the master,
inserting the heartbeat when the load has finished, and then performing
the slave backup:

On the slave:

slave shell> trepctl offline-deferred -at-heartbeat dataload

The trepctl offline-deferred configures the slave
to continue in the online state until the specified event, in this
case the heartbeat, is received. The deferred state can be checked
by looking at the status output, and the
offlineRequests field:

The heartbeat will appear in the transaction history log after the
data has been loaded and will identify the end of the load.

When the heartbeat is received, the slave will go into the offline
state. Now a backup can be created with all of the loaded data
replicated from the master. Because the slave is in the offline
state, no further data or changes will be recorded on the slave

This method of identifying specific events and points within the
transaction history log can be used for a variety of different purposes
where the point within the replication stream without relying on the
arbitrary event or sequence number.

Internal Implementation

Internally, the heartbeat system operates through a tag added to the
metadata of the THL entry and through a dedicated
heartbeat table within the
schema created for the replicator service. The table contains the
sequence number, event ID, timestamp and heartbeat name. The heartbeat
information is written into a special record within the transaction
history log. A sample THL entry can be seen in the output below:

During replication, slaves identify the heartbeat and record this
information into their own
heartbeat table. Because the
heartbeat is recorded into the transaction history log, the specific
sequence number of the transaction, and the event itself can be easily
identified.