API

#libslave Programmer's Documentation#

##Initializing the connection and reading the binary logs:##

Here we will walk through a minimal libslave application and explain the classes and methods used.

Let's begin.

#include "Slave.h"

Only this header needs to be included to start using libslave.

    slave::MasterInfo masterinfo;

    masterinfo.host = host;
    masterinfo.port = port;
    masterinfo.user = user;
    masterinfo.password = password;

    masterinfo.master_info_file = "libslave.master_info";

slave::MasterInfo is a simple structure that specifies the connection parameters to the master. There are five relevant fields in this structure. The first four,host, port, user and password, are the standard and familiar mysql connection parameters. master_info_file needs to be explained in more detail: it is a filename that should point to a writable file where libslave will store the current binlog name and binlog position. The purpose of this master-info file is twofold. Firstly, it is used for remembering the current position in the replication stream persistently. Secondly, it is useful as a means of resetting the replication stream position to a "good" position before the start of your application. (For debugging or maintenance reasons, for example.)

If master_info_file is an empty string, then saving or reading of the master-info file is disabled.

     slave::Slave slave(masterinfo);

Constructs the slave client, with a mandatory slave::MasterInfo parameter.

    slave.setCallback(database, table, callback);

The setCallback method must be called at least once. You need to pass three parameters: database and table are strings which indicate the table name (with database) to monitor. callback is a function pointer or object, with this signature: void (slave::RecordSet&).

Note that only events for those tables which were enabled with a setCallback call will be monitored. Also note that you can enable only one callback per table.

    slave.init();

This method will initialize internal library structures. It is mandatory and must be called after all setCallback methods were called.

    slave.createDatabaseStructure();

This method will connect to the master and retrieve the database schema(s) for the monitored tables. This method is mandatory and must be called after init().

        slave.get_remote_binlog();

This method will connect to the master and start reading the replication binlogs, in an infinite loop.

Note that if a master_info_file is provided, then this method will first attempt to read the binlog position and binlog name from this file. (The format is simple and plain-text: the binlog position on the first line, and then the binlog name on the second line.) If master_info_file cannot be read or parsed, or if no such file is provided, then the method will use the last known binlog position and binlog name gotten from the master.

PLEASE NOTE!!

Updating the master_info_file while your app is running is your own responsibility, not the library's. Calling the slave::stats::writeMasterInfoFile() function will save the current binlog position to the master_info_file. Please call this function at the correct and logically-consistent places in your app's logic.