egg-mysql

library5.0.0jsnpmunverified

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.

database

npm install egg-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EGG-MYSQL

egg-mysql

databasejavascriptv5.0.0

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.

Plugin configuration

✓ // config/plugin.ts export default { mysql: { enable: true, package: 'egg-mysql' } };

✗ // CommonJS require in plugin config (Egg.js supports ESM) const mysql = require('egg-mysql');

The plugin is not imported directly; it is configured in config/plugin.ts as an Egg.js plugin.

Single data source configuration

✓ // config/config.default.ts export default { mysql: { client: { host: 'localhost', port: '3306', user: 'root', password: 'pass', database: 'test' }, app: true } };

✗ // Using 'mysql' property without proper structure { mysql: { host: 'localhost', ... } }

The configuration must include 'client' object; using top-level fields directly is invalid.

Usage with app.mysql

✓ await app.mysql.query('SELECT * FROM users');

✗ const mysql = require('egg-mysql'); mysql.query(...);

The plugin injects on app; do not import the package directly. app.mysql is available after enabling the plugin.

Configures egg-mysql plugin with a single MySQL connection, then uses app.mysql to run a query returning the current time.

// config/plugin.ts export default { mysql: { enable: true, package: 'egg-mysql', }, }; // config/config.default.ts export default { mysql: { client: { host: process.env.MYSQL_HOST ?? 'localhost', port: process.env.MYSQL_PORT ?? '3306', user: process.env.MYSQL_USER ?? 'root', password: process.env.MYSQL_PASSWORD ?? '', database: process.env.MYSQL_DATABASE ?? 'test', }, app: true, agent: false, }, }; // app.ts (or controller) import { Application } from 'egg'; export default class PostController { async index(ctx: any) { const { app } = ctx; const result = await app.mysql.query('SELECT NOW() as current_time'); ctx.body = result; } }

Debug

Known issues

breakingVersion 5.0.0 requires Node >=18.0.0 and drops support for older Node versions.

fix

Upgrade Node.js to 18 or later, or pin egg-mysql to 4.x for older Node versions.

affects: >=5.0.0

deprecatedThe internal library moved from ali-rds to @eggjs/rds. Old configurations may reference ali-rds directly.

fix

Update package references and ensure @eggjs/rds is installed (it is bundled with egg-mysql).

affects: >=4.0.0

gotchaThe plugin is exclusively for Egg.js framework; it cannot be used outside of an Egg application context.

fix

Use @eggjs/rds directly if you need a standalone MySQL client.

affects: all

gotchaConfiguration property 'mysqls' (plural) is only available after enabling multiple data sources via 'clients' config. Using it with 'client' (singular) will result in undefined.

fix

For single data source, use app.mysql. For multiple, use app.mysqls.get('db1').

affects: all

gotchaIn TypeScript, app.mysql type is inferred from @eggjs/rds; you might need to declare module augmentation for correct types.

fix

Add declare module 'egg' { interface Application { mysql: ... } } or import types from @eggjs/rds.

affects: >=5.0.0

Errors

Common errors & fixes

Cannot find module 'egg-mysql'

The plugin is not installed or not properly enabled in config/plugin.ts.

fix

Run `npm install egg-mysql --save` and ensure config/plugin.ts includes `exports.default = { mysql: { enable: true, package: 'egg-mysql' } };`

TypeError: app.mysql.query is not a function

Using app.mysql but the plugin is configured with multiple data sources (clients). In that case, use app.mysqls.get('clientId').query().

fix

If using multiple clients, access via app.mysqls.get('db1'). Otherwise, ensure config uses 'client' not 'clients'.

Error: connect ETIMEDOUT ...

MySQL host/port configuration is incorrect or network is unreachable.

fix

Verify MYSQL_HOST and MYSQL_PORT in config or environment. Ensure MySQL server is running and firewall allows connection.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

@eggjs/rdsrequiredUnderlying library for MySQL database operations

eggoptionalRequired peer dependency for Egg.js plugin compatibility

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/eggjs/egg-mysql ↗

packageegg-mysql ↗

homepagehttps://github.com/eggjs/egg-mysql#readme ↗