Lucid

https://lucid.adonisjs.com/docs
Admin
Lucid is a SQL query builder and an Active Record ORM built on top of Knex, providing a fluent API...
Tokens:182,243
Snippets:1,684
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### migration:status output example

Source: https://lucid.adonisjs.com/docs/commands

Example output of the migration:status command, showing a table with columns Name, Status, Batch, and Message.

```text
┌───────────────────────────────────────────────┬───────────┬───────┬─────────┐
│ Name                                          │ Status    │ Batch │ Message │
├───────────────────────────────────────────────┼───────────┼───────┼─────────┤
│ 1720000000000_create_posts_table              │ completed │ 1     │         │
│ 1720000000001_create_comments_table           │ completed │ 1     │         │
│ 1720000000002_add_published_at_to_posts_table │ pending   │       │         │
└───────────────────────────────────────────────┴───────────┴───────┴─────────┘
```

--------------------------------

### Truncate all tables in test setup

Source: https://lucid.adonisjs.com/docs/database-service

Use `truncateAllTables` to reset the database in test setup or seed scripts. The example excludes the schema tables to avoid truncating them. This helper is available on every query client.

```typescript
import db from '@adonisjs/lucid/services/db'

export async function resetDatabase() {
  await db.connection().truncateAllTables(['adonis_schema', 'adonis_schema_versions'])
}
```

--------------------------------

### Set up database schema with testUtils.db().migrate() in tests/bootstrap.ts

Source: https://lucid.adonisjs.com/docs/testing

Registers a runner-level setup hook that runs `migration:run` once when the test runner starts. The returned cleanup runs `migration:reset` when the runner exits, leaving the database empty after the test run.

```typescript
import testUtils from '@adonisjs/core/services/test_utils'

export const runnerHooks: Required<Pick<Config, 'setup' | 'teardown'>> = {
  setup: [
    () => testUtils.db().migrate(),
  ],
  teardown: [],
}
```

--------------------------------

### Run shared migrations across multiple connections

Source: https://lucid.adonisjs.com/docs/migrations

Commands to run the same migration directory against different connections, useful for multi-tenant setups with one database per tenant. The example runs migrations on 'tenant_a' and 'tenant_b' connections.

```shellscript
node ace migration:run --connection=tenant_a
node ace migration:run --connection=tenant_b
```

--------------------------------

### Install Lucid with npm

Source: https://lucid.adonisjs.com/docs/installation

Install the `@adonisjs/lucid` package using npm.

```shellscript
npm i @adonisjs/lucid
```

--------------------------------

### Sidecar manifest example (postgres-schema.meta.json)

Source: https://lucid.adonisjs.com/docs/schema-dumps

Example of the .meta.json manifest written alongside a SQL dump. It records the connection, dump path, schema table names, and squashed migration names. Lucid validates it against the current connection before trusting it; a manifest for a different connection or schema table names is ignored.

```json
{
  "version": 1,
  "connection": "postgres",
  "dumpPath": "database/schema/postgres-schema.sql",
  "generatedAt": "2026-04-21T10:15:00.000Z",
  "schemaTableName": "adonis_schema",
  "schemaVersionsTableName": "adonis_schema_versions",
  "squashedMigrationNames": [
    "database/migrations/1700000000000_create_users_table",
    "database/migrations/1700000100000_create_posts_table"
  ]
}
```

--------------------------------

### Install Lucid with pnpm

Source: https://lucid.adonisjs.com/docs/installation

Install the `@adonisjs/lucid` package using pnpm.

```shellscript
pnpm add @adonisjs/lucid
```

--------------------------------

### Install Lucid with yarn

Source: https://lucid.adonisjs.com/docs/installation

Install the `@adonisjs/lucid` package using yarn.

```shellscript
yarn add @adonisjs/lucid
```

--------------------------------

### BaseSchema migration example

Source: https://lucid.adonisjs.com/docs/schema-builder

Shows the basic structure of a migration class extending BaseSchema, using this.schema.createTable and dropTable.

```typescript
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.string('email').unique().notNullable()
      table.timestamps(true, true)
    })
  }

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

--------------------------------

### Run migrations programmatically with MigrationRunner

Source: https://lucid.adonisjs.com/docs/migrations

Controller example using the MigrationRunner class to run migrations from outside the CLI, such as in an admin panel or setup wizard. It imports necessary dependencies, creates a runner with direction 'up' and dryRun false, runs it, and returns status, migrated files, and error message.

```typescript
import type { HttpContext } from '@adonisjs/core/http'
import db from '@adonisjs/lucid/services/db'
import app from '@adonisjs/core/services/app'
import { MigrationRunner } from '@adonisjs/lucid/migration'

