9.24.3.12. trepctl online Command

The trepctl online command puts the replicator into the online state. During the state change from offline to online various options can be used to control how the replicator goes back on line. For example, the replicator can be placed online, skipping one or more faulty transactions or disabling specific configurations.

trepctl online [ -all-services ] [ -base-seqno x ] [ -force ] [ -from-event event ] [ -no-checksum ] [ -skip-seqno seqdef ] [ -until-event event ] [ -until-heartbeat [name] ] [ -until-seqno seqno ] [ -until-time YYYY-MM-DD_hh:mm:ss ]

Where:

Table 9.52. trepctl online Command Options

OptionDescription
-all-servicesPlace online all available services
-base-seqno xOn a Primary, restart replication using the specified sequence number
-forceForce the online state
-from-event eventStart replication from the specified event
-no-checksumDisable checksums for all events when going online
-skip-seqno seqdefSkip one, multiple, or ranges of sequence numbers before going online
-until-event eventDefine an event when replication will stop
-until-heartbeat [name]Define a heartbeat when replication will stop
-until-seqno seqnoDefine a sequence no when replication will stop
-until-time YYYY-MM-DD_hh:mm:ssDefine a time when replication will stop

The trepctl online command attempts to switch replicator into the online state. The replicator may need to be put online because it has been placed offline for maintenance, or due to a failure.

To put the replicator online use the standard form of the command:

shell> trepctl online

Going online may fail if the reason for going offline was due to a fault in processing the THL, or in applying changes to the dataserver. The replicator will refuse to go online if there is a fault, but certain failures can be explicitly bypassed.

9.24.3.12.1. Going Online from Specific Transaction Points

If there is one, or more, event in the THL that could not be applied to the Replica because of a mismatch in the data (for example, a duplicate key), the event or events can be skipped using the -skip-seqno option. For example, the status shows that a statement failed:

shell> trepctl status
...
pendingError           : Event application failed: seqno=5250 fragno=0 »
    message=java.sql.SQLException: Statement failed on slave but succeeded on master
...

To skip the single sequence number, 5250, shown:

shell> trepctl online -skip-seqno 5250

The sequence number specification can be specified according to the following rules:

  • A single sequence number:

    shell> trepctl online -skip-seqno 5250
  • A sequence range:

    shell> trepctl online -skip-seqno 5250-5260
  • A comma-separated list of individual sequence numbers and/or ranges:

    shell> trepctl online -skip-seqno 5250,5251,5253-5260
9.24.3.12.2. Going Online from a Base Sequence Number

Note

To set the position of the replicator, the dsctl command can also be used.

Alternatively, the base sequence number, the transaction ID where replication should start, can be specified explicitly:

shell> trepctl online -base-seqno 5260

Warning

Use of -base-seqno should be restricted to replicators in the master role only. Use on Replicas may lead to duplication or corruption of data.

Note

If issuing -base-seqno and -from-event together, you need to also issue the -force option for it to work, otherwise a warning will be displayed

9.24.3.12.3. Going Online from a Specific Event

Note

To set the position of the replicator, the dsctl command can also be used.

If the source event (for example, the MySQL binlog position) is known, this can be used as the reference point when going online and restarting replication:

shell> trepctl online -from-event 'mysql-bin.000011:0000000000002552;0'

When used, replication will start from the next event within the THL. The event ID provided must be valid. The event cannot be found in the THL, the operation will fail.

Note

If issuing -base-seqno and -from-event together, you need to also issue the -force option for it to work, otherwise a warning will be displayed

9.24.3.12.4. Going Online Until Specific Transaction Points

There are times when it is useful to be able to online until a specific point in time or in the replication stream. For example, when performing a bulk load parallel replication may be enabled, but only a single applier stream is required once the load has finished. The replicator can be configured to go online for a limited period, defined by transaction IDs, events, heartbeats, or a specific time.

The replicator must be in the offline state before the deferred online specifications are made. Multiple deferred online states can be specified in the same command when going online.

The setting of a future offline state can be seen by looking at the offlineRequests field when checking the status:

shell> trepctl status
...
minimumStoredSeqNo     : 0
offlineRequests        : Offline at sequence number: 5262;Offline at time: 2014-01-01 00:00:00 EST
pendingError           : NONE
...

If the replicator goes offline for any reason before the deferred offline state is reached, the deferred settings are lost.

9.24.3.12.4.1. Going Online Until Specified Sequence Number

To go online until a specific transaction ID, use -until-seqno:

shell> trepctl online -until-seqno 5260

This will process all transactions up to, and including, sequence 5260, at which point the replicator will go offline.

9.24.3.12.4.2. Going Online Until Specified Event

To go online until a specific event ID:

shell> trepctl online -until-event  'mysql-bin.000011:0000000000003057;0'

Replication will go offline when the event ID up to the specified event has been processed.

9.24.3.12.4.3. Going Online Until Heartbeat

To go online until a heartbeat event:

shell> trepctl online -until-heartbeat

Heartbeats are inserted into the replication stream periodically, replication will stop once the heartbeat has been seen before the next transaction. A specific heartbeat can also be specified:

shell> trepctl online -until-heartbeat load-finished
9.24.3.12.4.4. Going Online Until Specified Time

To go online until a specific date and time:

shell> trepctl online -until-time 2014-01-01_00:00:00

Replication will go offline once the transaction being processed at the time specified has completed.

9.24.3.12.5. Going Online by Force

In situations where the replicator needs to go online, the online state can be forced. This changes the replicator state to online, but provides no guarantees that the online state will remain in place if another, different, error stops replication.

shell> trepctl online -force
9.24.3.12.6. Going Online without Validating Checksum

In the event of a checksum problem in the THL, checksums can be disabled using the -no-checksum option:

shell> trepctl online -no-checksum

This will bring the replicator online without reading or writing checksum information.

Important

Use of the -no-checksum option disables both the reading and writing of checksums on log records. If starting the replicator without checksums to get past a checksum failure, the replicator should be taken offline again once the offending event has been replicated. This will avoid generating too many local records in the THL without checksums.