{"id":26659798,"url":"https://github.com/eggjs/mysql","last_synced_at":"2025-05-15T13:06:04.625Z","repository":{"id":10747769,"uuid":"66625938","full_name":"eggjs/mysql","owner":"eggjs","description":"MySQL plugin for egg","archived":false,"fork":false,"pushed_at":"2025-03-23T12:47:38.000Z","size":94,"stargazers_count":332,"open_issues_count":0,"forks_count":60,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-06T06:22:58.353Z","etag":null,"topics":["egg","egg-mysql","egg-plugin","mysql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/eggjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-26T07:20:17.000Z","updated_at":"2025-05-03T06:53:49.000Z","dependencies_parsed_at":"2023-01-13T16:07:46.362Z","dependency_job_id":"3c31d7e2-32c1-442d-99ff-ccf51314a7da","html_url":"https://github.com/eggjs/mysql","commit_stats":{"total_commits":42,"total_committers":14,"mean_commits":3.0,"dds":0.6904761904761905,"last_synced_commit":"70b96835d3cf80a1b277d1894a63a1891d75aac3"},"previous_names":["eggjs/mysql"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fmysql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fmysql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fmysql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fmysql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eggjs","download_url":"https://codeload.github.com/eggjs/mysql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253434713,"owners_count":21907959,"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":["egg","egg-mysql","egg-plugin","mysql"],"created_at":"2025-03-25T11:07:08.942Z","updated_at":"2025-05-15T13:06:04.605Z","avatar_url":"https://github.com/eggjs.png","language":"TypeScript","readme":"# @eggjs/mysql\n\n[![NPM version][npm-image]][npm-url]\n[![CI](https://github.com/eggjs/mysql/actions/workflows/nodejs.yml/badge.svg?branch=master)](https://github.com/eggjs/mysql/actions/workflows/nodejs.yml)\n[![Test coverage][codecov-image]][codecov-url]\n[![npm download][download-image]][download-url]\n[![Node.js Version](https://img.shields.io/node/v/@eggjs/mysql.svg?style=flat)](https://nodejs.org/en/download/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/eggjs/mysql)\n\n[npm-image]: https://img.shields.io/npm/v/@eggjs/mysql.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/@eggjs/mysql\n[codecov-image]: https://img.shields.io/codecov/c/github/eggjs/mysql.svg?style=flat-square\n[codecov-url]: https://codecov.io/github/eggjs/mysql?branch=master\n[download-image]: https://img.shields.io/npm/dm/@eggjs/mysql.svg?style=flat-square\n[download-url]: https://npmjs.org/package/@eggjs/mysql\n\nMySQL plugin for Egg.js\n\n## Install\n\n```bash\nnpm i @eggjs/mysql\n```\n\nMySQL Plugin for `egg@4`, support egg application access to MySQL database.\n\n\u003e If you're using `egg@3`, please use `egg-mysql@5` instead.\n\nThis plugin based on [@eggjs/rds], if you want to know specific usage, you should refer to the document of [@eggjs/rds].\n\n## Configuration\n\nChange `${app_root}/config/plugin.ts` to enable MySQL plugin:\n\n```ts\nexport default {\n  mysql: {\n    enable: true,\n    package: '@eggjs/mysql',\n  },\n};\n```\n\nConfigure database information in `${app_root}/config/config.default.ts`:\n\n### Simple database instance\n\n```ts\nexport default {\n  mysql: {\n    // database configuration\n    client: {\n      // host\n      host: 'mysql.com',\n      // port\n      port: '3306',\n      // username\n      user: 'test_user',\n      // password\n      password: 'test_password',\n      // database\n      database: 'test',\n    },\n    // load into app, default is `true`\n    app: true,\n    // load into agent, default is `false`\n    agent: false,\n  },\n};\n```\n\nUsage:\n\n```ts\nawait app.mysql.query(sql, values); // you can access to simple database instance by using app.mysql.\n```\n\n### Multiple database instance\n\n```ts\nexport default {\n  mysql: {\n    clients: {\n      // clientId, access the client instance by app.mysql.get('clientId')\n      db1: {\n        // host\n        host: 'mysql.com',\n        // port\n        port: '3306',\n        // username\n        user: 'test_user',\n        // password\n        password: 'test_password',\n        // database\n        database: 'test',\n      },\n      // ...\n    },\n    // default configuration for all databases\n    default: {},\n    // load into app, default is open\n    app: true,\n    // load into agent, default is close\n    agent: false,\n  },\n};\n```\n\nUsage:\n\n```ts\nconst client1 = app.mysqls.getSingletonInstance('db1');\nawait client1.query(sql, values);\n\nconst client2 = app.mysqls.getSingletonInstance('db2');\nawait client2.query(sql, values);\n```\n\n## CRUD user guide\n\n### Create\n\n```ts\n// insert\nconst result = await app.mysql.insert('posts', { title: 'Hello World' });\nconst insertSuccess = result.affectedRows === 1;\n```\n\n### Read\n\n```ts\n// get\nconst post = await app.mysql.get('posts', { id: 12 });\n// query\nconst results = await app.mysql.select('posts', {\n  where: { status: 'draft' },\n  orders: [\n    ['created_at', 'desc'],\n    ['id', 'desc'],\n  ],\n  limit: 10,\n  offset: 0,\n});\n```\n\n### Update\n\n```ts\n// update by primary key ID, and refresh\nconst row = {\n  id: 123,\n  name: 'fengmk2',\n  otherField: 'other field value',\n  modifiedAt: app.mysql.literals.now, // `now()` on db server\n};\nconst result = await app.mysql.update('posts', row);\nconst updateSuccess = result.affectedRows === 1;\n```\n\n### Delete\n\n```ts\nconst result = await app.mysql.delete('table-name', {\n  name: 'fengmk2',\n});\n```\n\n## Transaction\n\n### Manual control\n\n- adventage: `beginTransaction`, `commit` or `rollback` can be completely under control by developer\n- disadventage: more handwritten code, Forgot catching error or cleanup will lead to serious bug.\n\n```ts\nconst conn = await app.mysql.beginTransaction();\n\ntry {\n  await conn.insert(table, row1);\n  await conn.update(table, row2);\n  await conn.commit();\n} catch (err) {\n  // error, rollback\n  await conn.rollback(); // rollback call won't throw err\n  throw err;\n}\n```\n\n### Automatic control: Transaction with scope\n\n- API：`async beginTransactionScope(scope, ctx)`\n  - `scope`: A generatorFunction which will execute all sqls of this transaction.\n  - `ctx`: The context object of current request, it will ensures that even in the case of a nested transaction, there is only one active transaction in a request at the same time.\n- adventage: easy to use, as if there is no transaction in your code.\n- disadvantage: all transation will be successful or failed, cannot control precisely\n\n```ts\nconst result = await app.mysql.beginTransactionScope(async conn =\u003e {\n  // don't commit or rollback by yourself\n  await conn.insert(table, row1);\n  await conn.update(table, row2);\n  return { success: true };\n}, ctx); // ctx is the context of current request, access by `this.ctx`.\n// if error throw on scope, will auto rollback\n```\n\n## Advance\n\n### Custom SQL splicing\n\n```ts\nconst results = await app.mysql.query(\n  'update posts set hits = (hits + ?) where id = ?',\n  [1, postId]\n);\n```\n\n### Literal\n\nIf you want to call literals or functions in mysql , you can use `Literal`.\n\n#### Inner Literal\n\n- NOW(): The database system time, you can obtain by `app.mysql.literals.now`.\n\n```ts\nawait app.mysql.insert(table, {\n  create_time: app.mysql.literals.now,\n});\n\n// INSERT INTO `$table`(`create_time`) VALUES(NOW())\n```\n\n#### Custom literal\n\nThe following demo showed how to call `CONCAT(s1, ...sn)` function in mysql to do string splicing.\n\n```ts\nconst Literal = app.mysql.literals.Literal;\nconst first = 'James';\nconst last = 'Bond';\nawait app.mysql.insert(table, {\n  id: 123,\n  fullname: new Literal(`CONCAT(\"${first}\", \"${last}\"`),\n});\n\n// INSERT INTO `$table`(`id`, `fullname`) VALUES(123, CONCAT(\"James\", \"Bond\"))\n```\n\n## For the local dev\n\nRun docker compose to start test mysql service\n\n```bash\ndocker compose -f docker-compose.yml up -d\n# if you run the first time, should wait for ~20s to let mysql service init started\n```\n\nRun the unit tests\n\n```bash\nnpm test\n```\n\nStop test mysql service\n\n```bash\ndocker compose -f docker-compose.yml down\n```\n\n## Questions \u0026 Suggestions\n\nPlease open an issue [here](https://github.com/eggjs/mysql/issues).\n\n## License\n\n[MIT](LICENSE)\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=eggjs/mysql)](https://github.com/eggjs/mysql/graphs/contributors)\n\nMade with [contributors-img](https://contrib.rocks).\n\n[@eggjs/rds]: https://github.com/node-modules/rds\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fmysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feggjs%2Fmysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fmysql/lists"}