objection 3.2.0 → 3.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![Tests](https://github.com/ditojs/objection/actions/workflows/test.yml/badge.svg)](https://github.com/ditojs/objection/actions)
 [![Join the chat at https://gitter.im/Vincit/objection.js](https://badges.gitter.im/Vincit/objection.js.svg)](https://gitter.im/Vincit/objection.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-# [Objection.js](https://vincit.github.io/objection.js)
+# [Objection.js](https://ditojs.github.io/objection/)
 
 Objection.js is an [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) for [Node.js](https://nodejs.org/) that aims to stay out of your way and make it as easy as possible to use the full power of SQL and the underlying database engine while still making the common stuff easy and enjoyable.
 
@@ -13,13 +13,13 @@ Objection.js is built on an SQL query builder called [knex](http://knexjs.org).
 
 What objection.js gives you:
 
-- **An easy declarative way of [defining models](https://vincit.github.io/objection.js/guide/models.html) and relationships between them**
-- **Simple and fun way to [fetch, insert, update and delete](https://vincit.github.io/objection.js/guide/query-examples.html) objects using the full power of SQL**
-- **Powerful mechanisms for [eager loading](https://vincit.github.io/objection.js/guide/query-examples.html#eager-loading), [inserting](https://vincit.github.io/objection.js/guide/query-examples.html#graph-inserts) and [upserting](https://vincit.github.io/objection.js/guide/query-examples.html#graph-upserts) object graphs**
-- **Easy to use [transactions](https://vincit.github.io/objection.js/guide/transactions.html)**
+- **An easy declarative way of [defining models](https://ditojs.github.io/objection/guide/models.html) and relationships between them**
+- **Simple and fun way to [fetch, insert, update and delete](https://ditojs.github.io/objection/guide/query-examples.html) objects using the full power of SQL**
+- **Powerful mechanisms for [eager loading](https://ditojs.github.io/objection/guide/query-examples.html#eager-loading), [inserting](https://ditojs.github.io/objection/guide/query-examples.html#graph-inserts) and [upserting](https://ditojs.github.io/objection/guide/query-examples.html#graph-upserts) object graphs**
+- **Easy to use [transactions](https://ditojs.github.io/objection/guide/transactions.html)**
 - **Official [TypeScript](https://github.com/ditojs/objection/blob/main/typings/objection/index.d.ts) support**
-- **Optional [JSON schema](https://vincit.github.io/objection.js/guide/validation.html) validation**
-- **A way to [store complex documents](https://vincit.github.io/objection.js/guide/documents.html) as single rows**
+- **Optional [JSON schema](https://ditojs.github.io/objection/guide/validation.html) validation**
+- **A way to [store complex documents](https://ditojs.github.io/objection/guide/documents.html) as single rows**
 
 What objection.js **doesn't** give you:
 
@@ -31,7 +31,7 @@ What objection.js **doesn't** give you:
 - **A custom query DSL. SQL is used as a query language.**
   This doesn't mean you have to write SQL strings though. A query builder based on [knex](http://knexjs.org) is
   used to build the SQL. However, if the query builder fails you for some reason, raw SQL strings can be easily
-  written using the [raw](https://vincit.github.io/objection.js/api/objection/#raw) helper function.
+  written using the [raw](https://ditojs.github.io/objection/api/objection/#raw) helper function.
 - **Automatic database schema creation and migration from model definitions.**
   For simple things it is useful that the database schema is automatically generated from the model definitions,
   but usually just gets in your way when doing anything non-trivial. Objection.js leaves the schema related things
@@ -45,9 +45,9 @@ Check out [this issue](https://github.com/Vincit/objection.js/issues/1069) to se
 Shortcuts:
 
 - [Who uses objection.js](https://github.com/Vincit/objection.js/discussions/2464)
-- [API reference](https://vincit.github.io/objection.js/api/query-builder/)
+- [API reference](https://ditojs.github.io/objection/api/query-builder/)
 - [Example projects](https://github.com/Vincit/objection.js/tree/main/examples)
-- [Changelog](https://vincit.github.io/objection.js/release-notes/changelog.html)
-- [v1 -> v2 -> v3 migration guide](https://vincit.github.io/objection.js/release-notes/migration.html)
-- [Contribution guide](https://vincit.github.io/objection.js/guide/contributing.html)
-- [Plugins](https://vincit.github.io/objection.js/guide/plugins.html)
+- [Changelog](https://ditojs.github.io/objection/release-notes/changelog.html)
+- [v1 -> v2 -> v3 migration guide](https://ditojs.github.io/objection/release-notes/migration.html)
+- [Contribution guide](https://ditojs.github.io/objection/guide/contributing.html)
+- [Plugins](https://ditojs.github.io/objection/guide/plugins.html)

package/lib/model/AjvValidator.js

@@ -5,6 +5,7 @@ const addFormats = require('ajv-formats');
 const { Validator } = require('./Validator');
 const { ValidationErrorType } = require('../model/ValidationError');
 const { isObject, once, cloneDeep: lodashCloneDeep, omit } = require('../utils/objectUtils');
+const { parseFieldExpression } = require('../utils/parseFieldExpression');
 
 class AjvValidator extends Validator {
   static init(self, conf) {
@@ -81,13 +82,24 @@ class AjvValidator extends Validator {
       json = cloneDeep(json);
     }
 
-    validator.call(model, json);
+    // Patch objects can contain field expression keys like `'meta:b'` that update
+    // a single property inside a json column. Validate them against the nested
+    // schema by converting them into nested objects like `{ meta: { b: value } }`.
+    const fieldExpressions = options.patch ? nestFieldExpressions(json) : null;
+    const validationJson = fieldExpressions ? fieldExpressions.json : json;
+
+    validator.call(model, validationJson);
     const error = parseValidationError(validator.errors, modelClass, options, this.ajvOptions);
 
     if (error) {
       throw error;
     }
 
+    if (fieldExpressions) {
+      // Copy back the changes made by Ajv options like `coerceTypes` and `removeAdditional`.
+      unnestFieldExpressions(json, fieldExpressions);
+    }
+
     return json;
   }
 
@@ -223,6 +235,116 @@ function parseValidationError(errors, modelClass, options, ajvOptions) {
   });
 }
 
+function nestFieldExpressions(json) {
+  const keys = Object.keys(json);
+
+  if (!keys.some(isFieldExpression)) {
+    return null;
+  }
+
+  const nested = Object.create(null);
+  const paths = new Map();
+  // The objects created here for the nested paths. Other objects are values
+  // of the input json and must not be modified.
+  const createdObjects = new Set();
+
+  for (const key of keys) {
+    if (!isFieldExpression(key)) {
+      nested[key] = json[key];
+      paths.set(key, [key]);
+    }
+  }
+
+  for (const key of keys) {
+    if (isFieldExpression(key)) {
+      const path = fieldExpressionPath(key);
+
+      // Field expressions with array access, and those that conflict with other
+      // keys of the patch, can't be validated without the current value of the
+      // json column. Leave them out of the validation.
+      if (path && setPath(nested, path, json[key], createdObjects)) {
+        paths.set(key, path);
+      }
+    }
+  }
+
+  return { json: nested, paths };
+}
+
+function unnestFieldExpressions(json, { json: nested, paths }) {
+  for (const [key, path] of paths) {
+    let value = nested;
+    let found = true;
+
+    for (const prop of path) {
+      found = isObject(value) && hasOwn(value, prop);
+
+      if (!found) {
+        break;
+      }
+
+      value = value[prop];
+    }
+
+    if (!found) {
+      // Removed by `removeAdditional`.
+      delete json[key];
+    } else if (json[key] !== value) {
+      json[key] = value;
+    }
+  }
+}
+
+function isFieldExpression(key) {
+  return key.indexOf(':') !== -1;
+}
+
+function fieldExpressionPath(key) {
+  let parsed;
+
+  try {
+    parsed = parseFieldExpression(key);
+  } catch (err) {
+    // Not a valid field expression, validate it as a top-level property.
+    return [key];
+  }
+
+  if (parsed.access.some((access) => access.type !== 'object')) {
+    return null;
+  }
+
+  return [parsed.column, ...parsed.access.map((access) => String(access.ref))];
+}
+
+function setPath(obj, path, value, createdObjects) {
+  const last = path.length - 1;
+
+  for (let i = 0; i < last; ++i) {
+    const prop = path[i];
+
+    if (!hasOwn(obj, prop)) {
+      const child = Object.create(null);
+      createdObjects.add(child);
+      obj[prop] = child;
+    } else if (!createdObjects.has(obj[prop])) {
+      return false;
+    }
+
+    obj = obj[prop];
+  }
+
+  if (hasOwn(obj, path[last])) {
+    return false;
+  }
+
+  obj[path[last]] = value;
+  return true;
+}
+
+function hasOwn(obj, prop) {
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+
 function cloneDeep(obj) {
   if (isObject(obj) && obj.$isObjectionModel) {
     return obj.$clone();
@@ -276,7 +398,12 @@ function objectHasDefaults(obj) {
 }
 
 function jsonSchemaWithoutRequired(jsonSchema) {
-  const subSchemaProps = ['anyOf', 'oneOf', 'allOf', 'not', 'then', 'else', 'properties'];
+  // `not` is intentionally left untouched: Stripping `required` inside it
+  // would turn it into a schema that rejects everything (e.g.
+  // `not: { required: ['a'] }` -> `not: {}`). Kept as is, it still holds for
+  // patches: Any property present in the patch is also present in the
+  // resulting object.
+  const subSchemaProps = ['anyOf', 'oneOf', 'allOf', 'then', 'else', 'properties'];
   // `definitions` was renamed to `$defs` in draft 2019-09. Support both.
   const definitionProps = ['definitions', '$defs'];
   return Object.assign(
@@ -318,7 +445,10 @@ function subSchemaWithoutRequired(jsonSchema, prop) {
       } else {
         return {};
       }
-    } else if (jsonSchema.type === 'object' && prop === 'properties') {
+    } else if (prop === 'properties') {
+      // `properties` is a map of property names to schemas, regardless of the
+      // schema's `type` (which may also be e.g. `['object', 'null']`, or be
+      // missing entirely).
       return {
         [prop]: Object.fromEntries(
           Object.entries(jsonSchema[prop]).map(([key, schema]) => [

package/lib/queryBuilder/QueryBuilder.js

@@ -46,6 +46,7 @@ const { FirstOperation } = require('./operations/FirstOperation');
 const { NoneOperation } = require('./operations/NoneOperation');
 const { FromOperation } = require('./operations/FromOperation');
 const { KnexOperation } = require('./operations/KnexOperation');
+const { wrapWhereGroups } = require('./whereGroups');
 
 class QueryBuilder extends QueryBuilderBase {
   static init(self, modelClass) {
@@ -58,8 +59,12 @@ class QueryBuilder extends QueryBuilderBase {
 
     self._allowedGraphExpression = null;
     self._graphModifiersAtPath = [];
+    // The eager algorithm that was most recently used explicitly, see `withGraph()`.
+    self._graphAlgorithm = null;
+    self._isJoinChildQuery = false;
     self._findOperationOptions = modelClass.defaultFindOptions;
     self._relatedQueryFor = null;
+    self._internalSelections = new Set();
 
     self._findOperationFactory = findOperationFactory;
     self._insertOperationFactory = insertOperationFactory;
@@ -78,6 +83,27 @@ class QueryBuilder extends QueryBuilderBase {
     return RelationExpression.create(expr).toPojo();
   }
 
+  childQueryOf(query, options = {}) {
+    super.childQueryOf(query, options);
+
+    if (query) {
+      this._isJoinChildQuery = !!options.isJoinChildQuery;
+
+      if (query.isObjectionQueryBuilder) {
+        this._graphAlgorithm = query._graphAlgorithm;
+      }
+    }
+
+    return this;
+  }
+
+  // Returns true if this query was created for a relation that is loaded using
+  // `withGraphJoined()`. Such queries are only used to build the join and are
+  // never executed themselves.
+  isJoinChildQuery() {
+    return this._isJoinChildQuery;
+  }
+
   tableNameFor(modelClassOrTableName, newTableName) {
     return super.tableNameFor(getTableName(modelClassOrTableName), newTableName);
   }
@@ -191,19 +217,50 @@ class QueryBuilder extends QueryBuilderBase {
   }
 
   withGraphFetched(exp, options = {}) {
-    return this._withGraph(exp, options, getWhereInEagerAlgorithm(this));
+    return this._withGraphUsing(exp, options, getWhereInEagerAlgorithm(this));
   }
 
   withGraphJoined(exp, options = {}) {
-    return this._withGraph(exp, options, getJoinEagerAlgorithm(this));
+    return this._withGraphUsing(exp, options, getJoinEagerAlgorithm(this));
+  }
+
+  // Like `withGraphFetched()` or `withGraphJoined()` with `options.algorithm`
+  // set to 'fetch' or 'join'. Without it, the top-level relations that are
+  // already loaded by one of the algorithms are merged into it, and new ones
+  // use the most recently used algorithm.
+  withGraph(exp, { algorithm, ...options } = {}) {
+    if (algorithm !== undefined) {
+      return this._withGraphUsing(exp, options, getEagerAlgorithmByName(this, algorithm));
+    }
+
+    const parsedExp = parseRelationExpression(this.modelClass(), exp);
+
+    for (const [algorithm, groupExp] of groupByEagerAlgorithm(this, parsedExp)) {
+      this._withGraph(groupExp, options, algorithm);
+    }
+
+    return this;
+  }
+
+  _withGraphUsing(exp, options, algorithm) {
+    this._graphAlgorithm = algorithm;
+    return this._withGraph(exp, options, algorithm);
   }
 
   _withGraph(exp, options, algorithm) {
     const eagerOp = ensureEagerOperation(this, algorithm);
     const parsedExp = parseRelationExpression(this.modelClass(), exp);
 
+    // The `joinOperation` option only applies to the relations of this call,
+    // see `RelationJoiner`. All other options are shared by all calls.
+    const { joinOperation, ...graphOptions } = options;
+
     eagerOp.expression = eagerOp.expression.merge(parsedExp);
-    eagerOp.graphOptions = { ...eagerOp.graphOptions, ...options };
+    eagerOp.graphOptions = { ...eagerOp.graphOptions, ...graphOptions };
+
+    if (joinOperation) {
+      eagerOp.joinOperations.push({ expression: parsedExp, joinOperation });
+    }
 
     checkMixedEager(this);
     checkEager(this);
@@ -355,6 +412,8 @@ class QueryBuilder extends QueryBuilderBase {
 
     builder._allowedGraphExpression = this._allowedGraphExpression;
     builder._graphModifiersAtPath = this._graphModifiersAtPath.slice();
+    builder._graphAlgorithm = this._graphAlgorithm;
+    builder._isJoinChildQuery = this._isJoinChildQuery;
     builder._findOperationOptions = this._findOperationOptions;
     builder._relatedQueryFor = this._relatedQueryFor;
 
@@ -376,8 +435,17 @@ class QueryBuilder extends QueryBuilderBase {
     return builder;
   }
 
+  // Registers a property of the result models that was selected internally,
+  // e.g. by an eager operation, without the user asking for it. Such properties
+  // are omitted from the result models before `runAfter` hooks are called.
+  addInternalSelection(prop) {
+    this._internalSelections.add(prop);
+    return this;
+  }
+
   clearWithGraph() {
     this.clear(EagerOperation);
+    this._graphAlgorithm = null;
     return this;
   }
 
@@ -424,11 +492,27 @@ class QueryBuilder extends QueryBuilderBase {
   async resultSize() {
     const knex = this.knex();
     const builder = this.clone().clear(/orderBy|offset|limit/);
+    const joinEagerOp = builder.findOperation(JoinEagerOperation);
+
+    if (joinEagerOp) {
+      // `withGraphJoined` needs the table metadata to build its selects.
+      await joinEagerOp.onBefore3(builder);
+    }
 
     const countQuery = knex.count('* as count').from((knexBuilder) => {
       // Also clear the order on the built knex query, since `orderBy` calls
       // can be added at build time, e.g. by a relation's `modify`.
-      builder.toKnexQuery(knexBuilder).clearOrder().as('temp');
+      knexBuilder = builder.toKnexQuery(knexBuilder).clearOrder();
+
+      if (joinEagerOp) {
+        // The joins of `withGraphJoined` return one row per joined child.
+        // Count the distinct root models instead.
+        const tableRef = builder.tableRef();
+        const idColumns = builder.modelClass().getIdColumnArray();
+        knexBuilder.clearSelect().distinct(idColumns.map((col) => `${tableRef}.${col}`));
+      }
+
+      knexBuilder.as('temp');
     });
 
     if (this.internalOptions().debug) {
@@ -891,6 +975,26 @@ class QueryBuilder extends QueryBuilderBase {
     return this;
   }
 
+  updateById(id, modelOrObject) {
+    return this.findById(id)
+      .update(modelOrObject)
+      .runBefore((_, builder) => {
+        if (!builder.internalOptions().skipUndefined) {
+          assertIdNotUndefined(id, `undefined was passed to updateById`);
+        }
+      });
+  }
+
+  patchById(id, modelOrObject) {
+    return this.findById(id)
+      .patch(modelOrObject)
+      .runBefore((_, builder) => {
+        if (!builder.internalOptions().skipUndefined) {
+          assertIdNotUndefined(id, `undefined was passed to patchById`);
+        }
+      });
+  }
+
   deleteById(id) {
     return this.findById(id)
       .delete()
@@ -1055,6 +1159,66 @@ function getGraphExpression(builder) {
   );
 }
 
+function getEagerAlgorithmByName(builder, name) {
+  if (name === 'fetch') {
+    return getWhereInEagerAlgorithm(builder);
+  } else if (name === 'join') {
+    return getJoinEagerAlgorithm(builder);
+  } else {
+    throw new Error(`unknown graph algorithm "${name}", expected "fetch" or "join"`);
+  }
+}
+
+function getEagerAlgorithmOfOperation(builder, eagerOp) {
+  if (eagerOp instanceof JoinEagerOperation) {
+    return getJoinEagerAlgorithm(builder);
+  } else if (eagerOp instanceof NaiveEagerOperation) {
+    return getNaiveEagerAlgorithm(builder);
+  } else {
+    return getWhereInEagerAlgorithm(builder);
+  }
+}
+
+// Splits `expression` by its top-level relations into one expression per eager
+// algorithm. Relations that are already loaded by one of the eager operations
+// keep its algorithm, new ones use the most recently used one.
+function groupByEagerAlgorithm(builder, expression) {
+  const defaultAlgorithm = builder._graphAlgorithm || getWhereInEagerAlgorithm(builder);
+  const { node } = expression;
+  const rootProps = {};
+  const groups = new Map();
+
+  for (const key of Object.keys(node)) {
+    if (key.startsWith('$')) {
+      rootProps[key] = node[key];
+    }
+  }
+
+  for (const childName of node.$childNames) {
+    const eagerOp = findEagerOperations(builder).find(
+      (op) => op.expression.node.$allRecursive || op.expression.node[childName],
+    );
+
+    const algorithm = eagerOp ? getEagerAlgorithmOfOperation(builder, eagerOp) : defaultAlgorithm;
+    let group = groups.get(algorithm);
+
+    if (!group) {
+      group = { ...rootProps, $childNames: [] };
+      groups.set(algorithm, group);
+    }
+
+    group.$childNames.push(childName);
+    group[childName] = node[childName];
+  }
+
+  if (groups.size === 0) {
+    // No top-level relations, e.g. `*` or an empty expression.
+    return [[defaultAlgorithm, expression]];
+  }
+
+  return [...groups].map(([algorithm, group]) => [algorithm, RelationExpression.create(group)]);
+}
+
 function getWhereInEagerAlgorithm(builder) {
   return builder.modelClass().WhereInEagerAlgorithm;
 }
@@ -1200,6 +1364,7 @@ function afterExecute(builder, result) {
 
   promise = chainOperationHooks(promise, builder, 'onAfter1');
   promise = chainOperationHooks(promise, builder, 'onAfter2');
+  promise = promise.then((result) => omitInternalSelections(builder, result));
 
   promise = chainHooks(promise, builder, builder.context().runAfter);
   promise = chainHooks(promise, builder, builder.internalContext().runAfter);
@@ -1209,6 +1374,22 @@ function afterExecute(builder, result) {
   return promise;
 }
 
+function omitInternalSelections(builder, result) {
+  const props = builder._internalSelections;
+
+  if (props.size && Array.isArray(result) && isObject(result[0])) {
+    const modelClass = builder.resultModelClass();
+
+    for (const model of result) {
+      for (const prop of props) {
+        modelClass.omitImpl(model, prop);
+      }
+    }
+  }
+
+  return result;
+}
+
 class ReturnImmediatelyException {
   constructor(value) {
     this.value = value;
@@ -1331,7 +1512,7 @@ function callOnBuildHooks(builder) {
   callOnBuildFuncs(builder, builder.internalContext().onBuild);
 
   builder.executeOnBuild();
-  return builder;
+  return wrapWhereGroups(builder);
 }
 
 function callOnBuildFuncs(builder, func) {

package/lib/queryBuilder/QueryBuilderOperationSupport.js

@@ -26,6 +26,7 @@ class QueryBuilderOperationSupport {
     self._parentQuery = null;
     self._isPartialQuery = false;
     self._activeOperations = [];
+    self._whereGroup = null;
   }
 
   static forClass(modelClass) {
@@ -413,6 +414,10 @@ class QueryBuilderOperationSupport {
     const shouldAdd = this.callOperationMethod(operation, 'onAdd', [this, args]);
 
     if (shouldAdd) {
+      if (this._whereGroup) {
+        operation.whereGroup = this._whereGroup;
+      }
+
       if (this._activeOperations.length) {
         const { operation: parentOperation, hookName } = last(this._activeOperations);
         parentOperation.addChildOperation(hookName, operation);

package/lib/queryBuilder/ReferenceBuilder.js

@@ -1,6 +1,9 @@
 'use strict';
 
-const { parseFieldExpression } = require('../utils/parseFieldExpression');
+const {
+  parseFieldExpression,
+  toPostgresJsonPathLiteral,
+} = require('../utils/parseFieldExpression');
 const { isObject } = require('../utils/objectUtils');
 
 class ReferenceBuilder {
@@ -185,8 +188,7 @@ class ReferenceBuilder {
 
     if (this._parsedExpr.access.length > 0) {
       const extractor = this._cast ? '#>>' : '#>';
-      const jsonFieldRef = this._parsedExpr.access.map((field) => field.ref).join(',');
-      return `??${extractor}'{${jsonFieldRef}}'`;
+      return `??${extractor}${toPostgresJsonPathLiteral(this._parsedExpr.access)}`;
     } else {
       return '??';
     }

package/lib/queryBuilder/RelationExpression.js

@@ -355,7 +355,19 @@ function normalizeAllRecursive(node, allRecusive) {
 }
 
 function normalizeChildNames(node) {
-  return (node && node.$childNames && node.$childNames.slice()) || getChildNames(node);
+  const childNames = getChildNames(node);
+
+  if (node && node.$childNames) {
+    // The actual keys of the node are authoritative, since the node may be a
+    // modified copy of `graphExpressionObject()` with a stale `$childNames`.
+    // Keep the order of `$childNames` for the children that still exist.
+    return union(
+      node.$childNames.filter((childName) => childNames.includes(childName)),
+      childNames,
+    );
+  } else {
+    return childNames;
+  }
 }
 
 function findExpressionsAtPath(target, path, results) {

package/lib/queryBuilder/StaticHookArguments.js

@@ -24,7 +24,13 @@ class StaticHookArguments {
 
   get asFindQuery() {
     return () => {
-      return this[BUILDER_SYMBOL].toFindQuery().clearWithGraphFetched().runAfter(asArray);
+      // The `runAfter()` callbacks of the query being executed (including the
+      // ones installed by `throwIfNotFound()` and `traverse()`) are meant for
+      // its result, not for the result of this find query.
+      return this[BUILDER_SYMBOL].toFindQuery()
+        .clear('runAfter')
+        .clearWithGraphFetched()
+        .runAfter(toArray);
     };
   }
 
@@ -97,6 +103,11 @@ class StaticHookArguments {
   }
 }
 
+// Like `asArray()`, but an empty `first()` result becomes an empty array.
+function toArray(result) {
+  return result === undefined ? [] : asArray(result);
+}
+
 function getRelation(op) {
   return op.relation;
 }

package/lib/queryBuilder/graph/GraphUpsert.js

@@ -14,6 +14,7 @@ const { RelationExpression } = require('../RelationExpression');
 const { GraphNodeDbExistence } = require('./GraphNodeDbExistence');
 const { GraphData } = require('./GraphData');
 const { uniqBy, asArray, isObject } = require('../../utils/objectUtils');
+const { deprecate } = require('../../utils/deprecate');
 
 class GraphUpsert {
   constructor({ rootModelClass, objects, upsertOptions }) {
@@ -28,6 +29,23 @@ class GraphUpsert {
     return { skipValidation: true };
   }
 
+  // A graph is written using many insert queries (one per batch and table),
+  // so there's no single insert query an `onConflict` clause could be applied
+  // to. Even applying it to the root table only would be unsound: rows skipped
+  // by `ignore()` aren't returned, which leaves the root models without ids,
+  // so that related rows would be inserted with missing or wrong foreign keys.
+  // The clause is ignored, and a warning is logged once per method.
+  // TODO: Throw an error instead in objection 4.0.
+  static warnOnConflict(builder, method) {
+    if (builder.has(isOnConflictOperation)) {
+      deprecate(
+        `onConflict(), ignore() and merge() are not supported by ${method}(). ` +
+          'Insert the conflicting rows with a separate insert() query instead. ' +
+          'This will throw in objection 4.0.',
+      );
+    }
+  }
+
   run(builder) {
     const modelClass = builder.modelClass();
     const graphOptions = new GraphOptions(this.upsertOpt);
@@ -326,6 +344,10 @@ function executeActions(builder, actions) {
   );
 }
 
+function isOnConflictOperation(op) {
+  return op.name === 'onConflict' || op.name === 'ignore' || op.name === 'merge';
+}
+
 function returnResult(objects, isArray) {
   return () => (isArray ? objects : objects[0]);
 }