velocious 1.0.593 → 1.0.595

package/README.md

@@ -20,7 +20,7 @@
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))
 * AwesomeTasks-shaped offline sync proof using routed resources, domain commands, signed offline grants, and peer-forwarded mutations (see the [developer guide](docs/shared-resource-sync-guide.md) and [proof](docs/awesome-tasks-offline-sync-proof.md))
 * SQLite web persistence that automatically prefers OPFS, then IndexedDB, and migrates legacy persisted bytes when possible (see [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md))
-* Bounded frontend tenant SQLite handles with durable flush/close, backend-complete deletion, clean-only LRU eviction, and scoped pins (see [docs/frontend-tenant-sqlite-lifecycle.md](docs/frontend-tenant-sqlite-lifecycle.md))
+* Bounded frontend tenant SQLite handles with independently deduplicated per-database migrations/model readiness, React lifecycle integration, durable flush/close, backend-complete deletion, clean-only LRU eviction, and scoped pins (see [docs/frontend-tenant-sqlite-lifecycle.md](docs/frontend-tenant-sqlite-lifecycle.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
@@ -955,7 +955,8 @@ Translated models also get a `currentTranslation` `hasOne` relationship scoped t
 Async class APIs initialize record metadata on first use when a model has not
 already been initialized eagerly. See [docs/model-initialization.md](docs/model-initialization.md)
 for the eager and lazy initialization behavior, including atomic shared bootstrap
-and complete recovery after an eager initialization failure.
+and complete recovery after an eager initialization failure or database-connection
+closure without overlapping stale and current bootstrap side effects.
 
 ## Lifecycle callbacks
 

package/build/configuration.js

@@ -302,8 +302,9 @@ export default class VelociousConfiguration {
      */
     this._initializeModelsPromise = undefined
     /**
-     * In-progress `initialize()` promise, memoized so concurrent callers await
-     * the same bootstrap. Reset to undefined if initialization fails.
+     * Current `initialize()` promise, memoized so concurrent callers await the
+     * same bootstrap. Retained across a connection close until stale bootstrap
+     * work settles, then cleared by identity before the new generation retries.
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
@@ -363,6 +364,15 @@ export default class VelociousConfiguration {
      */
     this._websocketChannelSubscriptions = new Map()
 
+    /**
+     * In-flight local (per-process) websocket channel broadcast deliveries,
+     * launched fire-and-forget from `_broadcastToChannelLocal` so one slow
+     * subscriber never blocks another. Tracked here so
+     * `awaitPendingBroadcasts` can snapshot and drain them before settling.
+     * Settled deliveries are removed by the tracking-level cleanup.
+     * @type {Set<Promise<void>>} */
+    this._localBroadcastDeliveries = new Set()
+
     /**
      * Stores the websocket sessions value.
      * @type {Set<import("./http-server/client/websocket-session.js").default>} - Live websocket sessions, including paused sessions within the grace window.
@@ -1102,6 +1112,18 @@ export default class VelociousConfiguration {
     }
   }
 
+  /**
+   * Invalidates record metadata owned by one closed/deleted physical tenant
+   * database while preserving every other tenant generation.
+   * @param {string} databaseIdentity - Logical identifier plus pool reuse key.
+   * @returns {void}
+   */
+  clearRecordMetadataForDatabaseIdentity(databaseIdentity) {
+    for (const modelClass of Object.values(this.modelClasses)) {
+      modelClass.clearRecordMetadataValuesForDatabaseIdentity(databaseIdentity)
+    }
+  }
+
   /**
    * Runs get database pool type.
    * @param {string} identifier - Identifier.
@@ -2054,10 +2076,25 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initializeModels(args = {type: "server"}) {
+    const modelInitializationGeneration = this._modelInitializationGeneration
+
     if (this._modelsInitialized) return
-    if (this._initializeModelsPromise) return await this._initializeModelsPromise
+    if (this._initializeModelsPromise) {
+      const initializeModelsPromise = this._initializeModelsPromise
+
+      await initializeModelsPromise
+
+      if (this._modelInitializationGeneration === modelInitializationGeneration && !this._modelsInitialized) {
+        if (this._initializeModelsPromise === initializeModelsPromise) {
+          this._initializeModelsPromise = undefined
+        }
+
+        return await this.initializeModels(args)
+      }
+
+      return
+    }
 
-    const modelInitializationGeneration = this._modelInitializationGeneration
     const initializeModelsPromise = (async () => {
       const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
         && process.env.VELOCIOUS_BROWSER_TESTS === "true"
@@ -2110,6 +2147,12 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initialize({type} = {type: "undefined"}) {
+    if (this._closeDatabaseConnectionsPromise) {
+      await this._closeDatabaseConnectionsPromise
+    }
+
+    const initializationGeneration = this._modelInitializationGeneration
+
     if (this._isInitialized) return
     // Memoize the in-progress initialization so concurrent callers await the same
     // bootstrap instead of racing. `_isInitialized` was previously set to `true`
@@ -2117,15 +2160,29 @@ export default class VelociousConfiguration {
     // `pooledRunnerConcurrency > 1` starting several jobs on a cold child) could
     // skip initialization and load models / perform a job while the first call
     // was still awaiting model discovery and initializers. Mirrors connectBeacon.
-    if (this._initializePromise) return await this._initializePromise
+    if (this._initializePromise) {
+      const initializePromise = this._initializePromise
+
+      await initializePromise
+
+      if (this._modelInitializationGeneration === initializationGeneration && !this._isInitialized) {
+        if (this._initializePromise === initializePromise) {
+          this._initializePromise = undefined
+        }
+
+        return await this.initialize({type})
+      }
+
+      return
+    }
 
-    this._initializePromise = (async () => {
+    const initializePromise = (async () => {
       await this.initializeModels({type})
 
       // Model initialization can be invalidated by a concurrent connection close.
       // If models are not ready, stop without marking the configuration initialized
       // so the next caller retries a full bootstrap.
-      if (!this._modelsInitialized) return
+      if (this._modelInitializationGeneration !== initializationGeneration || !this._modelsInitialized) return
 
       await this.getEnvironmentHandler().autoDiscoverResources(this)
       this._mergeDiscoveredAbilityResources()
@@ -2147,22 +2204,28 @@ export default class VelociousConfiguration {
         }
       }
 
-      this._isInitialized = true
+      if (this._modelInitializationGeneration === initializationGeneration) {
+        this._isInitialized = true
+      }
     })()
 
+    this._initializePromise = initializePromise
+
     try {
-      await this._initializePromise
+      await initializePromise
     } catch (error) {
       // Let a later call retry a failed initialization instead of every future
       // caller awaiting the same cached rejection.
-      this._initializePromise = undefined
+      if (this._initializePromise === initializePromise) {
+        this._initializePromise = undefined
+      }
       throw error
     }
 
     // If the inner IIFE returned without marking the configuration initialized
     // (e.g. because models were invalidated mid-bootstrap), clear the promise so
     // a later call retries a full bootstrap.
-    if (!this._isInitialized) {
+    if (!this._isInitialized && this._initializePromise === initializePromise) {
       this._initializePromise = undefined
     }
   }
@@ -2756,8 +2819,13 @@ export default class VelociousConfiguration {
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.awaitPendingBroadcasts === "function") {
+      // Drain the host/worker publish queues (including event-log persistence)
+      // before draining local deliveries, because host dispatch launches the
+      // local deliveries synchronously and they must be part of the snapshot.
       await websocketEvents.awaitPendingBroadcasts()
     }
+
+    await this._awaitLocalBroadcastDeliveries()
   }
 
   /**
@@ -2791,7 +2859,7 @@ export default class VelociousConfiguration {
 
       if (!matches) continue
 
-      void this.withoutCurrentConnectionContexts(() => {
+      const delivery = this.withoutCurrentConnectionContexts(() => {
         return Promise
           .resolve()
           .then(() => this._deliverWebsocketChannelBroadcast(subscription, body, {eventId: meta?.eventId}))
@@ -2799,9 +2867,35 @@ export default class VelociousConfiguration {
             console.error(`broadcastToChannel: ${name} subscription ${subscription.subscriptionId} deliverBroadcast threw`, error)
           })
       })
+
+      // Keep the fire-and-forget delivery (never awaited at broadcast time) but
+      // track it so `awaitPendingBroadcasts` can drain it before settling. Remove
+      // on settle; the failure handler also satisfies the promise so a rejected
+      // delivery never becomes an unhandled rejection.
+      this._localBroadcastDeliveries.add(delivery)
+
+      delivery.then(
+        () => { this._localBroadcastDeliveries.delete(delivery) },
+        () => { this._localBroadcastDeliveries.delete(delivery) }
+      )
     }
   }
 
+  /**
+   * Awaits a snapshot of the in-flight local (per-process) websocket channel
+   * broadcast deliveries. Called from `awaitPendingBroadcasts` after the host
+   * publish queues drain, so every delivery those queues launched is captured.
+   * New deliveries enqueued after the snapshot are not awaited. Individual
+   * delivery errors are isolated per subscriber — the delivery chain already
+   * logs them and resolves — so a snapshotted rejection never fails this barrier.
+   * @returns {Promise<void>}
+   */
+  async _awaitLocalBroadcastDeliveries() {
+    const snapshot = [...this._localBroadcastDeliveries]
+
+    await Promise.allSettled(snapshot)
+  }
+
   /**
    * Runs deliver websocket channel broadcast.
    * @param {import("./http-server/websocket-channel.js").default} subscription - Channel subscription.
@@ -3072,11 +3166,11 @@ export default class VelociousConfiguration {
    * database configuration. No ambient tenant value is read during checkout or
    * execution.
    * @template T
-   * @param {{databaseConfiguration: import("./configuration-types.js").DatabaseConfigurationType, databaseIdentifier: string, name?: string, tenant?: object}} options - Captured operation options.
+   * @param {{databaseConfiguration: import("./configuration-types.js").DatabaseConfigurationType, databaseIdentifier: string, name?: string, schemaGeneration?: string, tenant?: object}} options - Captured operation options.
    * @param {(operation: DatabaseOperation) => Promise<T>} callback - Operation callback.
    * @returns {Promise<T>} - Callback result.
    */
-  async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", tenant, ...restArgs}, callback) {
+  async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", schemaGeneration, tenant, ...restArgs}, callback) {
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withDatabaseOperation requires a databaseIdentifier")
@@ -3095,6 +3189,7 @@ export default class VelociousConfiguration {
         databaseIdentifier,
         enforceCurrentTenantReuseKey: false,
         owner,
+        schemaGeneration,
         tenant
       })
 

package/build/database/drivers/base.js

@@ -195,6 +195,10 @@ export default class VelociousDatabaseDriversBase {
    * Narrows the runtime value to the documented type.
    * @type {TransactionCallbackFrame[]} */
   _transactionCallbackFrames
+  /** @type {Promise<void>} */
+  _transactionCompletionPromise
+  /** @type {(() => void) | undefined} */
+  _resolveTransactionCompletion
   /**
    * Narrows the runtime value to the documented type.
    * @type {Map<string, Promise<ReturnType<typeof JSON.parse>>>} */
@@ -231,6 +235,8 @@ export default class VelociousDatabaseDriversBase {
     this.logger = new Logger(this)
     this._transactionCallbackFrames = []
     this._transactionsCount = 0
+    this._transactionCompletionPromise = Promise.resolve()
+    this._resolveTransactionCompletion = undefined
     this._transactionsActionsMutex = new Mutex()
     this._schemaCache = new Map()
   }
@@ -1426,6 +1432,12 @@ export default class VelociousDatabaseDriversBase {
    */
   insideTransaction() { return this._transactionsCount > 0 }
 
+  /**
+   * Returns the completion promise identifying the current outer transaction.
+   * @returns {Promise<void>} Resolves after that transaction commits or rolls back.
+   */
+  transactionCompletion() { return this._transactionCompletionPromise }
+
   /**
    * Runs start transaction.
    * @param {Pick<QueryOptions, "operationOwner">} [options] - Transaction ownership.
@@ -1446,6 +1458,12 @@ export default class VelociousDatabaseDriversBase {
 
         await this._startTransactionAction(options)
         this._transactionsCount++
+
+        if (this._transactionsCount === 1) {
+          this._transactionCompletionPromise = new Promise((resolve) => {
+            this._resolveTransactionCompletion = resolve
+          })
+        }
       })
 
       if (!blockingOperationLease) return
@@ -1472,9 +1490,20 @@ export default class VelociousDatabaseDriversBase {
     await this._transactionsActionsMutex.sync(async () => {
       await this._commitTransactionAction(options)
       this._transactionsCount--
+      this._resolveCompletedTransaction()
     })
   }
 
+  /** Resolves the current outer transaction completion when it has finished. */
+  _resolveCompletedTransaction() {
+    if (this._transactionsCount !== 0) return
+
+    const resolve = this._resolveTransactionCompletion
+
+    this._resolveTransactionCompletion = undefined
+    if (resolve) resolve()
+  }
+
   /**
    * Runs commit transaction action.
    * @param {Pick<QueryOptions, "operationOwner">} [options] - Transaction ownership.
@@ -2091,6 +2120,7 @@ export default class VelociousDatabaseDriversBase {
         await this._rollbackTransactionAction(options)
       } finally {
         this._transactionsCount--
+        this._resolveCompletedTransaction()
 
         // A rolled-back transaction may have reverted DDL (e.g. a CREATE TABLE
         // run lazily inside the transaction), so any cached schema metadata is

package/build/database/migrator.js

@@ -145,18 +145,75 @@ export default class VelociousDatabaseMigrator {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async migrateFilesFromRequireContext(requireContext) {
-    /**
-     * Files.
-     * @type {import("./migrator/types.js").MigrationObjectType[]} */
-    let files = []
+    const files = this.migrationsFromRequireContext(requireContext)
+
+    await this.configuration.ensureConnections({databaseIdentifiers: this.databaseIdentifiers, name: "Database migrator: migrate require-context files"}, async () => {
+      for (const migration of files) {
+        await this.runMigrationFile({
+          migration,
+          requireMigration: async () => requireContext(migration.file).default
+        })
+      }
+
+      await this._afterMigrations()
+    })
+  }
+
+  /**
+   * Migrates exactly one already-captured physical database. This is the
+   * frontend/tenant counterpart to the ambient multi-database entrypoints:
+   * callers own the captured connection and no configuration fallback is read.
+   * @param {object} args - Captured migration arguments.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} args.databaseConfiguration - Captured physical database configuration.
+   * @param {string} args.databaseIdentifier - Logical database identifier.
+   * @param {import("./drivers/base.js").default} args.db - Captured physical connection.
+   * @param {import("./migrator/types.js").RequireMigrationContextType} args.requireContext - Frontend migration require context.
+   * @returns {Promise<number>} - Number of newly applied migrations.
+   */
+  async migrateRequireContextForDatabase({databaseConfiguration, databaseIdentifier, db, requireContext}) {
+    if (!databaseConfiguration.migrations) return 0
+
+    await MigrationsLedger.ensureTable(db)
+    const appliedVersions = new Set(await MigrationsLedger.appliedVersions(db))
+    const migrations = this.migrationsFromRequireContext(requireContext)
+    let appliedCount = 0
+
+    for (const migration of migrations) {
+      const version = `${migration.date}`
+
+      if (appliedVersions.has(version)) continue
+
+      const MigrationClass = requireContext(migration.file).default
+
+      if (!MigrationClass || typeof MigrationClass !== "function") {
+        throw new Error(`Migration ${migration.file} must export a default migration class. Type: ${typeof MigrationClass}`)
+      }
+      if (!(MigrationClass.getDatabaseIdentifiers() || ["default"]).includes(databaseIdentifier)) continue
+
+      const migrationInstance = new MigrationClass({configuration: this.configuration, databaseIdentifier, db})
+
+      await this.runMigrationUp({migration, migrationInstance})
+      await MigrationsLedger.recordVersion(db, version)
+      appliedVersions.add(version)
+      appliedCount++
+    }
+
+    return appliedCount
+  }
+
+  /**
+   * Parses and orders migrations from a browser/native require context.
+   * @param {import("./migrator/types.js").RequireMigrationContextType} requireContext - Migration require context.
+   * @returns {import("./migrator/types.js").MigrationObjectType[]} - Ordered migrations.
+   */
+  migrationsFromRequireContext(requireContext) {
+    const migrations = []
 
     for (const file of requireContext.keys()) {
-      // "13,14" because somes "require-context"-npm-module deletes first character!?
       const match = file.match(/(\d{13,14})-(.+)\.js$/)
 
       if (!match) continue
 
-      // Fix require-context-npm-module deletes first character
       let fileName = file
       let dateNumber = match[1]
 
@@ -165,30 +222,39 @@ export default class VelociousDatabaseMigrator {
         fileName = `2${fileName}`
       }
 
-      // Parse regex
-      const date = parseInt(dateNumber)
-      const migrationName = match[2]
-      const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
-
-      files.push({
+      migrations.push({
+        date: parseInt(dateNumber),
         file: fileName,
-        date,
-        migrationClassName
+        migrationClassName: inflection.camelize(match[2].replaceAll("-", "_"))
       })
     }
 
-    files = files.sort((migration1, migration2) => migration1.date - migration2.date)
+    return migrations.sort((migration1, migration2) => migration1.date - migration2.date)
+  }
 
-    await this.configuration.ensureConnections({databaseIdentifiers: this.databaseIdentifiers, name: "Database migrator: migrate require-context files"}, async () => {
-      for (const migration of files) {
-        await this.runMigrationFile({
-          migration,
-          requireMigration: async () => requireContext(migration.file).default
-        })
-      }
+  /**
+   * Runs one migration's upward implementation.
+   * @param {object} args - Migration arguments.
+   * @param {import("./migrator/types.js").MigrationObjectType} args.migration - Migration descriptor.
+   * @param {import("./migration/index.js").default} args.migrationInstance - Migration instance.
+   * @returns {Promise<void>} - Resolves after the migration succeeds.
+   */
+  async runMigrationUp({migration, migrationInstance}) {
+    try {
+      await migrationInstance.change()
+    } catch (changeError) {
+      if (!(changeError instanceof NotImplementedError)) throw changeError
+
+      try {
+        await migrationInstance.up()
+      } catch (upError) {
+        if (upError instanceof NotImplementedError) {
+          throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`, {cause: upError})
+        }
 
-      await this._afterMigrations()
-    })
+        throw upError
+      }
+    }
   }
 
   /**

package/build/database/operation.js

@@ -17,9 +17,10 @@ export default class VelociousDatabaseOperation {
    * @param {import("./drivers/base.js").default} args.connection - Pinned physical connection.
    * @param {string} args.databaseIdentifier - Singular database identifier.
    * @param {symbol} args.owner - Opaque pool lease owner.
+   * @param {string} [args.schemaGeneration] - Tenant schema generation owning record metadata.
    * @param {object | undefined} args.tenant - Tenant descriptor captured by the owning handle.
    */
-  constructor({configuration, databaseConfiguration, configurationReuseKey, connection, databaseIdentifier, enforceCurrentTenantReuseKey = true, owner, tenant}) {
+  constructor({configuration, databaseConfiguration, configurationReuseKey, connection, databaseIdentifier, enforceCurrentTenantReuseKey = true, owner, schemaGeneration, tenant}) {
     this._active = true
     this._configuration = configuration
     this._databaseConfiguration = databaseConfiguration || configuration.resolveDatabaseConfiguration(databaseIdentifier, tenant)
@@ -27,7 +28,10 @@ export default class VelociousDatabaseOperation {
     this._databaseIdentifier = databaseIdentifier
     this._enforceCurrentTenantReuseKey = enforceCurrentTenantReuseKey
     this._physicalConnection = connection
+    this._schemaGeneration = schemaGeneration
     this._tenant = tenant
+    /** @type {WeakMap<typeof import("./record/index.js").default, typeof import("./record/index.js").default>} */
+    this._boundModelClasses = new WeakMap()
     this._connection = new OperationConnection({
       connection,
       operation: this,
@@ -45,12 +49,57 @@ export default class VelociousDatabaseOperation {
     this.assertActive()
     this.assertModel(ModelClass)
 
-    return ModelClass._newQuery({
+    return this.modelClass(ModelClass)._newQuery({
       driver: this.connection(),
       operation: this
     })
   }
 
+  /**
+   * Returns a model-class view whose schema metadata is bound to this physical
+   * database generation. Construction still produces the application's original
+   * model class, so lifecycle callbacks and model registries retain class identity.
+   * @template {typeof import("./record/index.js").default} MC
+   * @param {MC} ModelClass - Canonical model class.
+   * @returns {MC} - Operation-bound model class.
+   */
+  modelClass(ModelClass) {
+    if (!this._schemaGeneration) return ModelClass
+
+    const canonicalModelClass = /** @type {MC} */ (ModelClass._recordMetadataModelClass || ModelClass)
+
+    const existing = this._boundModelClasses.get(canonicalModelClass)
+
+    if (existing) return /** @type {MC} */ (existing)
+
+    const databaseIdentity = this.databaseIdentity()
+    const metadataKey = `${databaseIdentity.length}:${databaseIdentity}:${this._schemaGeneration}`
+    const metadataProperties = canonicalModelClass.recordMetadataPropertyNames()
+    const boundModelClass = new Proxy(canonicalModelClass, {
+      construct: (target, args, newTarget) => Reflect.construct(target, args, newTarget),
+      get: (target, property, receiver) => {
+        if (property === "_recordMetadataModelClass") return target
+        if (property === "_recordMetadataBinder") return (/** @type {typeof import("./record/index.js").default} */ targetModelClass) => this.modelClass(targetModelClass)
+        if (property === "_recordMetadataOperation") return this
+        if (typeof property === "string" && metadataProperties.has(property)) return target.recordMetadataValue(metadataKey, property)
+
+        return Reflect.get(target, property, receiver)
+      },
+      set: (target, property, value, receiver) => {
+        if (typeof property === "string" && metadataProperties.has(property)) {
+          target.setRecordMetadataValue(metadataKey, property, value)
+          return true
+        }
+
+        return Reflect.set(target, property, value, receiver)
+      }
+    })
+
+    this._boundModelClasses.set(canonicalModelClass, boundModelClass)
+
+    return /** @type {MC} */ (boundModelClass)
+  }
+
   /**
    * Verifies that a model belongs to this operation's configuration and database.
    * @param {typeof import("./record/index.js").default} ModelClass - Model class to verify.
@@ -162,9 +211,11 @@ export default class VelociousDatabaseOperation {
   async ensureModelInitialized(ModelClass) {
     this.assertActive()
 
-    if (ModelClass.isInitialized()) this.assertModel(ModelClass)
+    const boundModelClass = this.modelClass(ModelClass)
+
+    if (boundModelClass.isInitialized()) this.assertModel(ModelClass)
 
-    await ModelClass.ensureInitialized({
+    await boundModelClass.ensureInitialized({
       configuration: this._configuration,
       connection: this.connection()
     })

package/build/database/query/join-object.js

@@ -54,12 +54,15 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
     for (const joinKey in join) {
       const joinValue = join[joinKey]
       const relationship = modelClass.getRelationshipByName(joinKey)
-      const targetModelClass = relationship.getTargetModelClass()
+      const rawTargetModelClass = relationship.getTargetModelClass()
 
-      if (!targetModelClass) {
+      if (!rawTargetModelClass) {
         throw new Error(`Relationship ${modelClass.name}#${joinKey} has no target model class`)
       }
 
+      const targetModelClass = query.bindModelClass(rawTargetModelClass)
+      const foreignKey = relationship.getForeignKeyForModelClasses({modelClass, targetModelClass})
+
       const joinPath = path.concat([joinKey])
       const parentTableRef = query.getJoinTableReference(path)
       const targetEntry = query._registerJoinPath(joinPath)
@@ -80,9 +83,9 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
 
       if (relationship.getType() == "belongsTo") {
         sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(relationship.getPrimaryKey())} = `
-        sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(relationship.getForeignKey())}`
+        sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(foreignKey)}`
       } else if (relationship.getType() == "hasMany" || relationship.getType() == "hasOne") {
-        sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(relationship.getForeignKey())} = `
+        sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(foreignKey)} = `
         sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(relationship.getPrimaryKey())}`
       } else {
         throw new Error(`Unknown relationship type: ${relationship.getType()}`)