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.

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.