velocious 1.0.593 → 1.0.594

package/build/database/query/preloader/has-many.js

@@ -2,7 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
-import preloadQueryForModel from "./query-for-model.js"
+import preloadQueryForModel, { bindPreloadModelClass } from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 /**
@@ -18,19 +18,23 @@ export function hasManyThroughTargetForeignKey(relationship, throughModelClass,
   // (e.g. a default plus an alternate), so picking the first match would otherwise be ambiguous.
   const explicitForeignKey = relationship.getExplicitForeignKey()
 
-  if (explicitForeignKey) return explicitForeignKey
+  if (explicitForeignKey) {
+    return targetModelClass.getAttributeNameToColumnNameMap()[explicitForeignKey] || explicitForeignKey
+  }
 
   for (const targetRelationship of targetModelClass.getRelationships()) {
     if (targetRelationship.getType() != "belongsTo") continue
 
     const relationshipTargetModelClass = targetRelationship.getTargetModelClass()
 
-    if (relationshipTargetModelClass === throughModelClass) {
-      return targetRelationship.getForeignKey()
+    if (!relationshipTargetModelClass) continue
+
+    if (relationshipTargetModelClass.canonicalRecordMetadataModelClass() === throughModelClass.canonicalRecordMetadataModelClass()) {
+      return targetRelationship.getForeignKeyForModelClasses({modelClass: targetModelClass, targetModelClass: throughModelClass})
     }
   }
 
-  return relationship.getForeignKey()
+  return relationship.getForeignKeyForModelClasses({modelClass: throughModelClass, targetModelClass})
 }
 
 export default class VelociousDatabaseQueryPreloaderHasMany {
@@ -107,15 +111,19 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     }
 
     const throughRelationshipName = /** @type {string} */ (this.relationship.through)
-    const parentModelClass = this.relationship.getModelClass()
+    const parentModelClass = this.models[0].getModelClass()
     const throughRelationship = parentModelClass.getRelationshipByName(throughRelationshipName)
