API

#libslave Programmer's Documentation#

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

#include "Slave.h"

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

    slave::MasterInfo masterinfo;
    slave::EmptyExtState state;

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

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. state needs to be explained in more detail: it is an object of a class derived from slave::ExtStateIface which should have methods for tracking mysql slave statistics and for persistent storing/setting the current binlog name and binlog position.

     slave::Slave slave(masterinfo, state);

Constructs the slave client, with mandatory slave::MasterInfo and ExtStateIface& parameters.

    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.

This method will first attempt to read the binlog position and binlog using the provided ExtStateIface object. If a binlog position/name is not available from the state object, then the method will use the last known binlog position and binlog name gotten from the master.

PLEASE NOTE!!

Updating the current binlog name and position while your app is running is your own responsibility, not the library's. Calling the ExtStateIface::saveMasterInfo() function will store the current binlog position and name. Please call this function at the correct and logically-consistent places in your app's logic.

##Interpreting a row-level event:##

One event (meaning the changes to one row of the table) is represented by this structure:

typedef std::map<std::string, std::pair<std::string, boost::any> > Row;

struct RecordSet {
    Row m_row, m_old_row;

    std::string tbl_name;
    std::string db_name;

    time_t when;

    enum TypeEvent { Update, Delete, Write, PreInit, PostInit };

    TypeEvent type_event;
         
    unsigned int master_id;
};

A Row is one row of the table. Is is a map where the keys are the names of the table's fields, and the values are a pair of (field type, field data). The field type is a string, in the same syntax as you'd see, for example, in mysql's show create table. The field data is a boost::any object. The actual type of the data varies depending on the field's mysql type; see below.

A RecordSet is one row of the table, plus several supplementary properties of the event.

m_row holds the values of the row. All fields of the table will be present, unless the field's value is a mysql NULL. (NULL values are represented by an absense of the field in the Row!)

m_old_row is only relevant for UPDATE events; in this case, m_old_row holds the values of the row before the update; m_row holds the values of the row after the update. For INSERT and DELETE events, m_old_row will always be equal to m_row.

db_name and tbl_name are the database and table name, respectively.

when is the timestamp of the event on the server; this is useful for tracking the replication lag. (Like mysql's "seconds behind master".)

type_event is a flag indicating the type of the event. Possible values are Update, Delete and Write -- indicating UPDATE, DELETE and INSERT operations on the master, respectively. (PreInit and PostInit are not used by libslave itself and might be needed only for third-party wrappers.)

master_id is the server-id of the master where this event originated. (Note: this may be different from the server-id of the master of libslave's connection!) This value is equivalent to mysql's @@server_id variable.

##Mapping the mysql type to C++ type##

• tiny → char
• short → uint16
• medium → uint32
• long → uint32
• long long → ulonglong
• double → double
• float → float
• timestamp → uint32
• year → char
• datetime → ulonglong
• date → uint32
• time → uint32
• enum → int
• set → ulonglong
• varchar → std::string
• text → std::string
• blob → std::string

Note that for mysql's date/datetime fields you'll need additional post-processing to convert the data to a proper POSIX-style time structure. (For example, a mysql datetime value is represented as a 64-bit number similar to this: 20110313094909.)