export default class MigrationsController {
  async run({ response }: HttpContext) {
    const migrator = new MigrationRunner(db, app, {
      direction: 'up',
      dryRun: false,
    })

    await migrator.run()

    return response.ok({
      status: migrator.status,
      files: migrator.migratedFiles,
      error: migrator.error?.message,
    })
  }
}
```

--------------------------------

### Create a row with Model.create in a controller

Source: https://lucid.adonisjs.com/docs/models

Use Model.create to build an instance, persist it, and return it. This example is from a controller's store method, using request.input to get the email and password from the HTTP request.

```typescript
import type { HttpContext } from '@adonisjs/core/http'
import User from '#models/user'

export default class UsersController {
  async store({ request }: HttpContext) {
    return User.create({
      email: request.input('email'),
      password: request.input('password'),
    })
  }
}
```

--------------------------------

### Persistence lifecycle example

Source: https://lucid.adonisjs.com/docs/models

Shows how model state changes through the lifecycle: creating a new instance, modifying properties, saving, updating, and deleting. Demonstrates $original, $attributes, and $dirty behavior.

```typescript
const user = new User()                  // local, not persisted, not dirty
user.email = 'virk@adonisjs.com'         // dirty: { email }
user.password = 'secret'                 // dirty: { email, password }

await user.save()                        // INSERT runs; now persisted, dirty cleared

user.email = 'new@adonisjs.com'          // dirty again: { email }
console.log(user.$original.email)        // 'virk@adonisjs.com'
console.log(user.$attributes.email)      // 'new@adonisjs.com'

await user.save()                        // UPDATE runs; only email is sent

await user.delete()                      // DELETE runs; isDeleted is set
```

--------------------------------

### createTableIfNotExists example

Source: https://lucid.adonisjs.com/docs/schema-builder

Creates a table only if it does not already exist, useful for migrations that may run against environments where the table was created out-of-band.

```typescript
this.schema.createTableIfNotExists('posts', (table) => {
  table.increments('id')
  table.string('title').notNullable()
})
```

--------------------------------

### createTable example

Source: https://lucid.adonisjs.com/docs/schema-builder

Creates a new table with an id, title, body, and timestamps.

```typescript
this.schema.createTable('posts', (table) => {
  table.increments('id')
  table.string('title').notNullable()
  table.text('body')
  table.timestamps(true, true)
})
```

--------------------------------

### createTable with table builder

Source: https://lucid.adonisjs.com/docs/table-builder

Example of using the table builder inside a createTable callback to define columns, foreign keys, and timestamps.

```APIDOC
## createTable with table builder

### Description
Defines a new table with columns, foreign keys, and timestamps using the table builder API.

### Method
createTable

### Endpoint
this.schema.createTable('posts', (table) => { ... })

### Parameters
#### Callback Parameters
- **table** (TableBuilder) - Required - The table builder instance used to define columns and constraints.

### Request Example
```typescript
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  async up() {
    this.schema.createTable('posts', (table) => {
      table.increments('id')
      table.string('title').notNullable()
      table.text('body')
      table.integer('user_id').unsigned().references('users.id').onDelete('CASCADE')
      table.timestamps(true, true)
    })
  }
}
```

### Response
No response body; the operation is performed on the database.
```

--------------------------------

### Seeders configuration in config/database.ts

Source: https://lucid.adonisjs.com/docs/seeders

Example configuration for the postgres connection, setting the seeders paths and naturalSort option.

```typescript
{
  postgres: {
    client: 'pg',
    seeders: {
      paths: ['./database/seeders'],
      naturalSort: true,
    },
  },
}
```

--------------------------------

### createTableLike examples

Source: https://lucid.adonisjs.com/docs/schema-builder

Copies the structure of an existing table into a new one, optionally adding columns via a callback. Support varies by dialect; PostgreSQL and MySQL implement it natively.

```typescript
this.schema.createTableLike('posts_archive', 'posts')
```

```typescript
this.schema.createTableLike('posts_archive', 'posts', (table) => {
  table.timestamp('archived_at')
})
```

--------------------------------

### Use db.table() for insert with returning

Source: https://lucid.adonisjs.com/docs/database-service

Shows using `db.table('posts')` to insert a record and return columns. The example is from `app/controllers/posts_controller.ts`.

```typescript
import type { HttpContext } from '@adonisjs/core/http'
import db from '@adonisjs/lucid/services/db'

