@rvoh/dream 2.18.1 → 2.20.0

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -26,8 +26,8 @@ import MissingRequiredAssociationAndClause from '../../errors/associations/Missi
 import MissingRequiredPassthroughForAssociationAndClause from '../../errors/associations/MissingRequiredPassthroughForAssociationAndClause.js';
 import MissingThroughAssociation from '../../errors/associations/MissingThroughAssociation.js';
 import MissingThroughAssociationSource from '../../errors/associations/MissingThroughAssociationSource.js';
-import ThroughAssociationConditionsIncompatibleWithThroughAssociationSource from '../../errors/associations/ThroughAssociationConditionsIncompatibleWithThroughAssociationSource.js';
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
+import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
 import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
 import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
@@ -55,7 +55,6 @@ import CurriedOpsStatement from '../../ops/curried-ops-statement.js';
 import OpsStatement from '../../ops/ops-statement.js';
 import { DreamConst, primaryKeyTypes } from '../constants.js';
 import DreamTransaction from '../DreamTransaction.js';
-import throughAssociationHasOptionsBesidesThroughAndSource from '../internal/associations/throughAssociationHasOptionsBesidesThroughAndSource.js';
 import associationStringToNameAndAlias from '../internal/associationStringToNameAndAlias.js';
 import executeDatabaseQuery from '../internal/executeDatabaseQuery.js';
 import extractAssignableAssociationAttributes from '../internal/extractAssignableAssociationAttributes.js';
@@ -213,6 +212,10 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             await DreamCLI.logger.logProgress('[dream] sync failed, reverting file contents...', async () => {
                 await CliFileWriter.revert();
             });
+            // rethrow after reverting so callers (e.g. the `psy sync` and
+            // `db:migrate` CLI commands) exit nonzero instead of reporting success
+            // with stale generated types
+            throw error;
         }
     }
     static get syncDialect() {
@@ -441,6 +444,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.max;
     }
+    /**
+     * Retrieves the max value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().maxBy('name', 'score')
+     * // Map(2) { 'primary' => 9, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the max of within each group
+     * @returns A Map from each present group value to the max of the aggregated column in that group
+     */
+    async maxBy(groupColumn, aggregatedColumn) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { max } = this.dbFor('select').fn;
+        return this.groupedAggregate(groupColumn, max(aggregatedColumn));
+    }
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -464,6 +485,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.min;
     }
+    /**
+     * Retrieves the min value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().minBy('name', 'score')
+     * // Map(2) { 'primary' => 1, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the min of within each group
+     * @returns A Map from each present group value to the min of the aggregated column in that group
+     */
+    async minBy(groupColumn, aggregatedColumn) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { min } = this.dbFor('select').fn;
+        return this.groupedAggregate(groupColumn, min(aggregatedColumn));
+    }
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -487,6 +526,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.sum === null ? null : parseFloat(data.sum);
     }
+    /**
+     * Retrieves the sum of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().sumBy('name', 'score')
+     * // Map(2) { 'primary' => 10, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to sum within each group
+     * @returns A Map from each present group value to the sum of the aggregated column in that group
+     */
+    async sumBy(groupColumn, aggregatedColumn) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { sum } = this.dbFor('select').fn;
+        return this.groupedAggregate(groupColumn, sum(aggregatedColumn), rawSum => rawSum === null ? null : parseFloat(rawSum));
+    }
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -510,6 +567,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.avg;
     }