-    const throughModelClass = throughRelationship.getTargetModelClass()
+    const rawThroughModelClass = throughRelationship.getTargetModelClass()
+
+    if (!rawThroughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
 
-    if (!throughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
+    const throughModelClass = bindPreloadModelClass(this.models, rawThroughModelClass)
 
-    const targetModelClass = this.relationship.getTargetModelClass()
+    const rawTargetModelClass = this.relationship.getTargetModelClass()
 
-    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+    if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
 
     const targetForeignKey = hasManyThroughTargetForeignKey(this.relationship, throughModelClass, targetModelClass)
     const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [targetForeignKey])
@@ -127,7 +135,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     await ensureModelClassInitialized(throughModelClass, configuration, modelsToLoad[0])
     await ensureModelClassInitialized(targetModelClass, configuration, modelsToLoad[0])
 
-    const throughForeignKey = throughRelationship.getForeignKey()
+    const throughForeignKey = throughRelationship.getForeignKeyForModelClasses({modelClass: parentModelClass, targetModelClass: throughModelClass})
 
     /**
      * Models primary key values.
@@ -260,16 +268,19 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
    * @returns {Promise<import("../../record/index.js").default[]>} - Loaded target models.
    */
   async _runDirect() {
-    const foreignKey = this.relationship.getForeignKey()
     const primaryKey = this.relationship.getPrimaryKey()
 
     if (!primaryKey) {
       throw new Error(`${this.relationship.getModelClass().name}#${this.relationship.getRelationshipName()} doesn't have a primary key`)
     }
 
-    const targetModelClass = this.relationship.getTargetModelClass()
+    const rawTargetModelClass = this.relationship.getTargetModelClass()
+
+    if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
 
-    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+    const sourceModelClass = this.models[0].getModelClass()
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
+    const foreignKey = this.relationship.getForeignKeyForModelClasses({modelClass: sourceModelClass, targetModelClass})
 
     const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [foreignKey])
 

package/build/database/query/preloader/has-one.js

@@ -2,7 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
-import preloadQueryForModel from "./query-for-model.js"
+import preloadQueryForModel, { bindPreloadModelClass } from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryPreloaderHasOne {
@@ -32,13 +32,16 @@ export default class VelociousDatabaseQueryPreloaderHasOne {
      * @type {Record<number | string, Array<import("../../record/index.js").default>>} */
     const modelsByPrimaryKeyValue = {}
 
-    const foreignKey = this.relationship.getForeignKey()
     const primaryKey = this.relationship.getPrimaryKey()
     const relationshipName = this.relationship.getRelationshipName()
 
-    const targetModelClass = this.relationship.getTargetModelClass()
+    const rawTargetModelClass = this.relationship.getTargetModelClass()
 
-    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+    if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    const sourceModelClass = this.models[0].getModelClass()
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
+    const foreignKey = this.relationship.getForeignKeyForModelClasses({modelClass: sourceModelClass, targetModelClass})
 
     /**
      * Preload collections.

package/build/database/query/preloader/query-for-model.js

@@ -1,5 +1,20 @@
 // @ts-check
 
+/**
+ * Binds a preload target to the source records' physical database generation.
+ * @template {typeof import("../../record/index.js").default} MC
+ * @param {import("../../record/index.js").default[]} models - Source records.
+ * @param {MC} ModelClass - Target model class.
+ * @returns {MC} - Generation-bound target model class.
+ */
+export function bindPreloadModelClass(models, ModelClass) {
+  const sourceModel = models[0]
+
+  if (!sourceModel) throw new Error("Cannot bind a preload model class without source records")
+
+  return /** @type {MC} */ (sourceModel.getModelClass().bindRecordMetadataModelClass(ModelClass))
+}
+
 /**
  * Builds a target query preserving the explicit database operation owned by
  * the source records.
@@ -13,5 +28,5 @@ export default function preloadQueryForModel(models, ModelClass) {
 
   if (!sourceModel) throw new Error("Cannot build a preload query without source records")
 
-  return sourceModel.queryForModel(ModelClass)
+  return sourceModel.queryForModel(bindPreloadModelClass(models, ModelClass))
 }

package/build/database/query/preloader.js

@@ -88,7 +88,7 @@ export default class VelociousDatabaseQueryPreloader {
   static async preload(models, queryOrSpec, {force = false} = {}) {
     if (models.length == 0) return
 
-    const modelClass = /** @type {typeof import("../record/index.js").default} */ (models[0].constructor)
+    const modelClass = models[0].getModelClass()
     const isQuery = Boolean(queryOrSpec) && typeof queryOrSpec == "object" && "_preload" in queryOrSpec
     // Reuse the query builder's preload/select normalization for raw specs
     // instead of duplicating it here.
@@ -176,15 +176,17 @@ export default class VelociousDatabaseQueryPreloader {
 
             if (models.length == 0) continue
 
-            const targetModelClass = configuration.getModelClass(className)
+            const targetModelClass = this.modelClass.bindRecordMetadataModelClass(configuration.getModelClass(className))
             const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models, preload: normalizedPreload, selection: this.selection})
 
             await preloader.run()
           }
         } else {
-          const targetModelClass = relationship.getTargetModelClass()
+          const rawTargetModelClass = relationship.getTargetModelClass()
 
-          if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+          if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+          const targetModelClass = this.modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
           const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models: targetModels, preload: normalizedPreload, selection: this.selection})
 

package/build/database/query/query-data.js

