egg-mysql-ex

library3.0.0-RC11jsnpmunverified

MySQL plugin for the Egg.js framework (current stable version: 2.x, latest 3.0.0-RC11). It provides a thin wrapper around ali-rds, offering convenient CRUD operations, connection pooling, and transaction support. Key differentiators: seamless integration with Egg.js lifecycle and configuration, supports multi-instance databases, and follows Egg's convention-over-configuration plugin model. Release cadence is irregular; major version updates may align with Egg.js breaking changes. Not to be confused with other MySQL libraries—this is Egg-specific and not a general-purpose driver.

database

npm install egg-mysql-ex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EGG-MYSQL-EX

egg-mysql-ex

databasejavascriptv3.0.0-RC11

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.

egg-mysql

✓ // No direct import; configured in plugin.js // config/plugin.js: exports.mysql = { enable: true, package: 'egg-mysql' };

✗ import mysql from 'egg-mysql';

egg-mysql is an Egg plugin, not imported directly in application code. It is loaded via Egg's plugin mechanism.

app.mysql

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

✗ const result = await app.mysql.query('SELECT * FROM users', callback);

app.mysql is available inside controller/service after plugin is enabled. Use async/await, not callbacks.

app.mysql.get()

✓ const client = app.mysql.get('db1'); const result = await client.query('SELECT * FROM users');

✗ const result = await app.mysql.get('db1').query('SELECT * FROM users');

Use for multi-instance clients. Ensure app.mysql is not undefined.

Enable egg-mysql plugin, configure a single MySQL client, and use app.mysql.query in a controller.

// config/plugin.js exports.mysql = { enable: true, package: 'egg-mysql', }; // config/config.default.js exports.mysql = { client: { host: 'localhost', port: '3306', user: 'test_user', password: process.env.MYSQL_PASSWORD ?? 'test_password', database: 'test', }, app: true, agent: false, }; // app/controller/home.js 'use strict'; const Controller = require('egg').Controller; class HomeController extends Controller { async index() { const { ctx, app } = this; const result = await app.mysql.query('SELECT 1+1 AS solution'); ctx.body = { solution: result[0].solution }; } } module.exports = HomeController;

Debug

Known issues

gotchaegg-mysql plugin must be enabled in config/plugin.js before it can be used; missing enable causes app.mysql to be undefined.

fix

Add exports.mysql = { enable: true, package: 'egg-mysql' } to config/plugin.js.

affects: >=1.0.0

gotchaUsing callbacks with app.mysql.query will not work as expected; promise-based async/await is required.

fix

Use async/await: const result = await app.mysql.query(sql);

affects: >=1.0.0

breakingTransition from egg-mysql v1 to v2+ changed the configuration schema for multi-instance; clients became a required key.

fix

Use exports.mysql = { clients: { db1: { ... } }, default: {...} } instead of exports.mysql = { db1: {...} }.

affects: >=2.0.0

gotchaTransaction methods (beginTransaction, commit, rollback) are experimental and may change behavior across minor versions.

fix

Wrap transaction calls in try/catch/finally and use manual control carefully; refer to ali-rds documentation.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot read property 'query' of undefined

The mysql plugin is not enabled or configured correctly, so app.mysql is undefined.

fix

Ensure config/plugin.js has exports.mysql = { enable: true, package: 'egg-mysql' }; and config/config.default.js has valid exports.mysql.client configuration.

app.mysql.get is not a function

Using app.mysql.get with a single client setup (not multi-instance). app.mysql.get is only available when clients configuration is used.

fix

Use app.mysql directly for single instance, or switch to clients configuration with multiple databases.

ER_ACCESS_DENIED_ERROR: Access denied for user 'test_user'@'localhost'

Incorrect MySQL credentials or host/port.

fix

Verify MySQL host, port, user, password in config/config.default.js.

Upgrade

Version history

3.0.0-RC11latest on npm

Audit

Dependencies

ali-rdsrequiredCore underlying MySQL client library providing MySQL protocol support and connection management.

Agent activity

7 hits · last 30 days

node

Resources

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

packageegg-mysql-ex ↗

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