AdonisJS 中文文档

主题

Lucid ORM ​

Lucid 是一个 SQL 查询构建器和 Active Record ORM，建立在 Knex 之上，由 AdonisJS 核心团队创建和维护。Lucid 致力于充分发挥 SQL 的潜力，并为许多高级 SQL 操作提供简洁的 API。

TIP

Lucid 的文档可在 https://lucid.adonisjs.com 获取

为什么选择 Lucid ​

以下是一些精选的 Lucid 特性。

  • 建立在 Knex 之上的流畅查询构建器。
  • 支持读写副本和多连接管理。
  • 遵循 active record 模式的基于类的模型（处理关系、序列化和钩子）。
  • 使用增量变更集修改数据库架构的迁移系统。
  • 用于为测试生成假数据的模型工厂。
  • 用于向数据库插入初始/虚拟数据的数据库播种器。

除此之外，以下是在 AdonisJS 应用程序中使用 Lucid 的其他原因。

  • 我们为 Lucid 与 Auth 包和验证器提供一流的集成。因此，你不必自己编写这些集成。

  • Lucid 预配置在 api 和 web 入门套件中，为你的应用程序提供一个良好的开端。

  • Lucid 的主要目标之一是充分发挥 SQL 的潜力，并支持许多高级 SQL 操作，如窗口函数、递归 CTE、JSON 操作、行级锁等。

  • Lucid 和 Knex 都已经存在多年。因此，与许多其他新的 ORM 相比，它们更加成熟和经过实战检验。

话虽如此，AdonisJS 不强制你使用 Lucid。只需卸载该包并安装你选择的 ORM。

安装 ​

使用以下命令安装和配置 Lucid。

sh
node ace add @adonisjs/lucid

:::disclosure

  1. 在 adonisrc.ts 文件中注册以下服务提供者。

    ts
    {
  providers: [
    // ...其他提供者
    () => import('@adonisjs/lucid/database_provider'),
  ]
}

  2. 在 adonisrc.ts 文件中注册以下命令。

    ts
    {
  commands: [
    // ...其他命令
    () => import('@adonisjs/lucid/commands'),
  ]
}

  3. 创建 config/database.ts 文件。

  4. 为选定的方言定义环境变量及其验证。

  5. 安装所需的对等依赖项。

:::

创建你的第一个模型 ​

配置完成后，你可以使用以下命令创建你的第一个模型。

sh
node ace make:model User

此命令在 app/models 目录中创建一个新文件，内容如下。

ts
import { DateTime } from 'luxon'
import { BaseModel, column } from '@adonisjs/lucid/orm'

export default class User extends BaseModel {
  @column({ isPrimary: true })
  declare id: number

  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime
}

访问官方文档了解更多关于模型的信息。

迁移 ​

迁移是使用增量变更集修改数据库架构和数据的方法。你可以使用以下命令创建新迁移。

sh
node ace make:migration users

此命令在 database/migrations 目录中创建一个新文件，内容如下。

ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

  async down() {
    this.schema.dropTable(this.tableName)
  }
}

你可以使用以下命令运行所有待处理的迁移。

sh
node ace migration:run

访问官方文档了解更多关于迁移的信息。

查询构建器 ​

Lucid 附带一个建立在 Knex 之上的流畅查询构建器。你可以使用查询构建器对数据库执行 CRUD 操作。

ts
import db from '@adonisjs/lucid/services/db'

/**
 * 创建查询构建器实例
 */
const query = db.query()

/**
 * 创建查询构建器实例并选择表
 */
const queryWithTableSelection = db.from('users')

查询构建器也可以限定为模型实例。

ts
import User from '#models/user'

const user = await User.query().where('username', 'rlanz').first()

访问官方文档了解更多关于查询构建器的信息。

CRUD 操作 ​

Lucid 模型具有内置方法来对数据库执行 CRUD 操作。

ts
import User from '#models/user'

/**
 * 创建新用户
 */
const user = await User.create({
  username: 'rlanz',
  email: 'romain@adonisjs.com',
})

/**
 * 通过主键查找用户
 */
const user = await User.find(1)

/**
 * 更新用户
 */

const user = await User.find(1)
user.username = 'romain'
await user.save()

/**
 * 删除用户
 */
const user = await User.find(1)
await user.delete()

访问官方文档了解更多关于 CRUD 操作的信息。

了解更多 ​