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

무료