+    /**
+     * Retrieves the average of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().avgBy('name', 'score')
+     * // Map(2) { 'primary' => 5, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to average within each group
+     * @returns A Map from each present group value to the average of the aggregated column in that group
+     */
+    async avgBy(groupColumn, aggregatedColumn) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { avg } = this.dbFor('select').fn;
+        return this.groupedAggregate(groupColumn, avg(aggregatedColumn));
+    }
     /**
      * Retrieves the number of records in the database
      *
@@ -535,6 +610,59 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return parseInt(data.tablecount.toString());
     }
+    /**
+     * Retrieves the number of records in each group, keyed by the
+     * value of the provided group column.
+     *
+     * ```ts
+     * await User.query().countBy('name')
+     * // Map(2) { 'fred' => 2, 'zed' => 1 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @returns A Map from each present group value to the number of records in that group
+     */
+    async countBy(groupColumn) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { count } = this.dbFor('select').fn;
+        const primaryKeyRef = this.namespaceColumn(this.query.dreamInstance['_primaryKey']);
+        return this.groupedAggregate(groupColumn, count(primaryKeyRef), rawCount => parseInt(rawCount.toString()));
+    }
+    /**
+     * @internal
+     *
+     * Shared plumbing for grouped aggregates (`countBy` and the value-aggregate
+     * siblings `minBy` / `maxBy` / `sumBy` / `avgBy`). Selects the group column
+     * alongside a single aggregate expression, groups by the group column, executes,
+     * and folds the resulting rows into a Map keyed by the group value.
+     *
+     * The group column and the aggregate are selected under stable, underscore-free
+     * aliases so they can be read back off each row without being affected by
+     * Kysely's CamelCasePlugin (which would otherwise mangle a namespaced alias),
+     * mirroring the short-alias strategy used by `pluck`.
+     *
+     * @param groupColumn - the column to GROUP BY (base or joined-association-namespaced)
+     * @param aggregateExpression - the Kysely aggregate expression to select per group (e.g. `count(pk)`)
+     * @param coerceValue - maps each raw aggregate value to the value stored in the returned Map
+     * @returns A Map from each present group value to its coerced aggregate value
+     */
+    async groupedAggregate(groupColumn, aggregateExpression, coerceValue) {
+        const groupColumnRef = this.namespaceColumn(groupColumn);
+        let kyselyQuery = new this.constructor(this.query).buildSelect({
+            bypassSelectAll: true,
+            bypassOrder: true,
+        });
+        kyselyQuery = kyselyQuery
+            .select(`${groupColumnRef} as groupvalue`)
+            .select(aggregateExpression.as('aggregatevalue'))
+            .groupBy(groupColumnRef);
+        const rows = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const result = new Map();
+        for (const row of rows) {
+            result.set(row.groupvalue, coerceValue ? coerceValue(row.aggregatevalue) : row.aggregatevalue);
+        }
+        return result;
+    }
     /**
      * @internal
      *
@@ -606,6 +734,27 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * is provided as a second argument, it will use that transaction
      * to encapsulate the persisting of the dream, as well as any
      * subsequent model hooks that are fired.
+     *
+     * `RETURNING *` (rather than enumerating the compiled column list) keeps
+     * writes working under schema/image skew: during a rolling deploy, a
+     * container built before a drop-column migration would otherwise name the
+     * dropped column in `RETURNING` and fail with `42703 column does not
+     * exist` on every write, even writes that never touch that column. The
+     * `SET`/`VALUES` half still names only dirty attributes, so a write that
+     * actually sets a dropped column still fails loudly. The returned row is
+     * filtered to the compiled column list before hydration (see
+     * internal/saveDream.ts), so a column the image doesn't know about never
+     * reaches `setAttributes`.
+     *
+     * KNOWN CONSTRAINT: star-selects are only safe because nothing in this
+     * stack uses named prepared statements — node-postgres prepares a
+     * statement only when given an explicit `name`, and Kysely never names
+     * them, so every query is re-planned. With named prepared statements, a
+     * concurrent `ADD COLUMN` changes a cached plan's result shape and
+     * Postgres raises `cached plan must not change result type` (the reason
+     * Rails added `enumerate_columns_in_select_statements`). If a future
+     * driver or pooling layer enables named prepared statements, revisit
+     * every `RETURNING *` / `select *` in this driver.
      */
     static async saveDream(dream, txn = null) {
         const connectionName = dream.connectionName || 'default';
@@ -617,13 +766,13 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     .updateTable(dream.table)
                     .set(sqlifiedAttributes)
                     .where(namespaceColumn(dream['_primaryKey'], dream.table), '=', dream.primaryKeyValue());
-                return await executeDatabaseQuery(query.returning([...dream.columns()]), 'executeTakeFirstOrThrow');
+                return await executeDatabaseQuery(query.returningAll(), 'executeTakeFirstOrThrow');
             }
             else {
                 const query = db
                     .insertInto(dream.table)
                     .values(sqlifiedAttributes)
-                    .returning([...dream.columns()]);
+                    .returningAll();
                 return await executeDatabaseQuery(query, 'executeTakeFirstOrThrow');
             }
         }
