AdonisJS core peer packages (required if wiring into AdonisJS IoC):

npm install @adonisjs/core @adonisjs/presets

No native pod/Android linking steps are required. better-sqlite3 requires a C++ build toolchain (node-gyp); ensure python, make, and a C++ compiler are available.

Project setup

1. Copy the source/ directory into your project, e.g. src/lucid/.
2. Update tsconfig.json to include the source:

   {
     "compilerOptions": {
       "module": "ESNext",
       "moduleResolution": "Bundler",
       "target": "ES2022",
       "strict": true
     },
     "include": ["src/**/*"]
   }
   

3. Because clients/libsql.cjs is CommonJS, ensure your bundler or ts-node handles mixed ESM/CJS. With ts-node add:

   { "ts-node": { "esm": true } }
   

4. Set database environment variables your config will consume:

   DB_CONNECTION=pg
   PG_HOST=127.0.0.1
   PG_PORT=5432
   PG_USER=lucid
   PG_PASSWORD=secret
   PG_DB_NAME=myapp
   

5. Create a db.ts bootstrap file (see examples below) that instantiates Database with a config object matching DatabaseConfig.
6. For migrations, point MigrationRunner at your migrations directory and call run() during app startup or a CLI command.

Public API

Database

import { Database } from './src/lucid/database/main.js'

const db = new Database(config, logger, emitter)

The central entry point. Manages multiple named connections via ConnectionManager, exposes query(), from(), insertQuery(), rawQuery(), transaction(), and connection(). Extend with Database.macro() for project-wide helpers. Use this as a singleton injected across your service layer.

Connection

import { Connection } from './src/lucid/connection/index.js'

const conn = new Connection('primary', config, logger)
conn.open()
const knexClient: Knex = conn.client!

Wraps a single Knex connection with lifecycle events (connect, disconnect, error). Supports read/write replica splitting via hasReadWriteReplicas. Use directly only when you need low-level pool introspection; normally obtained through Database.

FactoryManager / factory

import factory from './src/lucid/factories/main.js'
import { FactoryManager } from './src/lucid/factories/main.js'

const UserFactory = factory.define(User, ({ faker }) => ({
  email: faker.internet.email(),
  name: faker.person.fullName(),
}))

FactoryManager.define() registers a model factory that generates stub rows for tests. Call make() for in-memory instances or create() to persist. Use stubId() to override the auto-increment stub ID strategy.

MigrationRunner

import { MigrationRunner } from './src/lucid/migration/main.js'

const runner = new MigrationRunner(db, app, { direction: 'up', dryRun: false })
await runner.run()

Discovers migration files, tracks their state in a adonis_schema table, and runs them in order. Supports up, down, and --dry-run. SchemaDumper (also exported from migration/main.ts) writes a SQL dump of the current schema.

Working examples

Scenario - Bootstrap a Database instance and run a raw query

Initialize Database with a PostgreSQL config and execute a raw SQL statement.

import { Database } from './src/lucid/database/main.js'
import { defineConfig } from './src/lucid/define_config.js'

const config = defineConfig({
  connection: 'pg',
  connections: {
    pg: {
      client: 'postgres',
      connection: {
        host: process.env.PG_HOST ?? '127.0.0.1',
        port: Number(process.env.PG_PORT ?? 5432),
        user: process.env.PG_USER ?? 'lucid',
        password: process.env.PG_PASSWORD ?? '',
        database: process.env.PG_DB_NAME ?? 'myapp',
      },
    },
  },
})

// Provide AdonisJS-compatible logger and emitter stubs if outside AdonisJS
const db = new Database(config, logger, emitter)

const result = await db.rawQuery('SELECT NOW() as now')
console.log(result.rows[0].now)

await db.manager.closeAll()

Scenario - Define a model factory and create seeded test data

Use FactoryManager to define a User factory, then create 10 persisted rows inside a test.

import factory from './src/lucid/factories/main.js'
import { User } from './src/models/user.js' // Your Lucid model

const UserFactory = factory
  .define(User, ({ faker }) => {
    return {
      email: faker.internet.email(),
      username: faker.internet.username(),
      avatarUrl: faker.image.avatarGitHub(),
    }
  })
  .build()

// Inside a test
const users = await UserFactory.createMany(10)
console.log(users.map((u) => u.email))

Scenario - Run migrations programmatically

Invoke the migration runner from a standalone Node.js script (e.g., a Dockerfile entrypoint).

import { MigrationRunner } from './src/lucid/migration/main.js'
import { Database } from './src/lucid/database/main.js'

// Assume `db` and `app` are already initialised
const runner = new MigrationRunner(db, app, {
  direction: 'up',
  dryRun: false,
  connectionName: 'pg',
})

await runner.run()

for (const file of runner.migratedFiles) {
  console.log(`Migrated: ${file.file.name} — status: ${file.status}`)
}

