zongji

library0.5.1jsnpmunverified

A pure JavaScript MySQL binlog listener for Node.js, allowing real-time capture of row-level changes (INSERT, UPDATE, DELETE) from MySQL binary logs. Current stable version is 0.5.x, with irregular releases. Works with MySQL 5.5–5.7, enabling row-format binlog. Requires explicit binlog configuration and replication privileges. A key differentiator is its pure JS implementation (no native dependencies) via the mysql package, but it has limited maintenance and no support for MySQL 8+ binlog features.

database devops

npm install zongji

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZONGJI

zongji

databasejavascriptv0.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZongJi

✓ const ZongJi = require('zongji');

✗ import ZongJi from 'zongji';

The package is CJS-only (no ESM wrapper). Default export is the constructor.

ZongJi

✓ const ZongJi = require('zongji'); const zongji = new ZongJi({host:'localhost', user:'root', password:'pass'});

✗ const zongji = new ZongJi({host:'localhost'});

Constructor requires full mysql connection options or a mysql Connection/Pool object. Omitting user/password causes connection failure.

ZongJi

✓ const mysql = require('mysql'); const pool = mysql.createPool({...}); const zongji = new ZongJi(pool);

✗ const zongji = new ZongJi(mysql.createPool({...}));

When passing a pool, ensure it's a valid pool object, not the factory function.

Instantiates a ZongJi listener, starts capturing row insert events, outputs rows, stops after 10 seconds.

Debug

Known issues

breakingZongJi v0.5.0 drops Node.js v4 and v6 support; requires Node >= 8.

fix

Upgrade Node.js to v8+ or use ZongJi v0.4.7.

affects: >=0.5.0

gotchaMySQL 8.0+ binlog format changes (e.g., caches for geometry types) may cause parse errors. ZongJi does not officially support MySQL 8.

fix

Use MySQL 5.7 or lower, or switch to a maintained alternative like @rodrigogs/mysql-events.

affects: >=0.5.0

deprecatedThe 'row' event is deprecated in favor of 'binlog' event; 'row' may be removed.

fix

Use 'binlog' event and check evt.getEventName().

affects: >=0.5.0

gotchaMySQL binlog checksum (enabled by default in 5.6+) is ignored by ZongJi; it doesn't verify checksums.

fix

Disable binlog_checksum or understand that ZongJi won't detect corruption.

affects: >=0.5.0

breakingZongJi.stop() does not destroy a user-provided mysql Connection/Pool; you must destroy it manually.

fix

Call connection.end() or pool.end() after zongji.stop().

affects: >=0.5.0

gotchaIf no 'includeEvents' filter is passed, all binlog events (including rotate, format_description) are emitted; may cause noise.

fix

Always specify includeEvents with row events: ['writerows','updaterows','deleterows'].

affects: >=0.5.0

Errors

Common errors & fixes

Error: ER_SLAVE_CONVERSION_FAILED: Slave failed to initialize relay log info structure from the repository

Missing replication privileges (GRANT REPLICATION SLAVE).

fix

Run: GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'user'@'host';

Error: connect ECONNREFUSED 127.0.0.1:3306

MySQL not running or connection config wrong.

fix

Check MySQL is running and verify host/port in ZongJi constructor.

Error: Cannot find module 'zongji'

Package not installed.

fix

Run: npm install zongji

Error: ER_BINLOG_ROW_LOGGING_AND_GTID_UNSAFE: ... binlog_format = ROW

MySQL binlog_format not set to ROW.

fix

Set binlog_format = ROW in my.cnf and restart MySQL.

Upgrade

Version history

0.5.1latest on npm

Audit

Dependencies

mysqlrequiredCore dependency for MySQL connection and querying column information.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nevill/zongji ↗

packagezongji ↗

homepagehttps://github.com/nevill/zongji ↗