{"id":42688,"library":"egg-mysql","title":"egg-mysql","description":"MySQL plugin for the Egg.js framework, providing a convenient wrapper around @eggjs/rds (ali-rds). Version 5.0.0 requires Node >=18.0.0. It supports both single and multiple data sources, CRUD operations, and manual/automatic transaction management. The plugin extends the app and agent with mysql/mysqls instances, enabling straightforward SQL queries. Key differentiators: tight integration with Egg.js lifecycle, singleton pattern for multiple DB clients, and full TypeScript type definitions.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/eggjs/egg-mysql","tags":["javascript","egg","eggPlugin","egg-plugin","mysql","database","typescript"],"install":[{"cmd":"npm install egg-mysql","lang":"bash","label":"npm"},{"cmd":"yarn add egg-mysql","lang":"bash","label":"yarn"},{"cmd":"pnpm add egg-mysql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underlying library for MySQL database operations","package":"@eggjs/rds","optional":false},{"reason":"Required peer dependency for Egg.js plugin compatibility","package":"egg","optional":true}],"imports":[{"note":"The plugin is not imported directly; it is configured in config/plugin.ts as an Egg.js plugin.","wrong":"// CommonJS require in plugin config (Egg.js supports ESM)\nconst mysql = require('egg-mysql');","symbol":"Plugin configuration","correct":"// config/plugin.ts\nexport default { mysql: { enable: true, package: 'egg-mysql' } };"},{"note":"The configuration must include 'client' object; using top-level fields directly is invalid.","wrong":"// Using 'mysql' property without proper structure\n{ mysql: { host: 'localhost', ... } }","symbol":"Single data source configuration","correct":"// config/config.default.ts\nexport default { mysql: { client: { host: 'localhost', port: '3306', user: 'root', password: 'pass', database: 'test' }, app: true } };"},{"note":"The plugin injects on app; do not import the package directly. app.mysql is available after enabling the plugin.","wrong":"const mysql = require('egg-mysql'); mysql.query(...);","symbol":"Usage with app.mysql","correct":"await app.mysql.query('SELECT * FROM users');"}],"quickstart":{"code":"// config/plugin.ts\nexport default {\n  mysql: {\n    enable: true,\n    package: 'egg-mysql',\n  },\n};\n\n// config/config.default.ts\nexport default {\n  mysql: {\n    client: {\n      host: process.env.MYSQL_HOST ?? 'localhost',\n      port: process.env.MYSQL_PORT ?? '3306',\n      user: process.env.MYSQL_USER ?? 'root',\n      password: process.env.MYSQL_PASSWORD ?? '',\n      database: process.env.MYSQL_DATABASE ?? 'test',\n    },\n    app: true,\n    agent: false,\n  },\n};\n\n// app.ts (or controller)\nimport { Application } from 'egg';\n\nexport default class PostController {\n  async index(ctx: any) {\n    const { app } = ctx;\n    const result = await app.mysql.query('SELECT NOW() as current_time');\n    ctx.body = result;\n  }\n}","lang":"typescript","description":"Configures egg-mysql plugin with a single MySQL connection, then uses app.mysql to run a query returning the current time."},"warnings":[{"fix":"Upgrade Node.js to 18 or later, or pin egg-mysql to 4.x for older Node versions.","message":"Version 5.0.0 requires Node >=18.0.0 and drops support for older Node versions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update package references and ensure @eggjs/rds is installed (it is bundled with egg-mysql).","message":"The internal library moved from ali-rds to @eggjs/rds. Old configurations may reference ali-rds directly.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Use @eggjs/rds directly if you need a standalone MySQL client.","message":"The plugin is exclusively for Egg.js framework; it cannot be used outside of an Egg application context.","severity":"gotcha","affected_versions":"all"},{"fix":"For single data source, use app.mysql. For multiple, use app.mysqls.get('db1').","message":"Configuration property 'mysqls' (plural) is only available after enabling multiple data sources via 'clients' config. Using it with 'client' (singular) will result in undefined.","severity":"gotcha","affected_versions":"all"},{"fix":"Add declare module 'egg' { interface Application { mysql: ... } } or import types from @eggjs/rds.","message":"In TypeScript, app.mysql type is inferred from @eggjs/rds; you might need to declare module augmentation for correct types.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'18.0.0':23 '5.0.0':20 'agent':44 'ali':17 'ali-rd':16 'app':42 'around':14 'client':64 'conveni':12 'crud':32 'data':30 'databas':77 'db':63 'definit':69 'differenti':53 'egg':2,71,74 'egg-mysql':1 'egg-plugin':73 'egg.js':8,57 'eggjs/rds':15 'eggplugin':72 'enabl':48 'extend':40 'framework':9 'full':66 'instanc':47 'integr':55 'javascript':70 'key':52 'lifecycl':58 'manag':37 'manual/automatic':35 'multipl':29,62 'mysql':3,4,76 'mysql/mysqls':46 'node':22 'oper':33 'pattern':60 'plugin':5,39,75 'provid':10 'queri':51 'rds':18 'requir':21 'singl':27 'singleton':59 'sourc':31 'sql':50 'straightforward':49 'support':25 'tight':54 'transact':36 'type':68 'typescript':67,78 'version':19 'wrapper':13","created_at":"2026-06-05T16:56:11.751621+00:00","updated_at":"2026-06-05T16:56:11.751621+00:00","problems":[{"fix":"Run `npm install egg-mysql --save` and ensure config/plugin.ts includes `exports.default = { mysql: { enable: true, package: 'egg-mysql' } };`","cause":"The plugin is not installed or not properly enabled in config/plugin.ts.","error":"Cannot find module 'egg-mysql'"},{"fix":"If using multiple clients, access via app.mysqls.get('db1'). Otherwise, ensure config uses 'client' not 'clients'.","cause":"Using app.mysql but the plugin is configured with multiple data sources (clients). In that case, use app.mysqls.get('clientId').query().","error":"TypeError: app.mysql.query is not a function"},{"fix":"Verify MYSQL_HOST and MYSQL_PORT in config or environment. Ensure MySQL server is running and firewall allows connection.","cause":"MySQL host/port configuration is incorrect or network is unreachable.","error":"Error: connect ETIMEDOUT ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/eggjs/egg-mysql#readme","github":"https://github.com/eggjs/egg-mysql","docs":null,"changelog":null,"pypi":null,"npm":"egg-mysql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}