egg-mysql

MySQL 插件是为 egg 提供 MySQL 数据库访问的功能

此插件基于 @eggjs/rds 实现一个简单的配置封装，具体使用方法你还需要阅读 @eggjs/rds 的文档。

安装

1npm i egg-mysql --save

配置

通过 config/plugin.ts 配置启动 MySQL 插件:

1export default {
2  mysql: {
3    enable: true,
4    package: 'egg-mysql',
5  },
6}

在 config/config.${env}.ts 配置各个环境的数据库连接信息：

单数据源

1export default {
2  mysql: {
3    // 单数据库信息配置
4    client: {
5      // host
6      host: 'mysql.com',
7      // 端口号
8      port: '3306',
9      // 用户名
10      user: 'test_user',
11      // 密码
12      password: 'test_password',
13      // 数据库名
14      database: 'test',    
15    },
16    // 是否加载到 app 上，默认开启
17    app: true,
18    // 是否加载到 agent 上，默认关闭
19    agent: false,
20  },
21}

使用方式：

1await app.mysql.query(sql, values); // 单实例可以直接通过 app.mysql 访问

多数据源

1export default {
2  mysql: {
3    clients: {
4      // clientId, 获取client实例，需要通过 app.mysql.get('clientId') 获取
5      db1: {
6        // host
7        host: 'mysql.com',
8        // 端口号
9        port: '3306',
10        // 用户名
11        user: 'test_user',
12        // 密码
13        password: 'test_password',
14        // 数据库名
15        database: 'test',
16      },
17      // ...
18    },
19    // 所有数据库配置的默认值
20    default: {
21
22    },
23
24    // 是否加载到 app 上，默认开启
25    app: true,
26    // 是否加载到 agent 上，默认关闭
27    agent: false,
28  },
29}

使用方式：

1const client1 = app.mysqls.get('db1');
2await client1.query(sql, values);
3
4const client2 = app.mysqls.get('db2');
5await client2.query(sql, values);

扩展

Application

app.mysql

如果开启了 config.mysql.app = true，则会在 app 上注入 @eggjs/rds 客户端 的 Singleton 单例。

1await app.mysql.query(sql);
2await app.mysqls.get('db1').query(sql);

Agent

agent.mysql

如果开启了 config.mysql.agent = true，则会在 agent 上注入 @eggjs/rds 客户端 的 Singleton 单例。

1await agent.mysql.query(sql);
2await agent.mysqls.get('db1').query(sql);

CRUD 使用指南

Create

1// 插入
2const result = await app.mysql.insert('posts', { title: 'Hello World' });
3const insertSuccess = result.affectedRows === 1;

Read

1// 获得一个
2const post = await app.mysql.get('posts', { id: 12 });
3// 查询
4const results = await app.mysql.select('posts',{
5  where: { status: 'draft' },
6  orders: [['created_at','desc'], ['id','desc']],
7  limit: 10,
8  offset: 0
9});

Update

1// 修改数据，将会根据主键 ID 查找，并更新
2const row = {
3  id: 123,
4  name: 'fengmk2',
5  otherField: 'other field value',
6  modifiedAt: app.mysql.literals.now, // `now()` on db server
7};
8const result = await app.mysql.update('posts', row);
9const updateSuccess = result.affectedRows === 1;

Delete

1const result = await app.mysql.delete('table-name', {
2  name: 'fengmk2'
3});

事务

手动控制

• 优点：beginTransaction, commit 或 rollback 都由开发者来完全控制，可以做到非常细粒度的控制。
• 缺点：手写代码比较多，不是每个人都能写好。忘记了捕获异常和 cleanup 都会导致严重 bug。

1const conn = await app.mysql.beginTransaction();
2
3try {
4  await conn.insert(table, row1);
5  await conn.update(table, row2);
6  await conn.commit();
7} catch (err) {
8  // error, rollback
9  await conn.rollback(); // rollback call won't throw err
10  throw err;
11}

自动控制：Transaction with scope

• API：async beginTransactionScope(scope, ctx)
  • scope: 一个 generatorFunction，在这个函数里面执行这次事务的所有 sql 语句。
  • ctx: 当前请求的上下文对象，传入 ctx 可以保证即便在出现事务嵌套的情况下，一次请求中同时只有一个激活状态的事务。
• 优点：使用简单，不容易犯错，就感觉事务不存在的样子。
• 缺点：整个事务要么成功，要么失败，无法做细粒度控制。

1const result = await app.mysql.beginTransactionScope(async (conn) => {
2  // don't commit or rollback by yourself
3  await conn.insert(table, row1);
4  await conn.update(table, row2);
5  return { success: true };
6}, ctx); // ctx 是当前请求的上下文，如果是在 service 文件中，可以从 `this.ctx` 获取到
7// if error throw on scope, will auto rollback

进阶

自定义SQL拼接

1const results = await app.mysql.query('update posts set hits = (hits + ?) where id = ?', [1, postId]);

表达式(Literal)

如果需要调用mysql内置的函数（或表达式），可以使用Literal。

内置表达式

• NOW(): 数据库当前系统时间，通过app.mysql.literals.now获取。

1await app.mysql.insert(table, {
2  create_time: app.mysql.literals.now
3});
4
5// INSERT INTO `$table`(`create_time`) VALUES(NOW())

自定义表达式

下例展示了如何调用mysql内置的CONCAT(s1, ...sn)函数，做字符串拼接。

1const Literal = app.mysql.literals.Literal;
2const first = 'James';
3const last = 'Bond';
4await app.mysql.insert(table, {
5  id: 123,
6  fullname: new Literal(`CONCAT("${first}", "${last}"`),
7});
8
9// INSERT INTO `$table`(`id`, `fullname`) VALUES(123, CONCAT("James", "Bond"))

Questions & Suggestions

Please open an issue here.

License

MIT

Contributors

Made with contributors-img.