{"id":18304551,"url":"https://github.com/numtel/mysql-live-select","last_synced_at":"2025-08-19T08:13:09.172Z","repository":{"id":25271155,"uuid":"28696619","full_name":"numtel/mysql-live-select","owner":"numtel","description":"NPM Package to provide events on updated MySQL SELECT result sets","archived":false,"fork":false,"pushed_at":"2017-04-07T18:54:12.000Z","size":497,"stargazers_count":87,"open_issues_count":15,"forks_count":26,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-08-09T11:39:42.769Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/numtel.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":"2015-01-01T21:51:45.000Z","updated_at":"2024-04-14T12:00:40.000Z","dependencies_parsed_at":"2022-08-23T23:50:35.448Z","dependency_job_id":null,"html_url":"https://github.com/numtel/mysql-live-select","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/numtel/mysql-live-select","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtel%2Fmysql-live-select","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtel%2Fmysql-live-select/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtel%2Fmysql-live-select/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtel%2Fmysql-live-select/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numtel","download_url":"https://codeload.github.com/numtel/mysql-live-select/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtel%2Fmysql-live-select/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271121168,"owners_count":24702723,"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","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-05T15:29:19.178Z","updated_at":"2025-08-19T08:13:09.143Z","avatar_url":"https://github.com/numtel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mysql-live-select [![Build Status](https://travis-ci.org/numtel/mysql-live-select.svg?branch=master)](https://travis-ci.org/numtel/mysql-live-select)\n\nNPM Package to provide events when a MySQL select statement result set changes.\n\nBuilt using the [`zongji` Binlog Tailer](https://github.com/nevill/zongji) and [`node-mysql`](https://github.com/felixge/node-mysql) projects.\n\n* [Example Application using Express, SockJS and React](https://github.com/numtel/reactive-mysql-example)\n* [Meteor package for reactive MySQL](https://github.com/numtel/meteor-mysql)\n* [NPM Package for Sails.js connection adapter integration](https://github.com/numtel/sails-mysql-live-select)\n* [Analogous package for PostgreSQL, `pg-live-select`](https://github.com/numtel/pg-live-select)\n\nThis package has been tested to work in MySQL 5.1, 5.5, 5.6, and 5.7. Expected support is all MySQL server version \u003e= 5.1.15.\n\n## Installation\n\n* Add the package to your project:\n  ```bash\n  $ npm install mysql-live-select\n  ```\n\n* Enable MySQL binlog in `my.cnf`, restart MySQL server after making the changes.\n\n  ```\n  # Must be unique integer from 1-2^32\n  server-id        = 1\n  # Row format required for ZongJi\n  binlog_format    = row\n  # Directory must exist. This path works for Linux. Other OS may require\n  #   different path.\n  log_bin          = /var/log/mysql/mysql-bin.log\n\n  binlog_do_db     = employees   # Optional, limit which databases to log\n  expire_logs_days = 10          # Optional, purge old logs\n  max_binlog_size  = 100M        # Optional, limit log size\n  ```\n* Create an account, then grant replication privileges:\n\n  ```sql\n  GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'user'@'localhost'\n  ```\n\n## LiveMysql Constructor\n\nThe `LiveMysql` constructor makes 3 connections to your MySQL database:\n\n* Connection for executing `SELECT` queries (exposed `node-mysql` instance as `db` property)\n* Replication slave connection\n* `information_schema` connection for column information\n\n#### Arguments\n\nArgument | Type | Description\n---------|------|---------------------------\n`settings` | `object` | An object defining the settings. In addition to the [`node-mysql` connection settings](https://github.com/felixge/node-mysql#connection-options), the additional settings below are available.\n`callback` | `function` | **Deprecated:** callback on connection success/failure. Accepts one argument, `error`. See information below about events emitted.\n\n#### Additional Settings\n\nSetting | Type | Description\n--------|------|------------------------------\n`serverId`  | `integer` | [Unique number (1 - 2\u003csup\u003e32\u003c/sup\u003e)](http://dev.mysql.com/doc/refman/5.0/en/replication-options.html#option_mysqld_server-id) to identify this replication slave instance. Must be specified if running more than one instance.\u003cbr\u003e**Default:** `1`\n`minInterval` | `integer` | Pass a number of milliseconds to use as the minimum between result set updates. Omit to refresh results on every update. May be changed at runtime.\n`checkConditionWhenQueued` | `boolean` | Set to `true` to call the condition function of a query on every binlog row change event. By default (when undefined or `false`), the condition function will not be called again when a query is already queued to be refreshed. Enabling this can be useful if external caching of row changes.\n\n#### Events Emitted\n\nUse `.on(...)` to handle the following event types.\n\nEvent Name | Arguments | Description\n-----------|-----------|---------------\n`error`    | `Error` | An error has occurred.\n`ready`    | *None*  | The database connection is ready.\n\n#### Quick Start\n\n```javascript\n// Example:\nvar liveConnection = new LiveMysql(settings);\nvar table = 'players';\nvar id = 11;\n\nliveConnection.select(function(esc, escId){\n  return (\n    'select * from ' + escId(table) +\n    'where `id`=' + esc(id)\n  );\n}, [ {\n  table: table,\n  condition: function(row, newRow){\n    // Only refresh the results when the row matching the specified id is\n    // changed.\n    return row.id === id\n      // On UPDATE queries, newRow must be checked as well\n      || (newRow \u0026\u0026 newRow.id === id);\n  }\n} ]).on('update', function(diff, data){\n  // diff contains an object describing the difference since the previous update\n  // data contains an array of rows of the new result set\n  console.log(data);\n});\n```\nSee [`example.js`](example.js) for full source...\n\n\n### LiveMysql.prototype.select(query, triggers)\n\nArgument | Type | Description\n---------|------|----------------------------------\n`query`  | `string` or `function` | `SELECT` SQL statement. See note below about passing function.\n`triggers` | `[object]` | Array of objects defining which row changes to update result set\n\nReturns `LiveMysqlSelect` object\n\n#### Function as `query`\n\nA function may be passed as the `query` argument that accepts two arguments.\n\n* The first argument, `esc` is a function that escapes values in the query.\n* The second argument, `escId` is a function that escapes identifiers in the query.\n\n#### Trigger options\n\nName | Type | Description\n-----|------|------------------------------\n`table` | `string` | Name of table (required)\n`database` | `string` | Name of database (optional)\u003cbr\u003e**Default:** `database` setting specified on connection\n`condition` | `function` | Evaluate row values (optional)\n\n#### Condition Function\n\nA condition function accepts up to three arguments:\n\nArgument Name | Description\n--------------|-----------------------------\n`row`         | Table row data\n`newRow`      | New row data (only available on `UPDATE` queries, `null` for others)\n`rowDeleted`  | Extra argument for aid in external caching: `true` on `DELETE`  queries, `false` on `INSERT`  queries, `null` on `UPDATE`  queries.\n\nReturn `true` when the row data meets the condition to update the result set.\n\n### LiveMysql.prototype.pause()\n\nTemporarily skip processing of updates from the binary log.\n\n### LiveMysql.prototype.resume()\n\nBegin processing updates after `pause()`. All active live select instances will be refreshed upon resume.\n\n### LiveMysql.prototype.end()\n\nClose connections and stop checking for updates.\n\n### LiveMysql.applyDiff(data, diff)\n\nExposed statically on the LiveMysql object is a function for applying a `diff` given in an `update` event to an array of rows given in the `data` argument.\n\n## LiveMysqlSelect object\n\nEach call to the `select()` method on a LiveMysql object, returns a `LiveMysqlSelect` object with the following methods:\n\nMethod Name | Arguments | Description\n------------|-----------|-----------------------\n`on`, `addListener` | `event`, `handler` | Add an event handler to the result set. See the following section for a list of the available event names.\n`update`    | `callback` | Update the result set. Callback function accepts `error, rows` arguments. Events will be emitted.\n`stop`      | *None* | Stop receiving updates\n`active`    | *None* | Return `true` if ready to recieve updates, `false` if `stop()` method has been called.\n\nAs well as all of the other methods available on [`EventEmitter`](http://nodejs.org/api/events.html)...\n\n### Available Events\n\nEvent Name | Arguments | Description\n-----------|-----------|---------------------------\n`update` | `diff`, `data` | First argument contains an object describing the difference since the previous `update` event with `added`, `removed`, `moved`, and `copied` rows. Second argument contains complete result set array.\n`error` | `error` | Unhandled errors will be thrown\n\n## Running Tests\n\nTests must be run with a properly configured MySQL server. Configure test settings in `test/settings/mysql.js`.\n\nExecute [Nodeunit](https://github.com/caolan/nodeunit) using the `npm test` command.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtel%2Fmysql-live-select","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumtel%2Fmysql-live-select","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtel%2Fmysql-live-select/lists"}