module objection

const objection = require('objection');
const { Model, ref } = require('objection');

The objection module is what you get when you import objection. It has a bunch of properties that are listed below.

Model

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

The model class

transaction

const { transaction } = require('objection');

The transaction function

ref

const { ref } = require('objection');

Factory function that returns a ReferenceBuilder instance, that makes it easier to refer to tables, columns, json attributes etc. ReferenceBuilder can also be used to type cast and alias the references.

See FieldExpression for more information about how to refer to json fields.

Examples
const { ref } = require('objection');

await Model.query()
  .select([
    'id',
    ref('Model.jsonColumn:details.name').castText().as('name'),
    ref('Model.jsonColumn:details.age').castInt().as('age')
  ])
  .join(
    'OtherModel',
    ref('Model.jsonColumn:details.name').castText(),
    '=',
    ref('OtherModel.name')
  )
  .where('age', '>', ref('OtherModel.ageLimit'));

raw

const { raw } = require('objection');

Factory function that returns a RawBuilder instance. RawBuilder is a wrapper for knex raw method that doesn't depend on knex. Instances of RawBuilder are converted to knex raw instances lazily when the query is executed.

Also see the raw query recipe.

Examples

When using raw SQL segments in queries, it's a good idea to use placeholders instead of adding user input directly to the SQL to avoid injection errors. Placeholders are sent to the database engine which then takes care of interpolating the SQL safely.

You can use ?? as a placeholder for identifiers (column names, aliases etc.) and ? for values.

const { raw } = require('objection');

const result = await Person
  .query()
  .select(raw('coalesce(sum(??), 0) as ??', ['age', 'ageSum']))
  .where('age', '<', raw('? + ?', [50, 25]));

console.log(result[0].ageSum);

You can use raw in insert and update queries too:

await Person
  .query()
  .patch({
    age: raw('age + ?', 10)
  })

You can also use named placeholders. :someName: for identifiers (column names, aliases etc.) and :someName for values.

await Person
  .query()
  .select(raw('coalesce(sum(:sumColumn:), 0) as :alias:', {
    sumColumn: 'age',
    alias: 'ageSum'
  }))
  .where('age', '<', raw(':value1 + :value2', {
    value1: 50,
    value2: 25
  }));

You can nest ref, raw, lit and query builders (both knex and objection) in raw calls

const { lit } = require('objection')

await Person
  .query()
  .select(raw('coalesce(:sumQuery, 0) as :alias:', {
    sumQuery: Person.query().sum('age'),
    alias: 'ageSum'
  }))
  .where('age', '<', raw(':value1 + :value2', {
    value1: lit(50)
    value2: knex.raw('25')
  }));

lit

const { lit } = require('objection')

Factory function that returns a LiteralBuilder instance. LiteralBuilder helps build literals of different types.

Examples
const { lit, ref } = require('objection');

// Compare json objects
await Model
  .query()
  .where(
    ref('Model.jsonColumn:details'),
    '=',
    lit({name: 'Jennifer', age: 29})
  )

// Insert an array literal
await Model
  .query()
  .insert({
    numbers: lit([1, 2, 3]).asArray().castTo('real[]')
  })

mixin

const { mixin } = require('objection');

The mixin helper for applying multiple plugins.

Examples
const { mixin, Model } = require('objection');

class Person extends mixin(Model, [
  SomeMixin,
  SomeOtherMixin,
  EvenMoreMixins,
  LolSoManyMixins,
  ImAMixinWithOptions({foo: 'bar'})
]) {

}

compose

const { compose } = require('objection');

The compose helper for applying multiple plugins.

Examples
const { compose, Model } = require('objection');

const mixins = compose(
  SomeMixin,
  SomeOtherMixin,
  EvenMoreMixins,
  LolSoManyMixins,
  ImAMixinWithOptions({foo: 'bar'})
);

class Person extends mixins(Model) {

}

snakeCaseMappers

const { snakeCaseMappers } = require('objection');

Function for adding snake_case to camelCase conversion to objection models. Better documented here. The snakeCaseMappers function accepts an options object. The available options are:

Option Type Description
upperCase boolean Set to true if your columns are UPPER_SNAKE_CASED.
Examples
const { Model, snakeCaseMappers } = require('objection');

class Person extends Model {
  static get columnNameMappers() {
    return snakeCaseMappers();
  }
}

If your columns are UPPER_SNAKE_CASE

const { Model, snakeCaseMappers } = require('objection');

class Person extends Model {
  static get columnNameMappers() {
    return snakeCaseMappers({ upperCase: true });
  }
}

knexSnakeCaseMappers

const { knexSnakeCaseMappers } = require('objection');

Function for adding a snake_case to camelCase conversion to knex. Better documented here. The knexSnakeCaseMappers function accepts an options object. The available options are:

Option Type Description
upperCase boolean Set to true if your columns are UPPER_SNAKE_CASED.
Examples
const { knexSnakeCaseMappers } = require('objection');
const Knex = require('knex');

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  }

  ...knexSnakeCaseMappers()
});

If your columns are UPPER_SNAKE_CASE

const { knexSnakeCaseMappers } = require('objection');
const Knex = require('knex');

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  }

  ...knexSnakeCaseMappers({ upperCase: true })
});

For older nodes:

const Knex = require('knex');
const knexSnakeCaseMappers = require('objection').knexSnakeCaseMappers;

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  },

  ...knexSnakeCaseMappers()
});

knexIdentifierMapping

const { knexIdentifierMapping } = require('objection');

Like knexSnakeCaseMappers, but can be used to make an arbitrary static mapping between column names and property names. In the examples, you would have identifiers MyId, MyProp and MyAnotherProp in the database and you would like to map them into id, prop and anotherProp in the code.

Examples
const { knexIdentifierMapping } = require('objection');
const Knex = require('knex');

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  }

  ...knexIdentifierMapping({
    MyId: 'id',
    MyProp: 'prop',
    MyAnotherProp: 'anotherProp'
  })
});

Note that you can pretty easily define the conversions in some static property of your model. In this example we have added a property column to jsonSchema and use that to create the mapping object.

const { knexIdentifierMapping } = require('objection');
const Knex = require('knex');
const path = require('path')
const fs = require('fs');

// Path to your model folder.
const MODELS_PATH = path.join(__dirname, 'models');

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  }

  // Go through all models and add conversions using the custom property
  // `column` in json schema.
  ...knexIdentifierMapping(fs.readdirSync(MODELS_PATH)
    .filter(it => it.endsWith('.js'))
    .map(it => require(path.join(MODELS_PATH, it)))
    .reduce((mapping, modelClass) => {
      const properties = modelClass.jsonSchema.properties;
      return Object.keys(properties).reduce((mapping, propName) => {
        mapping[properties[propName].column] = propName;
        return mapping;
      }, mapping);
    }, {});
  )
});

For older nodes:

const Knex = require('knex');
const knexIdentifierMapping = require('objection').knexIdentifierMapping;

const knex = Knex({
  client: 'postgres',

  connection: {
    host: '127.0.0.1',
    user: 'objection',
    database: 'objection_test'
  },

  ...knexIdentifierMapping({
    MyId: 'id',
    MyProp: 'prop',
    MyAnotherProp: 'anotherProp'
  })
});

ValidationError

const { ValidationError } = require('objection');

The ValidationError class.

NotFoundError

const { NotFoundError } = require('objection');

The NotFoundError class.