基本用法

TIP

ctx.database 并非内置服务，因此如果你的插件需要使用数据库功能，需要声明依赖。

对于几乎所有大型机器人项目，数据库的使用都是不可或缺的。但如果每个插件都独立处理与数据库的交互，这将导致插件之间的兼容性非常差——用户要么选择同时安装多个数据库，要么只能放弃一些功能。为此，Koishi 设计了一整套对象关系映射 (ORM) 接口，它易于扩展并广泛地运用于各种插件中，足以应对绝大部分使用场景。

get：查询数据

使用 database.get() 方法以获取特定表中的数据。下面是一个最基本的形式：

// 获取 schedule 表中 id 为 1234 的数据行，返回一个数组
await ctx.database.get('schedule', 1234)

// 获取 schedule 表中 id 为 1234 或 5678 的数据行，返回一个数组
await ctx.database.get('schedule', [1234, 5678])

对于复杂的数据表，如果你只需要获取少数字段，你可以通过第三个参数手动指定要获取的字段：

// 返回的数组中每个元素只会包含 command, time 属性
await ctx.database.get('schedule', [1234], ['command', 'time'])

你还可以向第二个参数传入一个对象，用来查询非主键上的数据或者同时指定多列的值：

// 获取名为 schedule 的表中 assignee 为 telegram:123456 的数据行
await ctx.database.get('schedule', {
  assignee: ['telegram:123456'],
})

对于需要进行复杂的数据库搜索的，ORM 也提供了相对应的方法：

// 获取名为 schedule 的表中 id 大于 2 但是小于等于 5 的数据行
await ctx.database.get('schedule', {
  id: { $gt: 2, $lte: 5 },
})

我们甚至也支持逻辑运算：

// 上述两个搜索条件的或运算
await ctx.database.get('schedule', {
  $or: [
    { assignee: ['telegram:123456'] },
    { id: { $gt: 2, $lte: 5 } },
  ],
})

你可以在 这里 看到完整的查询表达式 API。

create：插入数据

使用 database.create() 方法以插入数据。

// 向 schedule 表中添加一行数据，data 是要添加的数据行
// 返回值是添加的行的完整数据 (包括自动填充的 id 和默认属性等)
await ctx.database.create('schedule', row)

如果你想要批量插入数据，可以使用下面介绍的 database.upsert() 方法。

set：修改数据

database.set() 方法需要传入三个参数：表名、查询条件和要修改的数据。

// 第二个参数也可以使用上面介绍的查询表达式
await ctx.database.set('schedule', 1234, {
  assignee: 'telegram:123456',
  time: new Date(),
})

如果要修改的数据与已有数据相关，可以使用求值表达式：

// 让所有日期为今天的数据行的 count 字段在原有基础上增加 1
await ctx.database.set('foo', { date: new Date() }, (row) => ({
  // { $add: [a, b] } 相当于 a + b
  // { $: field } 相当于对当前行的 field 字段取值
  count: $.add(row.count, 1),
}))

你可以在 这里 看到完整的求值表达式 API。

upsert：修改或插入数据

database.upsert() 的逻辑稍微有些不同，需要你传入一个数组：

// 用一个数组来对数据进行更新，你需要确保每一个元素都拥有这个数据表的主键
// 修改时只会用每一行中出现的键进行覆盖，不会影响未定义的字段
await ctx.database.upsert('foo', [
  { id: 1, foo: 'hello' },
  { id: 2, foo: 'world' },
  // 这里同样支持求值表达式，$concat 可用于连接字符串
  { id: 3, bar: { $concat: ['koi', 'shi'] } },
])

如果初始的数据库是这样的：

id	foo	bar
(默认值)	null	bar
1	foo	baz

那么进行上述操作后的数据库将是这样的：

id	foo	bar	说明
1	hello	baz	该行已经存在，只更新了 foo 字段
2	world	bar	插入了新行，其中 foo 字段取自传入的数据，bar 字段取自默认值
3	null	koishi	插入了新行，其中 bar 字段取自传入的数据，foo 字段取自默认值

如果想以非主键来索引要修改的数据，可以使用第三个参数：

// @errors: 2304
// 以非主键为基准对数据表进行更新，你需要确保每一个元素都拥有 telegram 属性
await ctx.database.upsert('user', rows, 'telegram')

// 以复合键为基准对数据表进行更新，你需要确保每一个元素都拥有 platform 和 id 属性
await ctx.database.upsert('channel', rows, ['platform', 'id'])

remove：删除数据

使用 database.remove() 方法以删除特定表中的数据。

// 从 schedule 表中删除特定 id 的数据行
// 第二个参数也可以使用上面介绍的查询表达式
await ctx.database.remove('schedule', [id])

获取改动行数

set, upsert 和 remove 操作都会返回一个 WriteResult 对象，它包含了这次操作的结果。你可以通过 matched 属性来获取匹配的数据行数 (注意不是修改的函数)，通过 inserted 属性来获取插入的数据行数 (仅限 upsert 操作)。

// 对某个用户的余额进行扣除
const result = await ctx.database.set(
  'user',
  { id, money: { $gte: 100 } },
  (row) => ({ money: $.sub(row.money, 100) }),
)
// 如果用户不存在或余额不足，此时 result.matched 为 0
if (!result.matched) {
  throw new Error('用户不存在或余额不足！')
}

对比 set 和 upsert

set 与 upsert 方法都可以用于修改已经存在的数据，它们的区别如下表所示：

	set	upsert
作用范围	支持复杂的查询表达式	只能限定特定字段的值
插入行为	如果数据不存在则不会进行任何操作	如果数据不存在则会插入新行

对比 create 和 upsert

create 与 upsert 方法都可以用于插入新的数据，它们的区别如下表所示：

	create	upsert
插入数量	只能插入一条数据	可以批量插入多条数据
return value	返回经过填充后的数据	没有返回值
冲突行为	如果数据已存在则会报错	如果数据已存在则会执行修改