{"id":13425845,"url":"https://github.com/rodrigogs/mysql-events","last_synced_at":"2025-03-15T20:31:28.013Z","repository":{"id":54478295,"uuid":"139776415","full_name":"rodrigogs/mysql-events","owner":"rodrigogs","description":"A node package that watches a MySQL database and runs callbacks on matched events.","archived":false,"fork":true,"pushed_at":"2024-05-27T06:41:23.000Z","size":246,"stargazers_count":137,"open_issues_count":32,"forks_count":53,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-14T05:41:53.136Z","etag":null,"topics":["binlog","database","event-sourcing","events","mysql","nodejs","reactive"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"involvestecnologia/mysql-events","license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rodrigogs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-05T00:29:05.000Z","updated_at":"2025-03-06T07:39:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rodrigogs/mysql-events","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrigogs%2Fmysql-events","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrigogs%2Fmysql-events/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrigogs%2Fmysql-events/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrigogs%2Fmysql-events/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodrigogs","download_url":"https://codeload.github.com/rodrigogs/mysql-events/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243790939,"owners_count":20348378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binlog","database","event-sourcing","events","mysql","nodejs","reactive"],"created_at":"2024-07-31T00:01:20.287Z","updated_at":"2025-03-15T20:31:23.281Z","avatar_url":"https://github.com/rodrigogs.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# mysql-events\n[![CircleCI](https://circleci.com/gh/rodrigogs/mysql-events.svg)](https://circleci.com/gh/rodrigogs/mysql-events)\n[![Code Climate](https://codeclimate.com/github/rodrigogs/mysql-events/badges/gpa.svg)](https://codeclimate.com/github/rodrigogs/mysql-events)\n[![Test Coverage](https://codeclimate.com/github/rodrigogs/mysql-events/badges/coverage.svg)](https://codeclimate.com/github/rodrigogs/mysql-events/coverage)\n\nA [node.js](https://nodejs.org) package that watches a MySQL database and runs callbacks on matched events.\n\nThis package is based on the [original ZongJi](https://github.com/nevill/zongji) and the [original mysql-events](https://github.com/spencerlambert/mysql-events) modules. Please make sure that you meet the requirements described at [ZongJi](https://github.com/rodrigogs/zongji#installation), like MySQL binlog etc.\n\nCheck [@kuroski](https://github.com/kuroski)'s [mysql-events-ui](https://github.com/kuroski/mysql-events-ui) for a `mysql-events` UI implementation.\n\n## Install\n```sh\nnpm install @rodrigogs/mysql-events\n```\n\n## Quick Start\n```javascript\nconst mysql = require('mysql');\nconst MySQLEvents = require('@rodrigogs/mysql-events');\n\nconst program = async () =\u003e {\n  const connection = mysql.createConnection({\n    host: 'localhost',\n    user: 'root',\n    password: 'root',\n  });\n\n  const instance = new MySQLEvents(connection, {\n    startAtEnd: true,\n    excludedSchemas: {\n      mysql: true,\n    },\n  });\n\n  await instance.start();\n\n  instance.addTrigger({\n    name: 'TEST',\n    expression: '*',\n    statement: MySQLEvents.STATEMENTS.ALL,\n    onEvent: (event) =\u003e { // You will receive the events here\n      console.log(event);\n    },\n  });\n  \n  instance.on(MySQLEvents.EVENTS.CONNECTION_ERROR, console.error);\n  instance.on(MySQLEvents.EVENTS.ZONGJI_ERROR, console.error);\n};\n\nprogram()\n  .then(() =\u003e console.log('Waiting for database events...'))\n  .catch(console.error);\n```\n[Check the examples](https://github.com/rodrigogs/mysql-events/examples)\n\n## Usage\n  ### #constructor(connection, options)\n  - Instantiate and create a database connection using a DSN\n    ```javascript\n    const dsn = {\n      host: 'localhost',\n      user: 'username',\n      password: 'password',\n    };\n\n    const myInstance = new MySQLEvents(dsn, { /* ZongJi options */ });\n    ```\n\n  - Instantiate and create a database connection using a preexisting connection\n    ```javascript\n    const connection = mysql.createConnection({\n      host: 'localhost',\n      user: 'username',\n      password: 'password',\n    });\n\n    const myInstance = new MySQLEvents(connection, { /* ZongJi options */ });\n    ```\n  - Options(the second argument) is for ZongJi options\n    ```javascript\n    const myInstance = new MySQLEvents({ /* connection */ }, {\n      serverId: 3,\n      startAtEnd: true,\n    });\n    ```\n    [See more about ZongJi options](https://github.com/rodrigogs/zongji#zongji-class)\n\n  ### #start()\n  - start function ensures that MySQL is connected and ZongJi is running before resolving its promise\n    ```javascript\n    myInstance.start()\n      .then(() =\u003e console.log('I\\'m running!'))\n      .catch(err =\u003e console.error('Something bad happened', err));\n    ```\n  ### #stop()\n  - stop function terminates MySQL connection and stops ZongJi before resolving its promise\n    ```javascript\n    myInstance.stop()\n      .then(() =\u003e console.log('I\\'m stopped!'))\n      .catch(err =\u003e console.error('Something bad happened', err));\n    ```\n  ### #pause()\n  - pause function pauses MySQL connection until `#resume()` is called, this it useful when you're receiving more data than you can handle at the time\n    ```javascript\n    myInstance.pause();\n    ```\n  ### #resume()\n  - resume function resumes a paused MySQL connection, so it starts to generate binlog events again\n    ```javascript\n    myInstance.resume();\n    ```\n  ### #addTrigger({ name, expression, statement, onEvent })\n  - Adds a trigger for the given expression/statement and calls the `onEvent` function when the event happens\n    ```javascript\n    instance.addTrigger({\n      name: 'MY_TRIGGER',\n      expression: 'MY_SCHEMA.MY_TABLE.MY_COLUMN',\n      statement: MySQLEvents.STATEMENTS.INSERT,\n      onEvent: async (event) =\u003e {\n        // Here you will get the events for the given expression/statement.\n        // This could be an async function.\n        await doSomething(event);\n      },\n    });\n    ```\n  - The `name` argument must be unique for each expression/statement, it will be user later if you want to remove a trigger\n    ```javascript\n    instance.addTrigger({\n      name: 'MY_TRIGGER',\n      expression: 'MY_SCHEMA.*',\n      statement: MySQLEvents.STATEMENTS.ALL,\n      ...\n    });\n\n    instance.removeTrigger({\n      name: 'MY_TRIGGER',\n      expression: 'MY_SCHEMA.*',\n      statement: MySQLEvents.STATEMENTS.ALL,\n    });\n    ```\n  - The `expression` argument is very dynamic, you can replace any step by `*` to make it wait for any schema, table or column events\n    ```javascript\n    instance.addTrigger({\n      name: 'Name updates from table USERS at SCHEMA2',\n      expression: 'SCHEMA2.USERS.name',\n      ...\n    });\n    ```\n    ```javascript\n    instance.addTrigger({\n      name: 'All database events',\n      expression: '*',\n      ...\n    });\n    ```\n    ```javascript\n    instance.addTrigger({\n      name: 'All events from SCHEMA2',\n      expression: 'SCHEMA2.*',\n      ...\n    });\n    ```\n    ```javascript\n    instance.addTrigger({\n      name: 'All database events for table USERS',\n      expression: '*.USERS',\n      ...\n    });\n    ```\n  - The `statement` argument indicates in which database operation an event should be triggered\n    ```javascript\n    instance.addTrigger({\n      ...\n      statement: MySQLEvents.STATEMENTS.ALL,\n      ...\n    });\n    ```\n    [Allowed statements](https://github.com/rodrigogs/mysql-events/blob/master/lib/STATEMENTS.enum.js)\n  - The `onEvent` argument is a function where the trigger events should be threated\n    ```javascript\n    instance.addTrigger({\n      ...\n      onEvent: (event) =\u003e {\n        console.log(event); // { type, schema, table, affectedRows: [], affectedColumns: [], timestamp, }\n      },\n      ...\n    });\n    ```\n  ### #removeTrigger({ name, expression, statement })\n  - Removes a trigger from the current instance\n    ```javascript\n    instance.removeTrigger({\n      name: 'My previous created trigger',\n      expression: '',\n      statement: MySQLEvents.STATEMENTS.INSERT,\n    });\n    ```\n  ### Instance events\n  - MySQLEvents class emits some events related to its MySQL connection and ZongJi instance\n    ```javascript\n    instance.on(MySQLEvents.EVENTS.CONNECTION_ERROR, (err) =\u003e console.log('Connection error', err));\n    instance.on(MySQLEvents.EVENTS.ZONGJI_ERROR, (err) =\u003e console.log('ZongJi error', err));\n    ```\n  [Available events](https://github.com/rodrigogs/mysql-events/blob/master/lib/EVENTS.enum.js)\n\n## Tigger event object\nIt has the following structure:\n```javascript\n{\n  type: 'INSERT | UPDATE | DELETE',\n  schema: 'SCHEMA_NAME',\n  table: 'TABLE_NAME',\n  affectedRows: [{\n    before: {\n      column1: 'A',\n      column2: 'B',\n      column3: 'C',\n      ...\n    },\n    after: {\n      column1: 'D',\n      column2: 'E',\n      column3: 'F',\n      ...\n    },\n  }],\n  affectedColumns: [\n    'column1',\n    'column2',\n    'column3',\n  ],\n  timestamp: 1530645380029,\n  nextPosition: 1343,\n  binlogName: 'bin.001',\n}\n```\n\n**Make sure the database user has the privilege to read the binlog on database that you want to watch on.**\n\n## LICENSE\n[BSD-3-Clause](https://github.com/rodrigogs/mysql-events/blob/master/LICENSE) © Rodrigo Gomes da Silva\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodrigogs%2Fmysql-events","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodrigogs%2Fmysql-events","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodrigogs%2Fmysql-events/lists"}