MySQL Easy Query

一个简洁的 MySQL 查询封装库，基于 mysql2 和 sql-easy-builder，自动管理连接获取与释放。

安装

npm i mysql-easy-query

v4.0 起为 ESM 模块，使用 import 导入。

创建连接池

单连接池

传入一个 pool 配置时，返回 PoolQuery 实例：

import { createPoolCompatible } from 'mysql-easy-query';

const pool = createPoolCompatible({
  pools: {
    master: {
      host: '127.0.0.1',
      user: 'root',
      database: 'test',
      password: '123456',
    }
  }
});

集群连接池（主从分离）

传入多个 pool 配置时，自动创建 PoolCluster，返回 PoolClusterQueryOf 实例：

const pool = createPoolCompatible({
  cluster: { /* mysql2 PoolClusterOptions */ },
  pools: {
    MASTER: { host: 'master.db', user: 'root', database: 'test', password: '***' },
    SLAVE1: { host: 'slave1.db', user: 'root', database: 'test', password: '***' },
    SLAVE2: { host: 'slave2.db', user: 'root', database: 'test', password: '***' },
  }
});

查询

所有 pool 级别的方法都会自动获取连接、执行完毕后自动释放，无需手动管理。

原始 SQL

const users = await pool.query('SELECT * FROM user WHERE id = ?', [1]);

Builder 回调

使用 sql-easy-builder 构建查询，更加安全便捷：

// 查询列表
const users = await pool.query(b => {
  b.select().from('user').where({ status: 1 }).orderBy('id', 'DESC').limit(10);
});

// 查询单条（使用 one()）
const user = await pool.query(b => {
  b.select().from('user').where({ id: 1 }).one();
});

// 插入
await pool.query(b => b.insert('user', { name: 'Alice', age: 20 }));

// 更新
await pool.query(b => b.update('user', { name: 'Bob' }).where({ id: 1 }));

// 删除
await pool.query(b => b.delete('user').where({ id: 1 }));

// 统计数量
const count = await pool.auto(q => q.count('user', { status: 1 }));

事务

transaction 自动处理 commit/rollback：成功则提交，异常则回滚并抛出错误。连接同样会自动释放。

await pool.transaction(async q => {
  await q.query(b => b.update('account', { balance: 100 }).where({ uid: 1 }));
  await q.query(b => b.insert('log', { action: 'transfer', uid: 1 }));
});

集群读写分离

通过 of(pattern, selector) 选择目标池：

// 写操作走主库
await pool.of('MASTER').query('INSERT INTO user SET ?', { name: 'Alice' });

// 读操作走从库（随机选择）
await pool.of('SLAVE*', 'RANDOM').query('SELECT * FROM user');

| 参数 | 说明 | 默认值 | |------|------|--------| | pattern | 池匹配模式，如 'MASTER'、'SLAVE*'、'*' | '*' | | selector | 选择策略：'RR'（轮询）、'RANDOM'（随机）、'ORDER'（顺序） | 'RR' |

连接初始化钩子

每次从连接池获取连接后执行，常用于设置字符集：

import { Query } from 'mysql-easy-query';

pool.getPoolConnectionAfter(conn => {
  return new Query(conn).query('SET NAMES "utf8"');
});

手动管理连接

如需更细粒度的控制，可手动获取连接：

const conn = await pool.getPoolConnection();
try {
  const q = new Query(conn);
  await q.query('SELECT 1+1');
} finally {
  conn.release();
}

调试

通过环境变量启用调试日志，可查看连接获取、SQL 执行、连接释放等信息：

DEBUG=mysql-easy-query node app.js

API 一览

| 方法 | 说明 | |------|------| | pool.query(sql, params?) | 执行查询，自动管理连接 | | pool.auto(callback) | 获取连接执行回调，自动释放 | | pool.transaction(callback) | 自动事务（commit/rollback） | | pool.getPoolConnection() | 获取原始连接（需手动释放） | | pool.getPoolConnectionAfter(fn) | 连接获取后的初始化钩子 | | pool.of(pattern?, selector?) | 选择集群目标池 | | pool.end() | 关闭连接池 | | q.count(table, where?) | 统计行数 | | q.builder() | 创建新的 Builder 实例 |

相关项目

• sql-easy-builder — SQL 构建器
• ZenORM — 基于 mysql-easy-query 的 ORM

License

MIT