Home

Awesome

A MySQL 8.0-compatible fork of ZongJi - a MySQL binlog listener for Node.js, originally created by Nevill Dutt.

@vlasky/zongji has been tested working with MySQL 5.5, 5.6, 5.7 and 8.0.

It leverages @vlasky/mysql, a fork of mysql with the following enhancements:

Latest Release

ZongJi release versions since 0.5.0 only support Node.js version 8 and above.

Version 0.4.7 is the last release that supports Node.js version 4.x.

Quick Start

let zongji = new ZongJi({ /* ... MySQL Connection Settings ... */ });

// Each change to the replication log results in an event
zongji.on('binlog', function(evt) {
  evt.dump();
});

// Binlog must be started, optionally pass in filters
zongji.start({
  includeEvents: ['tablemap', 'writerows', 'updaterows', 'deleterows']
});

For a complete implementation see example.js...

Installation

ZongJi Class

The ZongJi constructor accepts one argument of either:

If a Connection or Pool object is passed to the constructor, it will not be destroyed/ended by Zongji's stop() method.

If there is a dateStrings mysql configuration option in the connection details or connection, ZongJi will follow it.

Each instance includes the following methods:

Method NameArgumentsDescription
startoptionsStart receiving replication events, see options listed below
stopNoneDisconnect from MySQL server, stop receiving events
oneventName, handlerAdd a listener to the binlog or error event. Each handler function accepts one argument.

Some events can be emitted in different phases:

Event NameDescription
readyThis event is occurred right after ZongJi successfully established a connection, setup slave status, and set binlog position.
binlogOnce a binlog is received and passes the filter, it will bubble up with this event.
errorEvery error will be caught by this event.
stoppedEmitted when ZongJi connection is stopped (ZongJi#stop is called).

Options available:

Option NameTypeDescription
serverIdintegerUnique number (1 - 2<sup>32</sup>) to identify this replication slave instance. Must be specified if running more than one instance of ZongJi. Must be used in start() method for effect.<br>Default: 1
startAtEndbooleanPass true to only emit binlog events that occur after ZongJi's instantiation. Must be used in start() method for effect.<br>Default: false
filenamestringBegin reading events from this binlog file. If specified together with position, will take precedence over startAtEnd.
positionintegerBegin reading events from this position. Must be included with filename.
includeEvents[string]Array of event names to include<br>Example: ['writerows', 'updaterows', 'deleterows']
excludeEvents[string]Array of event names to exclude<br>Example: ['rotate', 'tablemap']
includeSchemaobjectObject describing which databases and tables to include (Only for row events). Use database names as the key and pass an array of table names or true (for the entire database).<br>Example: { 'my_database': ['allow_table', 'another_table'], 'another_db': true }
excludeSchemaobjectObject describing which databases and tables to exclude (Same format as includeSchema)<br>Example: { 'other_db': ['disallowed_table'], 'ex_db': true }

Supported Binlog Events:

Event nameDescription
unknownCatch any other events
queryInsert/Update/Delete Query
intvarAutoincrement and LAST_INSERT_ID
rotateNew Binlog file Not required to be included to rotate to new files, but it is required to be included in order to keep the filename and position properties updated with current values for graceful restarting on errors.
formatFormat Description
xidTransaction ID
tablemapBefore any row event (must be included for any other row events)
writerowsRows inserted, row data array available as rows property on event object
updaterowsRows changed, row data array available as rows property on event object
deleterowsRows deleted, row data array available as rows property on event object

Event Methods

Neither method requires any arguments.

NameDescription
dumpLog a description of the event to the console
getEventNameReturn the name of the event

Important Notes

Run Tests

References

The following resources provided valuable information that greatly assisted in creating ZongJi:

License

MIT