export default class PostsController {
  async index() {
    return db
      .from('posts')
      .select('id', 'title')
      .orderBy('id', 'desc')
  }

  async store({ request, response }: HttpContext) {
    const [post] = await db
      .table('posts')
      .insert({ title: request.input('title') })
      .returning(['id', 'title'])

    return response.created(post)
  }
}
```

--------------------------------

### Create users table migration

Source: https://lucid.adonisjs.com/docs/migrations

Example migration class that creates a 'users' table with id, email, password, and timestamps. Uses the tableName property convention and implements up and down methods.

```typescript
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.string('email').unique().notNullable()
      table.string('password').notNullable()
      table.timestamp('created_at', { useTz: true })
      table.timestamp('updated_at', { useTz: true })
    })
  }

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

--------------------------------

### Create a User model with make:model

Source: https://lucid.adonisjs.com/docs/models

Scaffolds a new model in `app/models` using the `make:model` command. The output shows the created file path.

```shellscript
node ace make:model User
// CREATE: app/models/user.ts
```

--------------------------------

### with CTE example

Source: https://lucid.adonisjs.com/docs/select-query-builder

Defines a CTE named 'active_users' and uses it as a regular table in the main query. The CTE selects all active users, and the main query filters by role 'admin'.

```typescript
db
  .with('active_users', (query) => {
    query
      .from('users')
      .select('*')
      .where('is_active', true)
  })
  .from('active_users')
  .where('role', 'admin')
```

--------------------------------

### Read full ConnectionNode with db.manager.get

Source: https://lucid.adonisjs.com/docs/connection-manager

Use `get(name)` to read the full `ConnectionNode`, for example to inspect the current `state` or the `config` the connection was registered with.

```typescript
const node = db.manager.get('primary')

if (node) {
  logger.info({ state: node.state, client: node.config.client })
}
```

--------------------------------

### Access the model property on a query builder

Source: https://lucid.adonisjs.com/docs/model-query-builder

Use `query.model` to get the model class that the query builder was created from. The example checks that `query.model === User` evaluates to `true`.

```typescript
const query = User.query()
console.log(query.model === User)  // true
```

--------------------------------

### Scaffold and run migrations with --connection flag

Source: https://lucid.adonisjs.com/docs/migrations

Commands to scaffold and run migrations against a specific connection using the --connection flag. The example shows using 'products' as the connection name.

```shellscript
node ace make:migration --connection=products
node ace migration:run --connection=products
```

--------------------------------

### Recursive CTEs: withRecursive

Source: https://lucid.adonisjs.com/docs/introduction

Walk trees, graphs, and hierarchical data in a single query using the withRecursive method. This example sums amounts from a recursive tree starting at id 1.

```typescript
import db from '@adonisjs/lucid/services/db'

const total = await db
  .query()
  .withRecursive('tree', (query) => {
    query
      .from('accounts')
      .select('amount', 'id')
      .where('id', 1)
      .union((subquery) => {
        subquery
          .from('accounts as a')
          .select('a.amount', 'a.id')
          .innerJoin('tree', 'tree.id', 'a.parent_id')
      })
  })
  .sum('amount as total')
  .from('tree')
```

--------------------------------

### Create a Post model with flags --migration --factory --controller

Source: https://lucid.adonisjs.com/docs/models

Generates a model along with a migration, factory, and controller in one command.

```shellscript
node ace make:model Post --migration --factory --controller
```

--------------------------------

### Register and release tenant connections at runtime

Source: https://lucid.adonisjs.com/docs/connection-manager

Example of a service that registers a connection per tenant using `db.manager.add` and releases it with `db.manager.release`. The `add` method is a no-op if the name already exists, so it does not overwrite existing configs.

```typescript
import db from '@adonisjs/lucid/services/db'
import type { ConnectionConfig } from '@adonisjs/lucid/types/database'

export default class TenantConnections {
  register(tenantId: string, config: ConnectionConfig) {
    const name = `tenant:${tenantId}`

    if (!db.manager.has(name)) {
      db.manager.add(name, config)
    }

    return db.connection(name)
  }

  async forget(tenantId: string) {
    await db.manager.release(`tenant:${tenantId}`)
  }
}
```