process.exit(0)

File walkthrough

• connection/index.ts - Connection class; opens/closes the Knex pool, emits lifecycle events, supports R/W replicas.
• connection/manager.ts - ConnectionManager; maintains a registry of named Connection instances.
• connection/logger.ts - Thin wrapper adapting AdonisJS logger to Knex query logging.
• database/main.ts - Database façade; top-level API for all query/transaction/connection operations.
• database/query_builder/ - DatabaseQueryBuilder, InsertQueryBuilder, OnConflictQueryBuilder, RawQueryBuilder.
• database/static_builder/ - RawBuilder and ReferenceBuilder for pre-built SQL fragments.
• database/paginator/ - SimplePaginator for offset-based pagination results.
• database/checks/ - DbCheck and DbConnectionCountCheck health-check classes.
• dialects/index.ts - Maps client names to dialect classes; exports clientsToDialectsMapping.
• dialects/*.ts - Per-driver dialect logic (date handling, returning clauses, DDL quirks).
• factories/main.ts - FactoryManager singleton and factory default export.
• factories/factory_model.ts - FactoryModel with .make(), .create(), .makeMany(), .createMany().
• factories/relations/ - Factory helpers for hasOne, hasMany, belongsTo, manyToMany.
• migration/main.ts - Re-exports MigrationRunner and SchemaDumper.
• migration/runner.ts - Core runner that tracks and executes migration files.
• migration/source.ts - Discovers migration files from configured directories.
• migration/schema_dumper.ts - Dumps current schema to SQL for version control.
• orm/base_model/ - BaseModel with dirty tracking, lifecycle hooks, serialization.
• orm/decorators/ - @column, @hasMany, @belongsTo, and other relation decorators.
• orm/adapter/ - Adapter bridging models to QueryClient.
• schema/ - Schema base class used inside migration files to build DDL.
• seeders/ - Seeder runner that executes seed files in order.
• query_client/ - QueryClient selecting read or write Knex connection per query.
• transaction_client/ - TransactionClient wrapping a Knex transaction.
• types/ - All TypeScript interfaces and contract types.
• define_config.ts - defineConfig() helper for typed Lucid configuration objects.
• errors.ts - Named error subclasses (E_MISSING_MODEL_ATTRIBUTE, etc.).

Common pitfalls and fixes

• ESM/CJS mismatch with clients/libsql.cjs - Import it with createRequire or ensure your bundler treats .cjs files as CommonJS; do not rename to .js.
• knex-dynamic-connection version pin - patchKnex API changes between minor versions; pin knex-dynamic-connection to the version specified in the upstream package.json lock file.
• Missing @adonisjs/core logger/emitter - Database constructor expects AdonisJS Logger and Emitter shapes; outside AdonisJS, pass a minimal stub implementing .debug(), .error(), .emit() or the constructor will throw at runtime.
• better-sqlite3 native build failure - Run npm rebuild better-sqlite3 after switching Node.js versions; ensure node-gyp dependencies (python3, make, C++ compiler) are installed.
• dialectName deprecation warning - The Connection.dialectName property is deprecated; use Connection.clientName in all new code to avoid future breakage.
• Global transactions not cleaned up - Database.connectionGlobalTransactions holds live TransactionClient references; always commit() or rollback() inside finally blocks or the pool will exhaust open connections.

Vibe-coding prompt template

I have dropped the Lucid ORM source from @adonisjs/lucid@22.4.2 into `src/lucid/`
of my Node.js TypeScript project. The integration guide is in `USAGE.md`.

Please help me integrate it step by step:

1. Read `USAGE.md` and `src/lucid/define_config.ts` to understand the config shape.
2. Create `src/db.ts` that instantiates `Database` from `src/lucid/database/main.ts`
   using environment variables for the connection (postgres by default).
3. Wire the `Database` instance as a singleton exportable from `src/db.ts`.
4. Create a sample migration file under `database/migrations/` using the `Schema`
   base class from `src/lucid/schema/`.
5. Create a `User` model extending `BaseModel` from `src/lucid/orm/base_model/`
   with `@column` decorators for `id`, `email`, and `createdAt`.
6. Create a `UserFactory` in `database/factories/user_factory.ts` using
   `factory.define` from `src/lucid/factories/main.ts`.
7. Show how to run migrations programmatically using `MigrationRunner` from
   `src/lucid/migration/main.ts`.
8. Add a health check using `DbCheck` from `src/lucid/database/main.ts`.

Use only the APIs documented in `USAGE.md`. Do not invent method names.

License and credit

AdonisJS Lucid is released under the MIT License. See source/LICENSE.md if present, or refer to the upstream repository. The upstream npm package is @adonisjs/lucid maintained by Harminder Virk and the AdonisJS core team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Objection.js SQL-Friendly Relational Query Builder for Node.js

Automation, Utilities & Developer Tools

無料