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;

    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.

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

• int → uint32_t
• bigint → unsigned long long
• mediumint → uint32_t
• smallint → uint16_t
• tinyint → char
• bit → uint64_t
• enum → int
• set → unsigned long long
• float → float
• double → double
• decimal → slave::decimal (convertible to double)
• date → uint32_t
• time → int32_t
• datetime → unsigned long long
• timestamp → uint32_t
• char → std::string
• varchar → std::string
• tinytext → std::string
• text → std::string
• mediumtext → std::string
• long text → std::string
• blob → std::string

Note that signed and unsigned MySQL types are both mapped to unsigned C++ types, i.e. smallint -1 will become uint16_t(-1) in C++ (65535).

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.

• date value consists of a day in first 5 bits (values from 1 to 31), a month in the next 4 bits (values from 1 to 12), and a year in the rest of value.
• datetime value is represented as a 64-bit number similar to this: 20110313094909.

Code for it is provided in file types.h - functions

// Converts date from slave to timestamp assuming date is specified in local timezone.
time_t date2time(MY_DATE date);
// Converts date and time from slave to timestamp assuming date is specified in local timezone.
time_t datetime2time(MY_DATETIME datetime);