lucid

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lucid

Use this skill for the Lucid database layer in AdonisJS applications. Lucid is database-first: migrations change the database, Lucid generates

database/schema.ts

, and models extend generated schema classes while declaring relationships, hooks, scopes, serialization, and domain behavior.

When a task also touches controllers, routes, validators, policies, services, or broader AdonisJS architecture, use

adonisjs

alongside this skill. When writing tests around Lucid behavior, use

japa

alongside this skill.

本技能适用于AdonisJS应用中的Lucid数据库层。Lucid采用database-first模式：迁移操作修改数据库，Lucid生成

database/schema.ts

，模型继承生成的Schema类，同时声明关联、钩子、作用域、序列化和领域行为。

当任务同时涉及控制器、路由、验证器、策略、服务或更广泛的AdonisJS架构时，请结合

adonisjs

技能使用。当针对Lucid行为编写测试时，请结合

japa

技能使用。

Core Rules

核心规则

Treat the database as the source of truth.
Write schema changes in migrations, then run migrations or
```
schema:generate
```
to refresh
```
database/schema.ts
```
.
Do not manually edit generated
```
database/schema.ts
```
.
Model files should usually extend generated schema classes and contain relationships, hooks, scopes, serialization overrides, and domain methods.
Use the
```
db
```
service for SQL-heavy queries, reports, one-off scripts, or when model hydration is unnecessary.
Use model queries when you need Active Record behavior, relationships, hooks, scopes, serialization, or model instances.
Prefer managed transactions with
```
db.transaction(async (trx) => ...)
```
unless the transaction lifetime must cross function boundaries.
Always scope destructive update/delete queries with
```
where
```
clauses.
Preload relationships instead of querying inside loops.
Use
```
withCount
```
,
```
withAggregate
```
,
```
has
```
, and
```
whereHas
```
for relationship-aware filtering and aggregates.

将数据库视为事实来源。
在迁移中编写Schema变更，然后运行迁移或执行
```
schema:generate
```
命令刷新
```
database/schema.ts
```
。
不要手动编辑生成的
```
database/schema.ts
```
。
模型文件通常应继承生成的Schema类，并包含关联、钩子、作用域、序列化覆盖和领域方法。
对于SQL密集型查询、报表、一次性脚本或无需模型实例化的场景，使用
```
db
```
服务。
当需要Active Record行为、关联、钩子、作用域、序列化或模型实例时，使用模型查询。
除非事务生命周期必须跨函数边界，否则优先使用
```
db.transaction(async (trx) => ...)
```
进行托管事务。
破坏性的更新/删除查询必须始终通过
```
where
```
子句限定作用域。
预加载关联，而非在循环内执行查询。
使用
```
withCount
```
、
```
withAggregate
```
、
```
has
```
和
```
whereHas
```
实现关联感知的过滤和聚合。

Workflow

工作流程

For feature work that changes persisted data:

Identify existing tables, generated schema classes, models, and relationships.
Write or update migrations first.
Run the migration or note the command required to regenerate
```
database/schema.ts
```
.
Update models to extend the generated schema class and add Lucid-only behavior.
Add or update relationships with explicit keys when conventions do not match.
Use query builders, scopes, or factories based on the access pattern.
Verify with focused tests or a typecheck command available in the repo.

For existing-database adoption:

Configure the connection.
Exclude unmanaged tables in
```
schemaGeneration.excludeTables
```
.
Run
```
node ace schema:generate
```
.
Create models only for tables the application owns.
Handle convention mismatches with schema rules or model-level overrides.

针对需要修改持久化数据的功能开发：

识别现有表、生成的Schema类、模型和关联。
首先编写或更新迁移。
运行迁移，或记录重新生成
```
database/schema.ts
```
所需的命令。
更新模型以继承生成的Schema类，并添加Lucid专属行为。
当约定不匹配时，使用显式键添加或更新关联。
根据访问模式选择使用查询构建器、作用域或工厂。
通过聚焦测试或仓库中可用的类型检查命令验证。

