A MySQL binlog listener running on Node.js.

ZongJi (踪迹) is pronounced as zōng jì in Chinese.

This package is a "pure JS" implementation based on node-mysql. Since v0.2.0, The native part (which was written in C++) has been dropped.

This package has been tested to work in MySQL 5.5, 5.6, and 5.7.

var 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...

• Requires Node.js v4+

  $ npm install zongji

• Enable MySQL binlog in my.cnf, restart MySQL server after making the changes.

  From MySQL 5.6, binlog checksum is enabled by default. Zongji can work with it, but it doesn't really verify it.

  # Must be unique integer from 1-2^32
  server-id        = 1
  # Row format required for ZongJi
  binlog_format    = row
  # Directory must exist. This path works for Linux. Other OS may require
  #   different path.
  log_bin          = /var/log/mysql/mysql-bin.log
  
  binlog_do_db     = employees   # Optional, limit which databases to log
  expire_logs_days = 10          # Optional, purge old logs
  max_binlog_size  = 100M        # Optional, limit log size
  

• Create an account with replication privileges, e.g. given privileges to account zongji (or any account that you use to read binary logs)

  GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'zongji'@'localhost'

The ZongJi constructor accepts one argument of either:

• An object containing MySQL connection details in the same format as used by node-mysql
• Or, a node-mysql Connection or Pool object that will be used for querying column information.

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 node-mysql configuration option in the connection details or connection, ZongJi will follow it.

Each instance includes the following methods:

Options available:

• By default, all events and schema are emitted.
• excludeSchema and excludeEvents take precedence over includeSchema and includeEvents, respectively.

Supported Binlog Events:

Event Methods

Neither method requires any arguments.

• 🌟 All types allowed by node-mysql are supported by this package.
• 🙊 While 64-bit integers in MySQL (BIGINT type) allow values in the range of 2⁶⁴ (± ½ × 2⁶⁴ for signed values), Javascript's internal storage of numbers limits values to 2⁵³, making the allowed range of BIGINT fields only -9007199254740992 to 9007199254740992. Unsigned 64-bit integers must also not exceed 9007199254740992.
• 👉 TRUNCATE statement does not cause corresponding DeleteRows event. Use unqualified DELETE FROM for same effect.
• When using fractional seconds with DATETIME and TIMESTAMP data types in MySQL > 5.6.4, only millisecond precision is available due to the limit of Javascript's Date object.

• install Docker
• run docker-compose up and then ./docker-test.sh

I learnt many things from following resources while making ZongJi.

• https://github.com/felixge/node-mysql
• https://github.com/felixge/faster-than-c/
• https://intuitive-search.blogspot.co.uk/2011/07/binary-log-api-and-replication-listener.html
• https://github.com/Sannis/node-mysql-libmysqlclient
• https://kkaefer.com/node-cpp-modules/
• https://dev.mysql.com/doc/internals/en/replication-protocol.html
• https://www.cs.wichita.edu/~chang/lecture/cs742/program/how-mysql-c-api.html
• https://github.com/jeremycole/mysql_binlog (Ruby implemenation of MySQL binlog parser)
• https://dev.mysql.com/doc/internals/en/date-and-time-data-type-representation.html

MIT