@@ -999,6 +1148,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         }, {}), {
             negate,
             disallowSimilarityOperator,
+            expectedAlias: rootTableOrAssociationAlias,
         });
     }
     buildCommon(kyselyQuery) {
@@ -1041,20 +1191,25 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             kyselyQuery = kyselyQuery.where((eb) => eb.and([
                 ...this.aliasWhereStatements(query['whereStatements'], query['baseSqlAlias']).map(whereStatement => this.whereStatementToExpressionWrapper(this.dreamClass, eb, whereStatement, {
                     disallowSimilarityOperator: false,
+                    expectedAlias: query['baseSqlAlias'],
                 })),
                 ...this.aliasWhereStatements(query['whereNotStatements'], query['baseSqlAlias']).map(whereNotStatement => this.whereStatementToExpressionWrapper(this.dreamClass, eb, whereNotStatement, {
                     negate: true,
+                    expectedAlias: query['baseSqlAlias'],
                 })),
-                ...query['whereAnyStatements'].map(whereAnyStatements => eb.or(this.aliasWhereStatements(whereAnyStatements, query['baseSqlAlias']).map(whereAnyStatement => this.whereStatementToExpressionWrapper(this.dreamClass, eb, whereAnyStatement)))),
+                ...query['whereAnyStatements'].map(whereAnyStatements => eb.or(this.aliasWhereStatements(whereAnyStatements, query['baseSqlAlias']).map(whereAnyStatement => this.whereStatementToExpressionWrapper(this.dreamClass, eb, whereAnyStatement, {
+                    expectedAlias: query['baseSqlAlias'],
+                })))),
             ]));
         }
         return kyselyQuery;
     }