针对现有数据库适配场景：

配置连接。
在
```
schemaGeneration.excludeTables
```
中排除非托管表。
运行
```
node ace schema:generate
```
命令。
仅为应用拥有的表创建模型。
通过Schema规则或模型级覆盖处理约定不匹配的情况。

Choosing the Right API

选择合适的API

Need	Prefer
Table creation or schema change	Migration with `BaseSchema`
Typed model columns	Generated schema class from `database/schema.ts`
Domain behavior on rows	Model methods and hooks
Relationship loading/filtering	Model query builder
Reports or SQL-heavy reads	`db.from` , `db.query` , raw query builder
Multi-write consistency	Managed transaction
Test data	Model factories
Initial/dev data	Database seeders

需求	优先选择
表创建或Schema变更	基于 `BaseSchema` 的迁移
带类型的模型列	从 `database/schema.ts` 生成的Schema类
行级领域行为	模型方法和钩子
关联加载/过滤	模型查询构建器
报表或SQL密集型读取	`db.from` 、 `db.query` 、原生查询构建器
多写入一致性	托管事务
测试数据	模型工厂
初始/开发环境数据	数据库种子数据

References

参考资料

Load the relevant local reference before implementing:

```
references/schema-and-models.md
```
for migrations, schema generation, schema classes, CRUD, scopes, hooks, and serialization.
```
references/query-builders.md
```
for
```
db
```
service queries, model query builder behavior, pagination, raw SQL, and debugging.
```
references/transactions.md
```
for managed/manual transactions, isolation, savepoints, row locks, model transactions, and relationship writes inside transactions.

references/relationships.md

for

belongsTo

hasOne

hasMany

manyToMany

hasManyThrough

, preloads, relationship filters, aggregates, and writes.

```
references/testing.md
```
for test database state, factories, factory relationships, pivot attributes, hooks, and seeders.

Each reference contains the essential working patterns first and links to the deeper official Lucid docs at the end.

在实现前加载相关本地参考：

```
references/schema-and-models.md
```
：涵盖迁移、Schema生成、Schema类、CRUD、作用域、钩子和序列化。
```
references/query-builders.md
```
：涵盖
```
db
```
服务查询、模型查询构建器行为、分页、原生SQL和调试。
```
references/transactions.md
```
：涵盖托管/手动事务、隔离级别、保存点、行锁、模型事务以及事务内的关联写入。

references/relationships.md

：涵盖

belongsTo

、

hasOne

、

hasMany

、

manyToMany

、

hasManyThrough

、预加载、关联过滤、聚合和写入。

```
references/testing.md
```
：涵盖测试数据库状态、工厂、工厂关联、中间表属性、钩子和种子数据。

每个参考资料首先包含核心工作模式，末尾链接到更深入的Lucid官方文档。

Anti-Patterns

反模式

Avoid	Prefer
Editing `database/schema.ts` by hand	Migrations, schema rules, or model overrides
Declaring every column manually in model files	Extend the generated `*Schema` class
Running relationship queries inside loops	`preload` , nested preloads, `withCount` , `withAggregate`
Unscoped `update` or `delete`	Always include explicit `where` constraints
Manual transactions for simple operations	Managed `db.transaction` callback
Mocking Lucid query behavior for integration paths	Use Japa with test DB/factories
Using models for every report query	Use the `db` service when plain rows are enough

避免做法	优先选择
手动编辑 `database/schema.ts`	迁移、Schema规则或模型覆盖
在模型文件中手动声明每个列	继承生成的 `*Schema` 类
在循环内执行关联查询	`preload` 、嵌套预加载、 `withCount` 、 `withAggregate`
无作用域的 `update` 或 `delete`	始终包含显式 `where` 约束
简单操作使用手动事务	托管式 `db.transaction` 回调
为集成路径模拟Lucid查询行为	使用Japa结合测试数据库/工厂
所有报表查询都使用模型	当只需普通行数据时使用 `db` 服务