--------------------------------

### Create main seeder with make:seeder

Source: https://lucid.adonisjs.com/docs/seeders

Command to create a main seeder that will orchestrate other seeders. Output shows the created file path.

```shellscript
node ace make:seeder main/index
// CREATE: database/seeders/main/index_seeder.ts
```

--------------------------------

### Start a managed transaction with db.transaction

Source: https://lucid.adonisjs.com/docs/database-service

Use db.transaction when several database operations must succeed or fail together. The transaction commits when the callback succeeds and rolls back when the callback throws. This example inserts a user and a profile, returning the created user.

```typescript
import type { HttpContext } from '@adonisjs/core/http'
import db from '@adonisjs/lucid/services/db'

export default class UsersController {
  async store({ request, response }: HttpContext) {
    const user = await db.transaction(async (trx) => {
      const [createdUser] = await trx
        .table('users')
        .insert({ email: request.input('email') })
        .returning(['id', 'email'])

      await trx
        .table('profiles')
        .insert({
          user_id: createdUser.id,
          full_name: request.input('full_name'),
        })

      return createdUser
    })

    return response.created(user)
  }
}
```

--------------------------------

### Reset data between tests with testUtils.db().truncate() in tests/functional/posts.spec.ts

Source: https://lucid.adonisjs.com/docs/testing

Registers a `group.each.setup` hook that calls `truncate()`. The returned cleanup empties every table after each test completes, so each test starts with the schema from the runner hook plus any data inserted by the group's own setup.

```typescript
import { test } from '@japa/runner'
import testUtils from '@adonisjs/core/services/test_utils'

test.group('Posts', (group) => {
  group.each.setup(() => testUtils.db().truncate())
})
```

--------------------------------

### Get a builder instance with db.query() and db.from()

Source: https://lucid.adonisjs.com/docs/select-query-builder

Shows how to obtain a DatabaseQueryBuilder instance. db.query() returns a builder without a table, while db.from('users') is a shortcut that selects the table. Both return the same builder type.

```typescript
import db from '@adonisjs/lucid/services/db'

const query = db.query()              // builder without a table selected
const usersQuery = db.from('users')   // shortcut: builder with the table selected
```

--------------------------------

### Run migration:status command

Source: https://lucid.adonisjs.com/docs/commands

Lists every migration file and its status (pending, completed, or errored), grouped by batch. Use the --connection option to specify a connection.

```shellscript
node ace migration:status
```

--------------------------------

### Create migration for posts table

Source: https://lucid.adonisjs.com/docs/installation

Use the make:migration command with the --create flag to scaffold a migration that creates a new table. The command is run in the terminal.

```shellscript
node ace make:migration posts --create=posts
```

--------------------------------

### Configure database connection in config/database.ts

Source: https://lucid.adonisjs.com/docs/schema-generation

Sets up the PostgreSQL connection using the DATABASE_URL environment variable. This is the first step to make Lucid work with an existing database.

```typescript
import env from '#start/env'
import { defineConfig } from '@adonisjs/lucid'

const dbConfig = defineConfig({
  connection: 'postgres',
  connections: {
    postgres: {
      client: 'pg',
      connection: env.get('DATABASE_URL'),
    },
  },
})

export default dbConfig
```

--------------------------------

### withRecursive with column list example

Source: https://lucid.adonisjs.com/docs/select-query-builder

Shows how to pass a third argument to `withRecursive` to restrict the column list of the CTE. The example uses a placeholder comment for the CTE body.

```typescript
db
  .query()
  .withRecursive('tree', (query) => {
    // ...
  }, ['amount', 'id'])
  .sum('amount as total')
  .from('tree')
```

--------------------------------

### Create a migration with make:migration

Source: https://lucid.adonisjs.com/docs/migrations

Scaffolds a new migration file in database/migrations with a timestamp prefix. The --create=users flag generates a migration for creating the users table. The output shows the created file path.

```shellscript
node ace make:migration users --create=users
// CREATE: database/migrations/1720000000000_create_users_table.ts
```

--------------------------------

### afterPaginate hook example

Source: https://lucid.adonisjs.com/docs/model-hooks

Example of using the afterPaginate hook to log pagination usage. The hook receives the ModelPaginator instance and can be used for inspection or logging; mutating the paginator in place is unusual.

```typescript
import { afterPaginate } from '@adonisjs/lucid/orm'
import type { ModelPaginatorContract } from '@adonisjs/lucid/types/model'
import { UsersSchema } from '#database/schema'

export default class User extends UsersSchema {
  @afterPaginate()
  static logUsage(paginator: ModelPaginatorContract<User>) {
    logger.debug({ count: paginator.all().length, page: paginator.currentPage }, 'users paginated')
  }
}
```

--------------------------------

### Table-level primaryKey rule in database/schema_rules.ts

Source: https://lucid.adonisjs.com/docs/schema-classes

Example of a table-level primaryKey rule for the oauth_states table, overriding the global rule for that table only. Uses the same logic as the global example to force string type and @column({ isPrimary: true }).

```typescript
export default {
  tables: {
    oauth_states: {
      primaryKey: (tableName, primaryKeys, columns) => {
        const columnName = primaryKeys[0]
        if (!columnName || !columns[columnName]) {
          return undefined
        }

        return {
          columnName,
          columnInfo: {
            tsType: 'string',
            decorators: [{ name: '@column', args: { isPrimary: true } }],
            imports: [],
          },
        }
      },
    },
  },
} satisfies SchemaRules
```

--------------------------------

### beforePaginate hook example

Source: https://lucid.adonisjs.com/docs/model-hooks

Example of using the beforePaginate hook to filter deleted records in both the count and main queries. The hook receives a tuple of two query builders and mutates both to keep counts and results in sync.

```typescript
import { beforePaginate } from '@adonisjs/lucid/orm'
import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
import { UsersSchema } from '#database/schema'

export default class User extends UsersSchema {
  @beforePaginate()
  static filterDeleted([countQuery, query]: [
    ModelQueryBuilderContract<typeof User>,
    ModelQueryBuilderContract<typeof User>,
  ]) {
    countQuery.whereNull('deleted_at')
    query.whereNull('deleted_at')
  }
}
```

--------------------------------

### Type compatibility constraints for column re-declarations

Source: https://lucid.adonisjs.com/docs/schema-classes

Shows valid and invalid type narrowing for re-declared column properties. Valid examples narrow string to a union and any to a specific type; invalid examples change string to number and number to string.

```typescript
// Valid: narrow string to a union type
@column()
declare status: 'draft' | 'published'

// Valid: narrow any to a specific type
@column()
declare metadata: JSON<{ title: string }>

// Invalid: cannot change string to number
@column()
declare title: number

// Invalid: cannot change number to string
@column()
declare id: string
```

--------------------------------

### Run migration:fresh command

Source: https://lucid.adonisjs.com/docs/commands

Drops every table in the database and re-runs all migrations from scratch. Use --seed to run database seeders after migrations, and --drop-views, --drop-types, --drop-domains to drop additional database objects.

```shellscript
node ace migration:fresh
node ace migration:fresh --seed
```

--------------------------------

### Start a transaction from a model

Source: https://lucid.adonisjs.com/docs/transactions

`Model.transaction` is a convenience that starts a transaction on the model's connection. Use it when the entire operation is scoped to one model, especially when the model overrides `static connection`. For models on the default connection, this is equivalent to `db.transaction(...)`.

```typescript
import User from '#models/user'

await User.transaction(async (trx) => {
  const user = new User()
  user.email = 'virk@adonisjs.com'
  user.useTransaction(trx)
  await user.save()
})
```

--------------------------------

### Configure Lucid with SQLite driver

Source: https://lucid.adonisjs.com/docs/installation

Run the configure command to register Lucid with the framework. The `--db=sqlite` flag selects SQLite as the database driver, which is the fastest option for local verification.

```shellscript
node ace configure @adonisjs/lucid --db=sqlite
```

--------------------------------

### assertEmpty example

Source: https://lucid.adonisjs.com/docs/testing

Shorthand for assertCount(table, 0).

```typescript
await db.assertEmpty('sessions')
```

--------------------------------

### assertMissing example

Source: https://lucid.adonisjs.com/docs/testing

Passes when no row matches the given column-value pairs.

```typescript
await db.assertMissing('users', { email: 'deleted@example.com' })
```

--------------------------------

### Build instance and save with save

Source: https://lucid.adonisjs.com/docs/crud-operations

Creates an instance, assigns columns one at a time, and persists with save. The first save runs INSERT; subsequent saves run UPDATE.

```typescript
const user = new User()
user.email = 'virk@adonisjs.com'
user.password = 'secret'
await user.save()
```

--------------------------------

### dropTableIfExists example

Source: https://lucid.adonisjs.com/docs/schema-builder

Drops the table only if it exists, useful for cleanup migrations.

```typescript
this.schema.dropTableIfExists('legacy_audit')
```

--------------------------------

### renameTable example

Source: https://lucid.adonisjs.com/docs/schema-builder

Renames a table. Returns a Promise<void> and cannot be chained.

```typescript
await this.schema.renameTable('user', 'users')
```

--------------------------------

### tap(callback)

Source: https://lucid.adonisjs.com/docs/model-factories

Runs a callback for every instance the factory produces, after the factory callback and any applied states. Use it for one-off decoration that does not deserve a state.

```APIDOC
## tap(callback)

### Description
Runs the provided callback for every instance the factory produces, after the factory callback and any applied states. Use it for one-off decoration that does not deserve a state.

### Method
`tap`

### Parameters
- **callback** (Function) - Required - A function that receives `(user, ctx, builder)` and mutates the model instance in place. Return values are ignored.

### Request Example
```typescript
const users = await UserFactory
  .tap((user, ctx, builder) => {
    user.rememberMeToken = generateToken()
  })
  .createMany(5)
```

### Response
No direct response; the factory produces instances with the applied mutations.
```

--------------------------------

### assertCount example

Source: https://lucid.adonisjs.com/docs/testing

Passes when the table has exactly the expected number of rows total.

```typescript
await db.assertCount('users', 3)
```

--------------------------------

### Starter schema rules file (database/schema_rules.ts)

Source: https://lucid.adonisjs.com/docs/schema-classes

A minimal rules file that satisfies the SchemaRules type. It defines empty types, columns, and tables objects. This file is loaded automatically by the generator when pointed to by schemaGeneration.rulesPaths.

```typescript
import { type SchemaRules } from '@adonisjs/lucid/types/schema_generator'

export default {
  types: {},
  columns: {},
  tables: {},
} satisfies SchemaRules
```

--------------------------------

### Fresh migrate with a custom schema path

Source: https://lucid.adonisjs.com/docs/schema-dumps

Drops every table and then uses the dump at the given path to rebuild the database, rather than replaying every migration file.

```shellscript
node ace migration:fresh --schema-path=./database/snapshots/schema.sql
```

--------------------------------

### dropTable example

Source: https://lucid.adonisjs.com/docs/schema-builder

Drops an existing table, typically used in the down method to undo a createTable.

```typescript
this.schema.dropTable('users')
```

--------------------------------

### Run db:seed command with options

Source: https://lucid.adonisjs.com/docs/commands

Runs every seeder inside database/seeders. Use --interactive to pick seeders interactively, or --files to run a specific subset. Options include --connection, --compact-output.

```shellscript
node ace db:seed
node ace db:seed --interactive
node ace db:seed --files=./database/seeders/user_seeder.ts
```

--------------------------------

### Generate a model with ace make:model

Source: https://lucid.adonisjs.com/docs/installation

Run this command to generate a model for the 'posts' table. The generated model extends the schema class for the table.

```shellscript
node ace make:model Post
```

--------------------------------

### Migration Class Structure

Source: https://lucid.adonisjs.com/docs/migrations

Example of a migration class extending BaseSchema with up and down methods, and the tableName property.

```APIDOC
## Migration Class Structure

### Description
A migration class extends `BaseSchema` and must implement `up` (apply the change) and `down` (revert the change). The class also exposes helpers for raw SQL, deferred operations, and direct query client access.

### Example
```typescript
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.string('email').unique().notNullable()
      table.string('password').notNullable()
      table.timestamp('created_at', { useTz: true })
      table.timestamp('updated_at', { useTz: true })
    })
  }

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

### Properties
- **tableName** (string) - The name of the table. Convention to set once and reuse in `up`, `down`, and helper methods.

### Methods
- **up()** - Apply the migration changes.
- **down()** - Revert the migration changes.

### Available Members
- **this.schema** - The Knex schema builder for DDL operations.
- **this.now(precision?)** - Returns a raw `CURRENT_TIMESTAMP` expression for column defaults.
- **this.raw(sql, bindings?)** - Returns a raw SQL fragment.
- **this.knex()** - Returns the underlying Knex query builder.
- **this.db** - The `QueryClientContract` for the migration's connection.
- **this.dryRun** - Boolean flag indicating dry-run mode.
- **static disableTransactions** - Set to `true` to skip wrapping the migration in a transaction.
```

--------------------------------

### Position a column with first and after

Source: https://lucid.adonisjs.com/docs/table-builder

Positions a column at the start of the table (`first`) or after a specific column (`after`). MySQL only.

```typescript
table.string('email').first()
table.string('avatar_url').after('password')
```

--------------------------------

### Factory.before('makeStubbed')

Source: https://lucid.adonisjs.com/docs/model-factories

Registers a hook to customize the primary key for a specific factory before Lucid's stub runs.

```APIDOC
## Factory.before('makeStubbed')

### Description
Registers a hook to customize the primary key for a specific factory before Lucid's stub runs.

### Method
before

### Parameters
- **event** (string) - Required - The hook event name, e.g., 'makeStubbed'.
- **callback** (function) - Required - A function that receives (_, model) and assigns the primary key.

### Example
```typescript
import { randomUUID } from 'node:crypto'

Factory.define(Post, () => ({ /* ... */ }))
  .before('makeStubbed', (_, model) => {
    model.id = randomUUID()
  })
  .build()
```
```

--------------------------------

### Using date and timestamp columns (app/models/post.ts)

Source: https://lucid.adonisjs.com/docs/schema-classes

Shows how date and timestamp columns map to Luxon `DateTime` instances, allowing methods like `toFormat` and `diff`. The example checks if `publishedOn` is in the future.

```typescript
import { PostsSchema } from '#database/schema'

const post = await Post.findOrFail(params.id)

post.createdAt.toFormat('yyyy-MM-dd')

const daysSinceCreated = DateTime.now().diff(post.createdAt, 'days').days

if (post.publishedOn && post.publishedOn > DateTime.now()) {
  // scheduled for later
}
```

--------------------------------

### alterTable example

Source: https://lucid.adonisjs.com/docs/schema-builder

Alters an existing table by adding and dropping columns. Only modifying methods take effect.

```typescript
this.schema.alterTable('users', (table) => {
  table.string('first_name')
  table.string('last_name')
  table.dropColumn('name')
})
```

--------------------------------

### Run migrations

Source: https://lucid.adonisjs.com/docs/installation

Run the migration to create the table in the database. Lucid applies any pending migration files, prints a confirmation for each one, and regenerates database/schema.ts with a typed schema class for every table that now exists.

```shellscript
node ace migration:run
```

--------------------------------

### Await query builder directly

Source: https://lucid.adonisjs.com/docs/select-query-builder

The query builder is a Promise, so you can await it directly to get the result rows.

```typescript
const users = await db.from('users').where('is_active', true)
```

--------------------------------

### Factory.newUp()

Source: https://lucid.adonisjs.com/docs/model-factories

Replaces Lucid's default instantiation. Use it when the model needs a non-standard construction step.

```APIDOC
## Factory.newUp()

### Description
Replaces Lucid's default instantiation. Use it when the model needs a non-standard construction step.

### Method
newUp

### Parameters
- **callback** (function) - Required - A function that receives (attributes, ctx) and returns a model instance.

### Example
```typescript
Factory.define(User, () => ({ /* ... */ }))
  .newUp((attributes, ctx) => {
    const user = new User()
    user.fill(attributes)
    return user
  })
  .build()
```
```

--------------------------------

### withCount and preload are independent

Source: https://lucid.adonisjs.com/docs/model-query-builder

Shows that withCount and preload can be used together to get both the full list and the count.

```typescript
await User.query().preload('posts').withCount('posts')
```

--------------------------------

### Alter a column with options

Source: https://lucid.adonisjs.com/docs/table-builder

Pass options to control which aspects are altered. The example shows altering nullability and type.

```typescript
table.text('body').alter({ alterNullable: true, alterType: false })
```

--------------------------------

### Explain query execution plan with db.rawQuery

Source: https://lucid.adonisjs.com/docs/debugging

Build a query with the Lucid query builder, extract its SQL and bindings using `.toSQL()`, then run it through `db.rawQuery` with an `EXPLAIN ANALYZE` prefix. The `.toSQL()` call returns an object of shape `{ sql, bindings }`; pass both to `rawQuery` to preserve the prepared statement parameters. This approach works for PostgreSQL and MySQL (8.0.18+), but not for SQLite or MSSQL.

```typescript
import db from '@adonisjs/lucid/services/db'

export default class PostsService {
  async explainPublishedPosts() {
    const query = db
      .from('posts')
      .where('is_published', true)
      .orderBy('created_at', 'desc')
      .limit(10)
      .toSQL()

    const plan = await db.rawQuery(`EXPLAIN ANALYZE ${query.sql}`, query.bindings)
    return plan.rows
  }
}
```

--------------------------------

### Generate a model with transformer using ace command

Source: https://lucid.adonisjs.com/docs/serializing-models

Run this command to create a Lucid model and a matching transformer in app/transformers. The output shows the created files.

```shellscript
node ace make:model Post --transformer
// CREATE: app/models/post.ts
// CREATE: app/transformers/post_transformer.ts
```

--------------------------------

### db.manager.get(name)

Source: https://lucid.adonisjs.com/docs/connection-manager

Reads the full `ConnectionNode` for a connection, for example to inspect the current `state` or the `config` the connection was registered with.

```APIDOC
## db.manager.get(name)

### Description
Reads the full `ConnectionNode` for a connection, for example to inspect the current `state` or the `config` the connection was registered with.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The connection name to retrieve.

### Returns
- **ConnectionNode | null** - The connection node if found, otherwise `null`.

### Example
```typescript
const node = db.manager.get('primary')

if (node) {
  logger.info({ state: node.state, client: node.config.client })
}
```
```

--------------------------------

### Create a seeder with node ace make:seeder

Source: https://lucid.adonisjs.com/docs/seeders

Generates a new seeder file in database/seeders/. The output shows the created file path.

```shellscript
node ace make:seeder User
// CREATE: database/seeders/user_seeder.ts
```

--------------------------------

### assertModelMissing example

Source: https://lucid.adonisjs.com/docs/testing

Passes when no row exists for the model's primary key. Useful after a delete to confirm the row is gone.

```typescript
const user = await User.findOrFail(1)
await user.delete()
await db.assertModelMissing(user)
```

--------------------------------

### unique rule with callback

Source: https://lucid.adonisjs.com/docs/validation

Example of using the `unique` rule with a callback that checks if a value is unique using a Lucid model.

```APIDOC
## unique rule with callback

### Description
Example of using the `unique` rule with a callback that checks if a value is unique using a Lucid model.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **db** (Database) - Required - The database connection or query builder.
- **value** (any) - Required - The value being validated.
- **field** (string) - Optional - The field name.

### Request Example
```typescript
import vine from '@vinejs/vine'
import User from '#models/user'

const createUserValidator = vine.create({
  email: vine.string().email().unique(async (_db, value) => {
    const existing = await User.findBy('email', value)
    return existing === null
  }),
})
```

### Response
#### Success Response (200)
- **boolean** (boolean) - `true` if the value is unique, `false` otherwise.

#### Response Example
```json
{
  "valid": true
}
```
```

--------------------------------

### migration:run command and output

Source: https://lucid.adonisjs.com/docs/commands

Applies pending migrations, records them in adonis_schema, and regenerates database/schema.ts. The output shows the migrated files and timing.

```shellscript
node ace migration:run
```

```text
❯ migrated database/migrations/1720000000000_create_posts_table
❯ migrated database/migrations/1720000000001_create_comments_table

Migrated in 42 ms
```

--------------------------------

### create and createMany

Source: https://lucid.adonisjs.com/docs/has-many

Build a model instance from values, set the foreign key from the parent, and persist it. createMany does the same for an array of values.

```APIDOC
## create(values)

### Description
Builds a model instance from the provided values, sets the foreign key from the parent, and persists it. Runs inside a managed transaction.

### Method
create

### Parameters
- **values** (Object) - Required - The attribute values for the new related model.

### Request Example
```typescript
const post = await user.related('posts').create({
  title: 'Hello',
  body: 'World',
})
```

## createMany(values[])

### Description
Builds multiple model instances from an array of values, sets the foreign key from the parent, and persists them. Runs inside a managed transaction.

### Method
createMany

### Parameters
- **values[]** (Object[]) - Required - An array of attribute value objects for the new related models.

### Request Example
```typescript
const posts = await user.related('posts').createMany([
  { title: 'First', body: '...' },
  { title: 'Second', body: '...' },
])
```
```
Tokens:
Raw