@@ -153,13 +153,13 @@ function resolveTargetModelClass(rootModelClass, chain) {
 
   for (const segment of chain) {
     const relationship = modelClass.getRelationshipByName(segment)
-    const target = relationship.getTargetModelClass()
+    const rawTarget = relationship.getTargetModelClass()
 
-    if (!target) {
+    if (!rawTarget) {
       throw new Error(`queryData: could not resolve target model for ${modelClass.name}#${segment}`)
     }
 
-    modelClass = target
+    modelClass = modelClass.bindRecordMetadataModelClass(rawTarget)
   }
 
   return modelClass

package/build/database/query/where-model-class-hash.js

@@ -403,9 +403,11 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
       if (relationship && tuples) {
         if (index > 0) sql += " AND "
 
-        const targetModelClass = relationship.getTargetModelClass()
+        const rawTargetModelClass = relationship.getTargetModelClass()
 
-        if (!targetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+        if (!rawTargetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+
+        const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
         const nestedPath = path.concat([whereKey])
         const nestedTableName = modelQuery.getTableReferenceForJoin(...nestedPath)
@@ -431,9 +433,11 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
           throw new Error(`Unknown relationship "${whereKey}" for ${modelClass.name}`)
         }
 
-        const targetModelClass = relationship.getTargetModelClass()
+        const rawTargetModelClass = relationship.getTargetModelClass()
+
+        if (!rawTargetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
 
-        if (!targetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+        const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
         const nestedHash = /** @type {WhereHash} */ (whereValue)
         const nestedPath = path.concat([whereKey])

package/build/database/query/with-count.js

@@ -155,13 +155,14 @@ function queryForEntry({entry, modelClass, sourceModel}) {
     throw new Error(`withCount currently supports only hasMany relationships; ${modelClass.name}#${entry.relationshipName} is ${relationship.type}`)
   }
 
-  const targetModelClass = relationship.getTargetModelClass()
+  const rawTargetModelClass = relationship.getTargetModelClass()
 
-  if (!targetModelClass) {
+  if (!rawTargetModelClass) {
     throw new Error(`withCount: could not resolve target model for ${modelClass.name}#${entry.relationshipName}`)
   }
 
-  const foreignKey = relationship.getForeignKey()
+  const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
+  const foreignKey = relationship.getForeignKeyForModelClasses({modelClass, targetModelClass})
   /**
    * Mandatory cohort conditions.
    * @type {Record<string, ReturnType<typeof JSON.parse>>} */

package/build/database/record/index.js

@@ -24,6 +24,11 @@
 
 /** @typedef {import("../../configuration-types.js").TenantDatabaseProviderType} TenantDatabaseProviderType */
 
+/**
+ * Schema metadata cached for one record class and physical database generation.
+ * @typedef {boolean | null | string | undefined | Promise<void> | string[] | import("../drivers/base-column.js").default[] | import("../drivers/base-table.js").default | Record<string, string> | Record<string, string | undefined> | Record<string, import("../drivers/base-column.js").default>} RecordMetadataValue
+ */
+
 import AdvisoryLockRunner, {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError} from "../advisory-lock-runner.js"
 import BelongsToInstanceRelationship from "./instance-relationships/belongs-to.js"
 import BelongsToRelationship from "./relationships/belongs-to.js"
@@ -73,6 +78,39 @@ const declaredBooleanTruthyValues = new Set([1, true, "1"])
 /** Stored values that a declared `"boolean"` cast reads back as `false`. */
 const declaredBooleanFalsyValues = new Set([0, false, "0"])
 
+/** Static record metadata fields isolated per physical database/schema generation. */
+const recordMetadataPropertyNames = new Set([
+  "_attributeNameToColumnName",
+  "_columnNameToAttributeName",
+  "_columnNames",
+  "_columns",
+  "_columnsAsHash",
+  "_columnTypeByName",
+  "_databaseType",
+  "_initialized",
+  "_initializeRecordPromise",
+  "_table"
+])
+
+/** @type {WeakMap<typeof import("./index.js").default, Map<string, Map<string, RecordMetadataValue>>>} */
+const recordMetadataValuesByModel = new WeakMap()
+
+/**
+ * Returns the generation-keyed metadata store owned by one canonical model.
+ * @param {typeof import("./index.js").default} modelClass - Canonical model class.
+ * @returns {Map<string, Map<string, RecordMetadataValue>>} - Metadata store.
+ */
+function recordMetadataValuesFor(modelClass) {
+  let values = recordMetadataValuesByModel.get(modelClass)
+
+  if (!values) {
+    values = new Map()
+    recordMetadataValuesByModel.set(modelClass, values)
+  }
+
+  return values
+}
+
 class ValidationError extends Error {
   /**
    * Narrows the runtime value to the documented type.
@@ -236,6 +274,15 @@ class VelociousDatabaseRecord {
    * @type {Promise<void> | null | undefined} */
   static _initializeRecordPromise
 
+  /** @type {typeof VelociousDatabaseRecord | undefined} Canonical model class exposed only by an operation-bound metadata proxy. */
+  static _recordMetadataModelClass
+
+  /** @type {((modelClass: typeof VelociousDatabaseRecord) => typeof VelociousDatabaseRecord) | undefined} Binds related generated model classes to the same operation metadata generation. */
+  static _recordMetadataBinder
+
+  /** @type {import("../operation.js").default | undefined} Operation exposed only by a constructing metadata proxy. */
+  static _recordMetadataOperation
+
   /**
    * Narrows the runtime value to the documented type.
    * @type {boolean | undefined} */
@@ -360,10 +407,32 @@ class VelociousDatabaseRecord {
     return defineModelScope({
       callback,
       modelClass: this,
-      startQuery: () => this._newQuery()
+      startQuery: (modelClass = this) => {
+        // This backend scope factory can only be invoked through a DatabaseRecord class.
+        const BackendModelClass = /** @type {typeof VelociousDatabaseRecord} */ (modelClass)
+
+        return BackendModelClass._newQuery()
+      }
     })
   }
 
+  /**
+   * Returns the application model class behind an operation-bound metadata view.
+   * @returns {typeof VelociousDatabaseRecord} - Canonical model class.
+   */
+  static canonicalRecordMetadataModelClass() {
+    return this._recordMetadataModelClass || this
+  }
+
+  /**
+   * Binds a relationship target to this model class's metadata generation.
+   * @param {typeof VelociousDatabaseRecord} modelClass - Relationship target.
+   * @returns {typeof VelociousDatabaseRecord} - Generation-bound target, or the unchanged target for legacy queries.
+   */
+  static bindRecordMetadataModelClass(modelClass) {
+    return this._recordMetadataBinder ? this._recordMetadataBinder(modelClass) : modelClass
+  }
+
   static getColumnNameToAttributeNameMap() {
     if (!this._columnNameToAttributeName) {
       /**
@@ -1470,6 +1539,68 @@ class VelociousDatabaseRecord {
     this._columnTypeByName = undefined
     this._attributeNameToColumnName = undefined
     this._columnNameToAttributeName = undefined
+
+    if (!this._recordMetadataModelClass) this.clearRecordMetadataValues()
+  }
+
+  /**
+   * Static fields that belong to one physical database/schema generation.
+   * @returns {Set<string>} - Metadata property names.
+   */
+  static recordMetadataPropertyNames() {
+    return recordMetadataPropertyNames
+  }
+
+  /**
+   * Reads one operation-bound metadata field.
+   * @param {string} metadataKey - Physical database and schema generation key.
+   * @param {string} property - Static metadata property.
+   * @returns {RecordMetadataValue} - Stored metadata value.
+   */
+  static recordMetadataValue(metadataKey, property) {
+    return recordMetadataValuesFor(this).get(metadataKey)?.get(property)
+  }
+
+  /**
+   * Writes one operation-bound metadata field.
+   * @param {string} metadataKey - Physical database and schema generation key.
+   * @param {string} property - Static metadata property.
+   * @param {RecordMetadataValue} value - Metadata value.
+   * @returns {void}
+   */
+  static setRecordMetadataValue(metadataKey, property, value) {
+    let values = recordMetadataValuesFor(this).get(metadataKey)
+
+    if (!values) {
+      values = new Map()
+      recordMetadataValuesFor(this).set(metadataKey, values)
+    }
+
+    values.set(property, value)
+  }
+
+  /** Clears every tenant/generation metadata snapshot for this model. */
+  static clearRecordMetadataValues() {
+    recordMetadataValuesByModel.delete(this)
+  }
+
+  /**
+   * Clears snapshots whose key belongs to one physical database identity.
+   * @param {string} databaseIdentity - Logical identifier plus pool reuse key.
+   * @returns {void}
+   */
+  static clearRecordMetadataValuesForDatabaseIdentity(databaseIdentity) {
+    const values = recordMetadataValuesByModel.get(this)
+
+    if (!values) return
+
+    const metadataPrefix = `${databaseIdentity.length}:${databaseIdentity}:`
+
+    for (const metadataKey of values.keys()) {
+      if (metadataKey.startsWith(metadataPrefix)) values.delete(metadataKey)
+    }
+
+    if (values.size === 0) recordMetadataValuesByModel.delete(this)
   }
 
   /**
@@ -1484,8 +1615,10 @@ class VelociousDatabaseRecord {
     if (!configuration) throw new Error(`No configuration given for ${this.name}`)
 
     this.resetRecordMetadata()
-    this._configuration = configuration
-    this._configuration.registerModelClass(this)
+    const modelClass = this._recordMetadataModelClass || this
+
+    modelClass._configuration = configuration
+    configuration.registerModelClass(modelClass)
   }
 
   /**
@@ -1637,7 +1770,10 @@ class VelociousDatabaseRecord {
 
       if (!locales) throw new Error("Locales hasn't been set in the configuration")
 
-      await this.getTranslationClass().initializeRecord({
+      const TranslationClass = this.getTranslationClass()
+      const BoundTranslationClass = this._recordMetadataBinder ? this._recordMetadataBinder(TranslationClass) : TranslationClass
+
+      await BoundTranslationClass.initializeRecord({
         configuration: this._getConfiguration(),
         connection
       })
@@ -1825,6 +1961,8 @@ class VelociousDatabaseRecord {
   getModelClass() {
     const modelClass = /** @type {typeof VelociousDatabaseRecord} */ (this.constructor)
 
+    if (this._databaseOperation) return this._databaseOperation.modelClass(modelClass)
+
     return modelClass
   }
 
@@ -3092,8 +3230,10 @@ class VelociousDatabaseRecord {
    * @returns {ModelClassQuery<MC>} - The new query.
    */
   static _newQuery(args = {}) {
-    const {driver = () => this.connection(), operation, ...restArgs} = args
+    const {driver: givenDriver, operation: givenOperation, ...restArgs} = args
     restArgsError(restArgs)
+    const operation = givenOperation || this._recordMetadataOperation
+    const driver = givenDriver || (operation ? operation.connection() : () => this.connection())
     this._assertHasBeenInitialized()
     const handler = new Handler()
     const query = new ModelClassQuery({
@@ -3450,6 +3590,9 @@ class VelociousDatabaseRecord {
    * @param {WriteAttributes} changes - Changes.
    */
   constructor(changes = /** @type {WriteAttributes} */ ({})) {
+    const ModelClass = /** @type {typeof VelociousDatabaseRecord} */ (new.target)
+
+    this._databaseOperation = ModelClass._recordMetadataOperation
     this.getModelClass()._assertHasBeenInitialized()
     this._attributes = {}
     this._changes = {}

package/build/database/record/instance-relationships/base.js

@@ -62,6 +62,19 @@ export default class VelociousDatabaseRecordBaseInstanceRelationship {
     throw new Error("'build' not implemented")
   }
 
+  /**
+   * Resolves a relationship target through the source record's operation and
+   * metadata generation before construction.
+   * @returns {TMC | undefined} - Bound target model class.
+   */
+  getBoundTargetModelClass() {
+    const targetModelClass = this.getTargetModelClass()
+
+    if (!targetModelClass) return undefined
+
+    return /** @type {TMC} */ (this.getModel().getModelClass().bindRecordMetadataModelClass(targetModelClass))
+  }
+
   /**
    * Runs get auto save.
    * @returns {boolean | undefined} Whether the relationship should be auto-saved before saving the parent model

package/build/database/record/instance-relationships/belongs-to.js

@@ -23,7 +23,7 @@ export default class VelociousDatabaseRecordBelongsToInstanceRelationship extend
    * @returns {InstanceType<TMC>} - The build.
    */
   build(data) {
-    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
+    const TargetModelClass = this.getBoundTargetModelClass()
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model")
 

package/build/database/record/instance-relationships/has-many.js

@@ -25,7 +25,7 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
    */
   build(data) {
     // Spawn new model of the targeted class
-    const targetModelClass = this.getTargetModelClass()
+    const targetModelClass = this.getBoundTargetModelClass()
 
     if (!targetModelClass) throw new Error("Can't build a new record without a taget model class")
 
@@ -58,7 +58,10 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
     const parentModel = this.getModel()
 
     if (parentModel.isPersisted()) {
-      const foreignKeyName = this.getForeignKey()
+      const foreignKeyName = this.getRelationship().getForeignKeyForModelClasses({
+        modelClass: parentModel.getModelClass(),
+        targetModelClass
+      })
       const columnNameMap = targetModelClass.getColumnNameToAttributeNameMap()
       const foreignKeyAttributeName = columnNameMap[foreignKeyName]
       if (!foreignKeyAttributeName) throw new Error(`Unknown foreign key attribute name for ${foreignKeyName}`)

package/build/database/record/instance-relationships/has-one.js

@@ -28,7 +28,7 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
    * @returns {InstanceType<TMC>} - The build.
    */
   build(data) {
-    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
+    const TargetModelClass = this.getBoundTargetModelClass()
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model class")
 

package/build/database/record/relationships/base.js

@@ -117,6 +117,23 @@ export default class VelociousDatabaseRecordBaseRelationship {
     throw new Error("getForeignKey not implemented")
   }
 
+  /**
+   * Resolves an attribute-form foreign key through the model class that owns the physical column.
+   * @param {object} args - Bound relationship model classes.
+   * @param {typeof import("../index.js").default} args.modelClass - Relationship source model class.
+   * @param {typeof import("../index.js").default} args.targetModelClass - Relationship target model class.
+   * @returns {string} - Physical foreign-key column name.
+   */
+  getForeignKeyForModelClasses({modelClass, targetModelClass}) {
+    this.getForeignKey()
+
+    if (!this.foreignKey) throw new Error(`Relationship ${this.modelClass.name}#${this.relationshipName} did not resolve a foreign key`)
+
+    const foreignKeyModelClass = this.getType() === "belongsTo" ? modelClass : targetModelClass
+
+    return foreignKeyModelClass.getAttributeNameToColumnNameMap()[this.foreignKey] || this.foreignKey
+  }
+
   /**
    * Runs get inverse of.
    * @abstract