objection

library3.1.5jsnpmunverified

Objection.js is a relational query builder and ORM for Node.js, built on top of Knex. Current stable version is 3.1.5, released in 2023, with monthly releases. It provides full SQL power with an intuitive model-based API, supporting eager loading, graph operations, JSON schema validation, and transactions. Key differentiators: it stays close to SQL, does not hide the database behind abstractions, and offers official TypeScript support. All databases supported by Knex are supported (SQLite, PostgreSQL, MySQL). Requires Node >=14 and Knex >=1.0.1 as a peer dependency.

database

npm install objection

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OBJECTION

objection

databasejavascriptv3.1.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Model

✓ import { Model } from 'objection'

✗ const { Model } = require('objection')

Default import is not supported; use named import even in CommonJS with destructuring.

Model

✓ const { Model } = require('objection')

✗ const Model = require('objection').Model

In CommonJS, use destructured require; accessing .Model directly works but is less idiomatic.

raw

✓ import { raw } from 'objection'

✗ import raw from 'objection'

raw is a named export, not default.

transaction

✓ import { transaction } from 'objection'

✗ import transaction from 'objection'

transaction is a named export, not default.

ModelClass types

✓ import { Model } from 'objection' // models extend Model and infer types

✗ import { Model, ModelClass } from 'objection'

ModelClass was removed in v3; use typeof Model instead or infer from class.

Shows basic setup: bind Knex to Model, define a model with JSON schema, create table, insert and query a user.

import { Model } from 'objection'; import Knex from 'knex'; const knex = Knex({ client: 'sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, }); Model.knex(knex); class User extends Model { static get tableName() { return 'users'; } static get jsonSchema() { return { type: 'object', required: ['name'], properties: { id: { type: 'integer' }, name: { type: 'string', minLength: 1 }, }, }; } } async function main() { await knex.schema.createTable('users', (table) => { table.increments('id').primary(); table.string('name'); }); const user = await User.query().insert({ name: 'Alice' }); console.log(user); const fetched = await User.query().findById(1); console.log(fetched); } main().then(() => knex.destroy());

Debug

Known issues

breakingModelClass type removed in v3. Use `typeof Model` instead.

fix

Replace `ModelClass<SomeModel>` with `typeof SomeModel`.

affects: >=3.0.0

breakingStatic method `query()` no longer returns a QueryBuilder. It returns a QueryBuilderType.

fix

If using TypeScript, use `QueryBuilderType<Model>` as return type.

affects: >=3.0.0

deprecated`$relatedQuery()` is deprecated in favor of `relatedQuery()`.

fix

Use `modelInstance.relatedQuery('relationName')` instead of `modelInstance.$relatedQuery('relationName')`.

affects: >=2.2.0

gotchaKnex must be bound to Model before any query operations. Forgetting `Model.knex(knex)` leads to 'knex is not bound' errors.

fix

Call `Model.knex(knex)` with your Knex instance at app startup.

affects: >=1.0.0

gotchaJSON schema validation does not automatically run on updates. Use `$beforeUpdate` or `patch` with validation.

fix

Override `$beforeUpdate` to call `await this.$validate()` or use `allowInsert`/`allowUpdate` options.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Knex is not bound to a model class. Did you forget to call Model.knex(knex)?

Knex instance was not bound to Model.

fix

Add `Model.knex(knex)` in your app initialization after creating the Knex instance.

TypeError: Cannot read properties of undefined (reading 'RelationExpression')

Importing Objection without Knex installed or peer dependency not satisfied.

fix

Install knex as a peer dependency: `npm install knex`.

ObjectionError: Could not find any relation with name 'xyz'

Relation name mismatch in eager loading or relationMapping.

fix

Check that the relation name in `eager()` matches exactly one of the keys in `static get relationMappings()`.

TypeScript error: 'ModelClass' is not exported from 'objection'

ModelClass type was removed in v3.

fix

Use `typeof MyModel` instead of `ModelClass<MyModel>`.

Upgrade

Version history

3.1.5latest on npm

Audit

Dependencies

knexrequiredUnderlying query builder; peer dependency required for all queries and migrations.

Agent activity

4 hits · last 30 days

node

Resources

githubgit://github.com/vincit/objection.js ↗

packageobjection ↗

homepagehttps://github.com/vincit/objection.js#readme ↗