-    whereStatementToExpressionWrapper(dreamClass, eb, whereStatement, { negate = false, disallowSimilarityOperator = true, } = {}) {
+    whereStatementToExpressionWrapper(dreamClass, eb, whereStatement, { negate = false, disallowSimilarityOperator = true, expectedAlias, } = {}) {
         const clauses = compact(Object.keys(whereStatement)
             .filter(key => whereStatement[key] !== DreamConst.required)
             .map(attr => {
             const val = whereStatement[attr];
+            this.validateAssociationFilterAlias(attr, val, expectedAlias);
             if (val?.isOpsStatement &&
                 val.shouldBypassWhereStatement) {
                 if (disallowSimilarityOperator)
@@ -1063,6 +1218,10 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 // and should be ommited from the where clause directly
                 return;
             }
+            if (this.isAssociationInstanceArray(dreamClass, attr, val))
+                return this.associationInstanceArrayToExpressionWrapper(dreamClass, eb, attr, val, {
+                    negate,
+                });
             const { a, b, c, a2, b2, c2 } = this.dreamWhereStatementToExpressionBuilderParts(dreamClass, attr, val);
             // postgres is unable to handle WHERE IN statements with blank arrays, such as in
             // "WHERE id IN ()", meaning that:
@@ -1106,7 +1265,13 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 //
             }
             else if (b === '=' && negate) {
-                return eb.and([eb(a, '=', c), eb(a, 'is not', null)]);
+                const conditions = [eb(a, '=', c), eb(a, 'is not', null)];
+                // when a second condition is present (e.g. the type field of a polymorphic
+                // association), it must be included so that the caller negates the full
+                // conjunction rather than the first condition alone
+                if (b2)
+                    conditions.push(eb(a2, b2, c2), eb(a2, 'is not', null));
+                return eb.and(conditions);
                 //
             }
             else if (b === '!=' && c !== null) {
@@ -1147,6 +1312,95 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             return eb.and([eb(a, 'not in', compactedC), isNotNullStatement]);
         return isNotNullStatement;
     }
+    /**
+     * @internal
+     *
+     * A Dream instance (or array of Dream instances) as a where-clause value is
+     * resolved as an association of the dreamClass whose statement is being
+     * compiled, so a key namespaced to a different table (e.g.
+     * `where({ 'c.user': user })` after `innerJoin('composition as c')`) would
+     * silently resolve the association against the wrong class, emitting invalid
+     * SQL or SQL that filters the wrong table. Such keys are already rejected at
+     * the type level; this guard rejects them at runtime. Un-namespaced keys and
+     * keys namespaced to the alias the statement applies to are unaffected, as
+     * are callers that do not declare an expected alias.
+     */
+    validateAssociationFilterAlias(attr, val, expectedAlias) {
+        if (expectedAlias === undefined)
+            return;
+        const isolatedColumn = maybeNamespacedColumnNameToColumnName(attr);
+        if (isolatedColumn === attr)
+            return;
+        const namespace = attr.slice(0, attr.length - isolatedColumn.length - 1);
+        if (namespace === expectedAlias)
+            return;
+        if (val instanceof Dream ||
+            (Array.isArray(val) && val.length > 0 && val.every(element => element instanceof Dream)))
+            throw new CannotNamespaceAssociationFilterToAnotherTable(this.dreamClass, attr, expectedAlias);
+    }
+    /**
+     * @internal
+     *
+     * An array under an association name can only be an array of Dream instances
+     * (association names are not columns). The every-element check simply avoids
+     * changing the handling of invalid runtime input (e.g. an array of ids under
+     * an association name), which the type system already rejects.
+     */
+    isAssociationInstanceArray(dreamClass, attr, val) {
+        return (Array.isArray(val) &&
+            dreamClass.associationNames.includes(maybeNamespacedColumnNameToColumnName(attr)) &&
+            val.every(element => element instanceof Dream));
+    }
+    /**
+     * @internal
+     *
+     * Expands an array of Dream instances under a BelongsTo association name into
+     * foreign key filtering:
+     * - non-polymorphic: `foreignKey IN (...)`
+     * - polymorphic: instances are grouped by their reference type (STI children
+     *   collapse into their base class), each group becoming
+     *   `(foreignKey IN (...) AND foreignKeyTypeField = 'TheType')`, with multiple
+     *   groups ORed together
+     * - empty array: matches nothing (FALSE); when the caller negates, NOT(FALSE)
+     *   matches everything, mirroring empty `in`/`not in` array semantics
+     *
+     * When `negate` is set, IS NOT NULL conditions are included so that the
+     * caller's negation also matches records in which the foreign key (or type
+     * field) is null, consistent with negation of single Dream instances and of
+     * `in` arrays.
+     */
+    associationInstanceArrayToExpressionWrapper(dreamClass, eb, attr, instances, { negate }) {
+        if (instances.length === 0)
+            return sql `FALSE`;
+        const isolatedColumn = maybeNamespacedColumnNameToColumnName(attr);
+        // preserve any table alias prefix from the attribute (e.g. `posts.user` -> `posts.`)
+        // on the columns we compare against
+        const namespacePrefix = attr.slice(0, attr.length - isolatedColumn.length);
+        const association = dreamClass['associationMetadataMap']()[isolatedColumn];
+        const foreignKeyColumn = `${namespacePrefix}${association.foreignKey()}`;
+        const primaryKeyValuesFor = (instances) => instances.map(instance => {
+            const primaryKeyValue = association.primaryKeyValue(instance);
+            if (primaryKeyValue === undefined)
+                throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, foreignKeyColumn);
+            return primaryKeyValue;
+        });
+        if (!association.polymorphic) {
+            const inClause = eb(foreignKeyColumn, 'in', primaryKeyValuesFor(instances));
+            return negate ? eb.and([inClause, eb(foreignKeyColumn, 'is not', null)]) : inClause;
+        }
+        const typeColumn = `${namespacePrefix}${association.foreignKeyTypeField()}`;
+        const instancesByType = groupBy(instances, instance => instance.referenceTypeString);
+        const typeClauses = Object.keys(instancesByType).map(referenceTypeString => {
+            const conditions = [
+                eb(foreignKeyColumn, 'in', primaryKeyValuesFor(instancesByType[referenceTypeString])),
+                eb(typeColumn, '=', referenceTypeString),
+            ];
+            if (negate)
+                conditions.push(eb(foreignKeyColumn, 'is not', null), eb(typeColumn, 'is not', null));
+            return eb.and(conditions);
+        });
+        return eb.or(typeClauses);
+    }
     dreamWhereStatementToExpressionBuilderParts(dreamClass, attr, val) {
         let a;
         let b;
@@ -1260,7 +1514,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 explicitAlias: alias,
                 joinAndStatement,
                 joinType,
-                previousThroughAssociation: undefined,
+                previousThroughAssociations: [],
                 dreamClassThroughAssociationWantsToHydrate: undefined,
             });
             query = results.query;
@@ -1563,20 +1817,35 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      *   public b
      * ```
      *
+     * Options declared on a through association (`and`/`andAny`/`andNot`/`selfAnd`/
+     * `selfAndNot`/`order`/`distinct`) are applied at the join of the table where the
+     * through association's target model materializes. When a source is itself a
+     * through association, that join is only reached after bridging further through
+     * associations, so each through association is pushed onto the
+     * `previousThroughAssociations` stack (along with the alias `selfAnd`/`selfAndNot`
+     * clauses reference) before the terminal `applyOneJoin` call, and the stack is
+     * threaded through every recursion until `addAssociationJoinStatementToQuery`
+     * reaches a concrete (non-through) association, where every stacked entry is
+     * applied to that join.
+     *
      * Then `MyModel.leftJoinPreload('myB')` is processed as follows:
      * - `applyOneJoin` is called with the `myB` association
      *   - `joinsBridgeThroughAssociations` is called with the `myB` association
      *     - `joinsBridgeThroughAssociations` is called with the `myA` association
      *       - `addAssociationJoinStatementToQuery` is called with the `otherModel` association
-     *       - `applyOneJoin` is called with the `a` association from OtherModel
-     *         - `joinsBridgeThroughAssociations` is called with the `a` association from OtherModel
-     *           // throw ThroughAssociationConditionsIncompatibleWithThroughAssociationSource if
-     *           // myA in MyModel defines conditions, distinct, or order
+     *       - `applyOneJoin` is called with the `a` association from OtherModel, with `myA` pushed
+     *         onto the previousThroughAssociations stack
+     *         - `joinsBridgeThroughAssociations` is called with the `a` association from OtherModel,
+     *           inheriting the stack
      *           - `addAssociationJoinStatementToQuery` is called with the `aToOtherModelJoinModel` association
-     *           - `applyOneJoin` is called with the `a` association from AToOtherModelJoinModel with conditions (if present) on `a` defined on OtherModel
-     *             - `addAssociationJoinStatementToQuery` is called with the `myA` association
-     *     - `applyOneJoin` is called with the `b` association from A with conditions (if present) from `myB` defined on MyModel
-     *       - `addAssociationJoinStatementToQuery` is called with the `myB` association
+     *           - `applyOneJoin` is called with the `a` association from AToOtherModelJoinModel, with the
+     *             `a` association from OtherModel pushed onto the stack
+     *             - `addAssociationJoinStatementToQuery` is called with the `a` association from
+     *               AToOtherModelJoinModel, applying the options (if present) of every stacked through
+     *               association (`myA` defined on MyModel, `a` defined on OtherModel) to the `through_as` join
+     *     - `applyOneJoin` is called with the `b` association from A, with `myB` pushed onto the stack
+     *       - `addAssociationJoinStatementToQuery` is called with the `b` association from A, applying
+     *         the options (if present) of `myB` defined on MyModel to the `through_bs` join
      */
     joinsBridgeThroughAssociations({ query, dreamClassTheAssociationIsDefinedOn, throughAssociation, 
     /**
@@ -1598,7 +1867,13 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, joinAndStatement, joinType, }) {
+    previousTableAlias, joinAndStatement, 
+    /**
+     * Through associations from further out in the association chain whose
+     * options are waiting to be applied at the terminal concrete join of this
+     * chain (see the doc comment above this method).
+     */
+    previousThroughAssociations, joinType, }) {
         /**
          * `through` associations always point to other associations on the same model
          * they are defined on. So when we want to find an association referenced by a
@@ -1632,6 +1907,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 explicitAlias: undefined,
                 previousTableAlias,
                 joinAndStatement: {},
+                /**
+                 * The through associations pending in previousThroughAssociations are
+                 * applied at the terminal join of _this_ association's chain (their
+                 * target model is this through association's target model), not at the
+                 * terminal join of the nested through association being bridged here,
+                 * so the nested chain starts with an empty stack.
+                 */
+                previousThroughAssociations: [],
                 joinType,
             });
             //
@@ -1658,7 +1941,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                  * The joinAndStatement is reserved for the final association, not intermediary join tables
                  */
                 joinAndStatement: {},
-                previousThroughAssociation: undefined,
+                previousThroughAssociations: [],
                 joinType,
                 dreamClassThroughAssociationWantsToHydrate: undefined,
             });
@@ -1698,15 +1981,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             // recursively and therefore may have added other through associations and their sources prior to reaching this point)
             explicitAlias,
             previousTableAlias: recursiveResult.association.as,
-            selfTableAlias: (throughAssociation.selfAnd ?? throughAssociation.selfAndNot)
-                ? previousTableAlias
-                : recursiveResult.association.as,
+            selfTableAlias: recursiveResult.association.as,
             // since joinsBridgeThroughAssociations passes {} to joinAndStatement recursively, we know this is only set on the
             // first call to joinsBridgeThroughAssociations, which corresponds to the outermoset through association and therefore
             // the last source association to be added to the statement (because joinsBridgeThroughAssociations was called
             // recursively and therefore may have added other through associations and their sources prior to reaching this point)
             joinAndStatement,
-            previousThroughAssociation: throughAssociation,
+            previousThroughAssociations: [
+                ...previousThroughAssociations,
+                /**
+                 * This through association's options are applied at the terminal
+                 * concrete join of this chain. `selfAnd`/`selfAndNot` clauses on a
+                 * through association reference the model the association is defined
+                 * on, whose table is aliased with this method's previousTableAlias.
+                 */
+                { association: throughAssociation, selfTableAlias: previousTableAlias },
+            ],
             joinType,
             dreamClassThroughAssociationWantsToHydrate,
         });
@@ -1731,14 +2021,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociation, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
         if (association.type !== 'BelongsTo' && association.through) {
-            if (throughAssociationHasOptionsBesidesThroughAndSource(previousThroughAssociation)) {
-                throw new ThroughAssociationConditionsIncompatibleWithThroughAssociationSource({
-                    dreamClass,
-                    association,
-                });
-            }
             return this.joinsBridgeThroughAssociations({
                 query,
                 dreamClassTheAssociationIsDefinedOn: dreamClass,
@@ -1746,6 +2030,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 explicitAlias,
                 previousTableAlias,
                 joinAndStatement,
+                previousThroughAssociations,
                 joinType,
             });
         }
@@ -1757,7 +2042,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             previousTableAlias,
             selfTableAlias,
             joinAndStatement,
-            previousThroughAssociation,
+            previousThroughAssociations,
             joinType,
             dreamClassThroughAssociationWantsToHydrate,
         });
@@ -1782,24 +2067,32 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociation, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
         const currentTableAlias = explicitAlias ?? association.as;
         const _associatedDreamClass = association.modelCB();
         const associatedDreamClass = Array.isArray(_associatedDreamClass)
             ? _associatedDreamClass[0]
             : _associatedDreamClass;
-        if (previousThroughAssociation?.type === 'HasMany') {
-            if (query?.distinctOn && previousThroughAssociation.distinct) {
+        /**
+         * Stacked order/distinct clauses are applied in join order: the options of
+         * the through association whose bridging joins were added to the query
+         * first are applied first, and the terminal association's own
+         * order/distinct (applied after the join, below) come last.
+         */
+        for (const { association: throughAssociation } of previousThroughAssociations) {
+            if (throughAssociation.type !== 'HasMany')
+                continue;
+            if (query?.distinctOn && throughAssociation.distinct) {
                 query = query.distinctOn(this.distinctColumnNameForAssociation({
-                    association: previousThroughAssociation,
+                    association: throughAssociation,
                     tableNameOrAlias: currentTableAlias,
-                    foreignKey: previousThroughAssociation.primaryKey(),
+                    foreignKey: throughAssociation.primaryKey(),
                 }));
             }
-            if (previousThroughAssociation?.order) {
+            if (throughAssociation.order) {
                 query = this.applyOrderStatementForAssociation({
                     query,
-                    association: previousThroughAssociation,
+                    association: throughAssociation,
                     tableNameOrAlias: currentTableAlias,
                 });
             }
@@ -1818,21 +2111,18 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
                     associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
                 }), currentTableAlias));
-                if (previousThroughAssociation) {
-                    if (dreamClassThroughAssociationWantsToHydrate) {
-                        join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
-                            [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate.sanitizedName,
-                        }, previousThroughAssociation.through)));
-                    }
-                    join = this.applyAssociationAndStatementsToJoinStatement({
-                        dreamClass,
-                        join,
-                        association: previousThroughAssociation,
-                        currentTableAlias,
-                        selfTableAlias,
-                        joinAndStatement,
-                    });
+                if (dreamClassThroughAssociationWantsToHydrate) {
+                    join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
+                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate.sanitizedName,
+                    }, previousTableAlias)));
                 }
+                join = this.applyPreviousThroughAssociationAndStatementsToJoinStatement({
+                    dreamClass,
+                    join,
+                    previousThroughAssociations,
+                    currentTableAlias,
+                    joinAndStatement,
+                });
                 join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
                     dreamClass,
                     join,
@@ -1856,16 +2146,13 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                             : dreamClass.referenceTypeString,
                     }, currentTableAlias)));
                 }
-                if (previousThroughAssociation) {
-                    join = this.applyAssociationAndStatementsToJoinStatement({
-                        dreamClass,
-                        join,
-                        association: previousThroughAssociation,
-                        currentTableAlias,
-                        selfTableAlias,
-                        joinAndStatement,
-                    });
-                }
+                join = this.applyPreviousThroughAssociationAndStatementsToJoinStatement({
+                    dreamClass,
+                    join,
+                    previousThroughAssociations,
+                    currentTableAlias,
+                    joinAndStatement,
+                });
                 join = this.applyAssociationAndStatementsToJoinStatement({
                     dreamClass,
                     join,
@@ -1929,27 +2216,52 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             return this.namespaceColumn(foreignKey, tableNameOrAlias);
         return this.namespaceColumn(association.distinct, tableNameOrAlias);
     }
+    /**
+     * Applies the and-family clauses (`and`/`andAny`/`andNot`/`selfAnd`/`selfAndNot`)
+     * of every pending through association to the terminal concrete join of a
+     * through association chain.
+     *
+     * The first entry in the stack is the association the developer named in the
+     * join/preload/associationQuery statement, so it is the association the
+     * developer-supplied joinAndStatement corresponds to (used to satisfy
+     * `DreamConst.required` clauses); `DreamConst.required` on any other stacked
+     * through association cannot be satisfied and will throw
+     * `MissingRequiredAssociationAndClause`.
+     */
+    applyPreviousThroughAssociationAndStatementsToJoinStatement({ dreamClass, join, previousThroughAssociations, currentTableAlias, joinAndStatement, }) {
+        previousThroughAssociations.forEach(({ association, selfTableAlias }, index) => {
+            join = this.applyAssociationAndStatementsToJoinStatement({
+                dreamClass,
+                join,
+                association,
+                currentTableAlias,
+                selfTableAlias,
+                joinAndStatement: index === 0 ? joinAndStatement : {},
+            });
+        });
+        return join;
+    }
     applyAssociationAndStatementsToJoinStatement({ dreamClass, join, currentTableAlias, selfTableAlias, association, joinAndStatement, }) {
         if (association.and) {
             this.throwUnlessAllRequiredWhereClausesProvided(association, currentTableAlias, joinAndStatement);
-            join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(association.and, currentTableAlias), { disallowSimilarityOperator: false }));
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(association.and, currentTableAlias), { disallowSimilarityOperator: false, expectedAlias: currentTableAlias }));
         }
         if (association.andNot) {
-            join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(association.andNot, currentTableAlias), { negate: true }));
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(association.andNot, currentTableAlias), { negate: true, expectedAlias: currentTableAlias }));
         }
         if (association.andAny) {
-            join = join.on((eb) => eb.or(association.andAny.map(whereAnyStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereAnyStatement, currentTableAlias), { disallowSimilarityOperator: false }))));
+            join = join.on((eb) => eb.or(association.andAny.map(whereAnyStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereAnyStatement, currentTableAlias), { disallowSimilarityOperator: false, expectedAlias: currentTableAlias }))));
         }
         if (association.selfAnd) {
             join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.rawifiedSelfOnClause({
-                associationAlias: association.as,
+                associationAlias: currentTableAlias,
                 selfAlias: selfTableAlias,
                 selfAndClause: association.selfAnd,
             })));
         }
         if (association.selfAndNot) {
             join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.rawifiedSelfOnClause({
-                associationAlias: association.as,
+                associationAlias: currentTableAlias,
                 selfAlias: selfTableAlias,
                 selfAndClause: association.selfAndNot,
             }), { negate: true }));
@@ -1997,9 +2309,9 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             // branches below, such default scopes are silently dropped on association loads, leaking
             // rows the app intended to hide.
             join = join.on((eb) => eb.and([
-                ...scopesQuery['whereStatements'].map(whereStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereStatement, tableNameOrAlias), { disallowSimilarityOperator: false })),
-                ...scopesQuery['whereNotStatements'].map(whereNotStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereNotStatement, tableNameOrAlias), { negate: true })),
-                ...scopesQuery['whereAnyStatements'].map(whereAnyStatements => eb.or(whereAnyStatements.map(whereAnyStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereAnyStatement, tableNameOrAlias))))),
+                ...scopesQuery['whereStatements'].map(whereStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereStatement, tableNameOrAlias), { disallowSimilarityOperator: false, expectedAlias: tableNameOrAlias })),
+                ...scopesQuery['whereNotStatements'].map(whereNotStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereNotStatement, tableNameOrAlias), { negate: true, expectedAlias: tableNameOrAlias })),
+                ...scopesQuery['whereAnyStatements'].map(whereAnyStatements => eb.or(whereAnyStatements.map(whereAnyStatement => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement(whereAnyStatement, tableNameOrAlias), { expectedAlias: tableNameOrAlias })))),
             ]));
         }
         return join;
@@ -2110,15 +2422,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             const preloadedPolymorphicBelongsTos = await this.preloadPolymorphicBelongsTo(association, dreamClassToHydrate, dreams);
             return preloadedPolymorphicBelongsTos;
         }
-        const dreamClassToHydrateColumns = [...dreamClassToHydrate.columns()];
-        const columnsToPluck = dreamClassToHydrateColumns.map(column => this.namespaceColumn(column.toString(), alias));
-        columnsToPluck.push(this.namespaceColumn(dreamClass.primaryKey, dreamClass.table));
+        const dreamClassToHydrateColumns = dreamClassToHydrate.columns();
+        // The base-model primary key rides along under a short alias so each
+        // associated row can be matched back to the dream it belongs to. The
+        // alias is lowercase without underscores so Kysely's CamelCasePlugin
+        // passes it through untouched (the same strategy as `pluck0` /
+        // `groupvalue`), and is extended until it cannot collide with a real
+        // column of the associated table. That collision loop can only consult
+        // the compiled column set, so under add-column skew a live column
+        // literally named like the alias would produce two identically-named
+        // result fields. The aliased base PK is deliberately selected last,
+        // and node-postgres resolves duplicate field names last-wins, so the
+        // base PK still wins even in that pathological case — and the
+        // hydration filter strips the colliding key from the instance's
+        // attributes.
+        let basePrimaryKeyAlias = 'preloadbasepk';
+        while (dreamClassToHydrateColumns.has(basePrimaryKeyAlias))
+            basePrimaryKeyAlias += '0';
         const baseClass = dreamClass['stiBaseClassOrOwnClass']['getAssociationMetadata'](associationName)
             ? dreamClass['stiBaseClassOrOwnClass']
             : dreamClass;
         const associationDataScope = this.dreamClassQueryWithScopeBypasses(baseClass, {
             // In order to stay DRY, preloading leverages the association logic built into
-            // `joins` (by using `pluck`, which calls `joins`). However, baseClass may have
+            // `joins`. However, baseClass may have
             // default scopes that would preclude finding that instance. We remove all
             // default scopes on baseClass, but not subsequent associations, so that the
             // single query will be able to find each row corresponding to a Dream in `dreams`,
@@ -2127,16 +2453,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         }).where({
             [dreamClass.primaryKey]: dreams.map(obj => obj.primaryKeyValue()),
         });
-        const hydrationData = await associationDataScope['_connection'](this.connectionOverride)
-            .innerJoin(associationName, (onStatement || {}))
-            .pluck(...columnsToPluck);
-        const preloadedDreamsAndWhatTheyPointTo = hydrationData.map(pluckedData => {
-            const attributes = {};
-            dreamClassToHydrateColumns.forEach((columnName, index) => (attributes[protectAgainstPollutingAssignment(columnName)] = pluckedData[index]));
-            const hydratedDream = this.dbResultToDreamInstance(attributes, dreamClassToHydrate);
+        const joinedQuery = associationDataScope['_connection'](this.connectionOverride).innerJoin(associationName, (onStatement || {}));
+        // Select the association's row wholesale (`"alias".*`) rather than
+        // enumerating the compiled column list. Enumerating made every preload
+        // assert the compiled schema against the live database: under
+        // schema/image skew (rolling deploy or rollback around a drop-column
+        // migration), naming a dropped column fails the whole preload with
+        // `42703 column does not exist`. The raw row is passed straight to
+        // hydration, where sqlResultToDreamInstance — the single filtering
+        // point — intersects it with the compiled column list (also stripping
+        // the base-PK alias key), so a column the image doesn't know about
+        // (the add-column direction of skew) never reaches the instance. See
+        // the prepared-statements note on `saveDream` before changing this
+        // back to an enumerated select.
+        const kyselyQuery = new this.constructor(joinedQuery)
+            .buildSelect({ bypassSelectAll: true })
+            .selectAll(alias)
+            .select(`${this.namespaceColumn(dreamClass.primaryKey, dreamClass.table)} as ${basePrimaryKeyAlias}`);
+        const rows = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const preloadedDreamsAndWhatTheyPointTo = rows.map((row) => {
+            const hydratedDream = this.dbResultToDreamInstance(row, dreamClassToHydrate);
             return {
                 dream: hydratedDream,
-                pointsToPrimaryKey: pluckedData.at(-1),
+                pointsToPrimaryKey: row[basePrimaryKeyAlias],
             };
         });
         this.hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo);