Lucid: the SQL ORM for AdonisJS

What Lucid provides for AdonisJS applications

Lucid is the SQL ORM for AdonisJS, built on top of Knex. It comes with a database query builder, an Active Record ORM, migrations, seeders, and model factories. The supported databases include PostgreSQL, MySQL, MSSQL, Redshift, SQLite, and many more, which the description names directly.

The intended user is a developer building an AdonisJS application who needs structured database access rather than raw SQL. The package is published as @adonisjs/lucid on npm. The official documentation lives at lucid.adonisjs.com. The project is licensed under MIT and is a first-party package of the AdonisJS ecosystem, as indicated by the first-party-package topic.

How Lucid is organized as a package

The package.json reveals the module structure. The main entry point is build/index.js, and the exports map exposes subpaths for schema, commands, factories, database, orm, orm/relations, seeders, plugins/db, services, types, migration, database_provider, and utils. That modular export surface lets an application import only the parts it needs, such as the ORM or the migration runner.

The package is an ES module with type definitions, and it requires Node 24.0.0 or newer. The version is 22.4.2, matching the default branch 22.x. Recent releases are v22.4.2 with custom schema rules correctly overriding default decorators, v22.4.1 unlocking the Knex version, and v22.4.0 adding test assertion helpers and support for multiple decorators.

The repository layout includes src, services, providers, commands, stubs, docs, test, test-helpers, example, and a schema generation guide. The example directory contains an index.ts entry point.

Running tests locally with Docker

The README documents a local test workflow that uses Docker Compose and npm. The compose.yml file defines services for MySQL, legacy MySQL, MySQL read replicas, and PostgreSQL, each configured through environment variables.

docker-compose up -d
npm run test

The first command starts the database containers in the background. The second runs the test suite. The package.json provides many database-specific test scripts, such as test:sqlite, test:mysql, test:mysql_legacy, test:better_sqlite, and test:libsql, each selecting a database through the DB environment variable. The pretest script runs the linter before tests.

The README is short and points to the official documentation for usage details. The contribution guide and code of conduct are maintained in the adonisjs/.github repository rather than in this one.

Database support and compose services

The compose.yml defines services for multiple database versions, including mysql:5.7, mysql:8.0, and postgres:16, plus read replicas for testing replication scenarios. Environment variables for ports, users, passwords, and databases are loaded from.env. The mysql:8.0 service is configured with specific flags such as mysql_native_password authentication and relaxed durability settings for test performance.

The presence of both mysql:5.7 and mysql:8.0 services indicates the project tests against legacy and current MySQL versions. This breadth of test infrastructure supports the claim of supporting many databases, though the README does not list every supported driver.

Limitations and when Lucid is the wrong tool

Lucid is an AdonisJS package, so it is the wrong tool if you are not using AdonisJS or need an ORM for another Node.js framework. The Node engine requirement of 24.0.0 or newer is a hard floor that excludes older Node runtimes.

The README does not document installation steps, configuration, or API usage; it points to lucid.adonisjs.com for documentation. The repository's default branch is 22.x rather than main, which matters when cloning or referencing the default branch in tooling.

The README does not document rollback, migration strategies between major versions, or offline installation. The test infrastructure depends on Docker, so a contributor without Docker cannot easily run the full suite.

Alternatives and how the approach differs

The README does not name a competing ORM, but it positions Lucid as built on top of Knex, which is itself a query builder. Lucid adds an Active Record layer, migrations, seeders, and model factories on top of Knex's query building. A team could use Knex directly for a lighter dependency, but would lose the ORM conventions and the migration and factory tooling.

The trade-off is convention versus control. Lucid follows AdonisJS conventions and integrates with the framework's provider and command system, as shown by the providers and commands directories. Using Knex alone gives more flexibility but requires more boilerplate for model relationships and migrations.

Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-09-18. The license is MIT. The version is 22.4.2 on the 22.x branch, with recent releases from March and April 2026.

Upgrade cost is shaped by the Node 24 engine requirement and the Knex dependency. The 22.4.1 release unlocked the Knex version, suggesting the project tracks Knex closely and may need updates when Knex changes. The modular exports and the database-specific test scripts mean a maintainer must verify changes across multiple database engines. The MIT license allows use, modification, and redistribution, including in commercial products, but this is not legal advice and a team should have counsel review its obligations.

Editorial conclusion

Adopt Lucid if you build AdonisJS applications and need a SQL ORM with migrations and factories. Skip it if you are not using AdonisJS or need an ORM for another Node.js framework. Verify the Node engine requirement and the database driver setup before upgrading.

Frequently asked questions

Official sources

1. adonisjs/lucid on GitHub
2. License: MIT
3. Project website
4. README
5. Releases