@rvoh/dream 2.20.0 → 2.22.0

package/dist/cjs/src/Dream.js

@@ -1330,6 +1330,9 @@ export default class Dream {
      * // User{email: 'goodbye@world'}
      * ```
      *
+     * Records are always visited in ascending primary key order; any `order`
+     * applied to the query is discarded. See {@link Query.findEach} for why.
+     *
      * @param cb - The callback to call for each found record
      * @param opts - Optional parameters for batch processing
      * @param opts.batchSize - the batch size you wish to collect records in. If not provided, it will default to 1000

package/dist/cjs/src/cli/index.js

@@ -45,6 +45,8 @@ ${INDENT}    - timetz
 ${INDENT}    - timetz[]
 ${INDENT}    - integer
 ${INDENT}    - integer[]
+${INDENT}    - boolean
+${INDENT}    - boolean[]
 ${INDENT}
 ${INDENT}    - decimal:
 ${INDENT}    - decimal[]:
@@ -153,16 +155,17 @@ ${INDENT}  # Add columns to an existing table (suffix with -to-<table_name> for
 ${INDENT}  pnpm psy g:migration add-timezone-to-users timezone:string
 ${INDENT}  pnpm psy g:migration add-bio-to-users bio:text:optional avatar_url:string:optional
 ${INDENT}
-${INDENT}  # Remove columns (suffix with -from-<table_name>)
-${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts
+${INDENT}  # Remove columns (suffix with -from-<table_name>; columns are described with
+${INDENT}  # their types, same shorthand as -to-, so the rollback (down) can recreate them)
+${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts legacy_status:string
 ${INDENT}
 ${INDENT}  # General schema change (no table suffix — generates empty up/down methods)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
             .argument('<migrationName>', `Kebab-case name describing the change. End with -to-<table_name> or -from-<table_name> to auto-generate an alterTable scaffold for that table.
 ${INDENT}
 ${INDENT}Examples:
-${INDENT}  add-phone-to-users          # scaffolds alterTable('users', ...)
-${INDENT}  remove-status-from-posts    # scaffolds alterTable('posts', ...)
+${INDENT}  add-phone-to-users phone:encrypted           # scaffolds alterTable('users', ...)
+${INDENT}  remove-status-from-posts status:string      # scaffolds alterTable('posts', ...)
 ${INDENT}  create-join-table-host-places  # empty migration (no table suffix match)`)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
             .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForMigration)

package/dist/cjs/src/dream/DreamClassTransactionBuilder.js

@@ -421,6 +421,9 @@ export default class DreamClassTransactionBuilder {
      * // User{email: 'goodbye@world'}
      * ```
      *
+     * Records are always visited in ascending primary key order; any `order`
+     * applied to the query is discarded. See {@link Query.findEach} for why.
+     *
      * @param cb - The callback to call for each found record
      * @param options.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void

package/dist/cjs/src/dream/Query.js

@@ -3,7 +3,9 @@ import DreamApp from '../dream-app/index.js';
 import AssociationDeclaredWithoutAssociatedDreamClass from '../errors/associations/AssociationDeclaredWithoutAssociatedDreamClass.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from '../errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import CannotPassAdditionalFieldsToPluckEachAfterCallback from '../errors/CannotPassAdditionalFieldsToPluckEachAfterCallback.js';
+import InvalidBatchSize from '../errors/InvalidBatchSize.js';
 import LeftJoinPreloadIncompatibleWithFindEach from '../errors/LeftJoinPreloadIncompatibleWithFindEach.js';
+import RowLockIncompatibleWithDistinct from '../errors/RowLockIncompatibleWithDistinct.js';
 import MissingRequiredCallbackFunctionToPluckEach from '../errors/MissingRequiredCallbackFunctionToPluckEach.js';
 import NoUpdateAllOnJoins from '../errors/NoUpdateAllOnJoins.js';
 import NoUpdateOnAssociationQuery from '../errors/NoUpdateOnAssociationQuery.js';
@@ -31,6 +33,10 @@ export default class Query {
      */
     static BATCH_SIZES = {
         FIND_EACH: 1000,
+        // deliberately small: every record in a locked destroy batch stays
+        // row-locked for the whole batch, so an oversized batch blocks unrelated
+        // writers. See Query#destroy's `lock` option.
+        LOCKED_DESTROY: 10,
         PLUCK_EACH: 10000,
         PLUCK_EACH_THROUGH: 1000,
     };
@@ -398,13 +404,30 @@ export default class Query {
      * records matching the Query have been fetched.
      *
      * ```ts
-     * await User.order('id').findEach(user => {
+     * await User.where({ deletedAt: null }).findEach(user => {
      *   DreamApp.log(user)
      * })
      * // User{id: 1}
      * // User{id: 2}
      * ```
      *
+     * IMPORTANT: `findEach` always iterates in ascending primary key order.
+     * Any `order` applied to the Query is discarded; passing one has no effect
+     * on the order records are visited in.
+     *
+     * This is not a limitation that can be lifted. `findEach` guarantees that
+     * every matching record is visited exactly once, and it delivers that by
+     * paginating on a keyset: each batch selects the next `batchSize` records
+     * with a primary key greater than the last record of the previous batch.
+     * That guarantee only holds over a stable, unique key. Ordering by a
+     * mutable, non-unique column would mean a record whose sort value changed
+     * partway through the iteration could be skipped entirely or visited twice.
+     * ({@link Query.cursorPaginate} can honor an arbitrary order precisely
+     * because a paginated UI tolerates that anomaly; a full traversal cannot.)
+     *
+     * If you need records processed in a particular order, load them with a
+     * regular ordered query instead of `findEach`.
+     *
      * @param cb - The callback to call for each found record
      * @param __namedParameters - Options for batch processing
      * @param __namedParameters.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
@@ -1741,21 +1764,109 @@ export default class Query {
      * // 12
      * ```
      *
+     * ## Guarded (compare-and-set) destroy
+     *
+     * By default, `destroy` reads the matching records and then destroys each of
+     * them, so a concurrent writer can change a record in between — the record is
+     * destroyed even though it no longer matches the Query that selected it.
+     * Passing `lock: true` closes that window, making `destroy` a compare-and-set
+     * the way `update(..., { skipHooks: true })` already is:
+     *
+     * ```ts
+     * const destroyed = await Order.where({ status: 'pending' }).destroy({ lock: true })
+     * // 0 — someone else moved every one of them out of 'pending' first
+     * ```
+     *
+     * With `lock: true`, records are processed in batches, and each batch runs in
+     * its own transaction which first re-selects that batch's records with an
+     * exclusive row lock and then destroys them before committing. Because the
+     * database re-checks the Query's conditions after acquiring each row lock,
+     * a record a concurrent transaction has already moved out of the Query drops
+     * out of the locked read and is never destroyed. The returned count is the
+     * number of records actually claimed, so a caller can detect that it lost a
+     * race by comparing the count against what it expected.
+     *
+     * Things to know before relying on it:
+     *
+     * - **The guarantee is per batch, not set-wide.** A run spanning more than one
+     *   batch can win a race in batch 1 and lose one in batch 2; nothing holds the
+     *   whole matched set still for the duration of the run. Sharing one
+     *   transaction across every batch — by threading a transaction onto the Query
+     *   itself, `Order.query().txn(txn).where({ ... }).destroy({ lock: true })` —
+     *   buys two things: the destroys become all-or-nothing (a rollback undoes the
+     *   whole run), and the row locks taken by every batch are held until you
+     *   commit. It does **not** extend the compare-and-set to the part of the set
+     *   the run has not reached yet: under READ COMMITTED each statement takes a
+     *   fresh snapshot, so a record moved out of the Query between batch 1 and
+     *   batch 2 still drops out of batch 2's locked read. A genuinely set-wide
+     *   guarantee needs REPEATABLE READ / SERIALIZABLE, or a single locking
+     *   statement over the whole set.
+     * - **Only a transaction carried by the Query is shared.** Merely wrapping the
+     *   call in `Model.transaction(...)` does not thread that transaction onto the
+     *   Query — `Dream.transaction` establishes no ambient transaction, it only
+     *   hands a `txn` to your callback — so each batch would open its own
+     *   transaction on a different pooled connection. Worse, if the surrounding
+     *   transaction has already written to any of the matched rows, each batch's
+     *   locked read blocks on locks the surrounding transaction holds while that
+     *   transaction awaits the destroy: a cycle across two connections, which
+     *   Postgres's deadlock detector cannot see, so it hangs rather than aborting.
+     *   Always pass the transaction with `.txn(txn)`.
+     * - **Behavior above READ COMMITTED differs.** The drop-out-of-the-result
+     *   behavior described above is READ COMMITTED (Postgres's default). Under
+     *   REPEATABLE READ or SERIALIZABLE, the same race raises a serialization
+     *   failure instead of silently returning a lower count. Both are safe; only
+     *   one of them is quiet.
+     * - **`batchSize` defaults to 10 here**, not `findEach`'s 1000, and the
+     *   default is deliberately small. Every row in a batch stays locked for the
+     *   whole batch, including the time spent running each record's hooks and
+     *   `dependent: 'destroy'` cascade, so an oversized batch blocks unrelated
+     *   writers touching those rows and surfaces as timeouts somewhere else in the
+     *   application, which is very hard to trace back to this destroy. Too small a
+     *   batch, by contrast, only slows down this call, which you can see and fix.
+     *   Lower it further for models with deep `dependent: 'destroy'` cascades or
+     *   expensive destroy hooks.
+     * - **A batch waits, without bound, for whoever holds the row.** The locked
+     *   read is a plain `FOR UPDATE`: if another transaction already holds a lock
+     *   on one of the batch's rows, this call blocks until that transaction ends,
+     *   holding its own transaction and its pooled connection open the whole
+     *   time. Dream sets no `lock_timeout` or `statement_timeout`, so a
+     *   long-running writer on the other side stalls the run indefinitely and, at
+     *   scale, ties up connections. If that is a risk in your application, set a
+     *   `lock_timeout` on the connection so a stuck batch fails instead of
+     *   hanging.
+     * - **If you are destroying a large set and do not need compare-and-set, do
+     *   not pass `lock`.** Plain `destroy()` (hooks and cascade, no locking) or
+     *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
+     *   are the right tools for bulk removal.
+     *
      * @param __namedParameters - Options for destroying the instance
      * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
+     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
      * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
      * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    async destroy({ skipHooks, cascade, } = {}) {
+    async destroy({ skipHooks, cascade, lock, batchSize, } = {}) {
         let counter = 0;
+        // resolve the default before validating: `??` would let an explicit 0
+        // through, and `limit(0)` means "no limit", which would turn a batched
+        // destroy into a single unbounded pass (and, with `lock`, a lock over the
+        // entire matched set)
+        const resolvedBatchSize = batchSize ?? (lock ? Query.BATCH_SIZES.LOCKED_DESTROY : Query.BATCH_SIZES.FIND_EACH);
+        if (!Number.isInteger(resolvedBatchSize) || resolvedBatchSize < 1)
+            throw new InvalidBatchSize(batchSize);
         const options = {
             bypassAllDefaultScopes: this.bypassAllDefaultScopes,
             defaultScopesToBypass: this.defaultScopesToBypass,
             skipHooks,
             cascade,
         };
+        if (lock) {
+            return await this.lockedDestroy(options, resolvedBatchSize);
+        }
         await this.findEach(async (result) => {
             const subquery = this.dreamTransaction
                 ? result.txn(this.dreamTransaction)
@@ -1767,9 +1878,94 @@ export default class Query {
                 await subquery.destroy(options);
             }
             counter++;
+        }, {
+            batchSize: resolvedBatchSize,
         });
         return counter;
     }
+    /**
+     * @internal
+     *
+     * The compare-and-set implementation behind `destroy({ lock: true })`.
+     *
+     * Each batch is handled in two steps inside one transaction:
+     *
+     * 1. an unlocked pluck of the next `batchSize` primary keys, in ascending
+     *    primary key order, which establishes the batch's window (its keyset
+     *    cursor) and tells us how many records were *attempted*. Only the keys are
+     *    read: hydrating and preloading these records would duplicate the work
+     *    step 2 does over the same rows; then
+     * 2. a locked re-read restricted to exactly those primary keys, which
+     *    re-applies every condition on the Query while acquiring an exclusive row
+     *    lock on each row it returns. Records a concurrent transaction has moved
+     *    out of the Query since step 1 do not come back, and are the records this
+     *    run lost the race for.
+     *
+     * The count comes from step 2's result set, which is why it reports records
+     * actually claimed rather than records attempted. (One thing it does not
+     * account for, because it never has: a `beforeDestroy` hook that sets
+     * `_preventDeletion` leaves the record in place but still counts.)
+     *
+     * The two-step shape is what keeps iteration correct. If the locked read both
+     * claimed rows and advanced the cursor, a batch whose records all lost the
+     * race would come back empty and end the run early, silently skipping every
+     * record after it. Advancing the cursor from step 1 instead means losing a
+     * race skips only the records that were lost.
+     *
+     * When the Query already carries a transaction, that transaction is used for
+     * every batch rather than opening one per batch, so the caller's transaction
+     * boundary wins and the locks are held until the caller commits.
+     */
+    async lockedDestroy(options, batchSize) {
+        if (this.joinLoadActivated)
+            throw new LeftJoinPreloadIncompatibleWithFindEach();
+        // the driver seam refuses this combination too, but catching it here means
+        // failing before any transaction is opened or any row is touched
+        if (this.distinctColumn)
+            throw new RowLockIncompatibleWithDistinct();
+        const primaryKey = this.dreamInstance['_primaryKey'];
+        const orderedQuery = this.order(null)
+            .order(this.namespacedPrimaryKey)
+            .limit(batchSize);
+        let counter = 0;
+        // the cursor is compared against a sentinel rather than tested for
+        // truthiness, since a primary key of 0 is a legitimate cursor value that
+        // would otherwise reset the window to the start of the set
+        let lastId = undefined;
+        let attemptedCount = 0;
+        do {
+            const batchQuery = lastId === undefined
+                ? orderedQuery
+                : orderedQuery.where({ [primaryKey]: ops.greaterThan(lastId) });
+            const destroyBatch = async (txn) => {
+                const candidateIds = await batchQuery.txn(txn).pluck(this.namespacedPrimaryKey);
+                if (!candidateIds.length)
+                    return { attempted: 0, claimed: 0, lastId };
+                const claimed = await this.dbDriverInstance(batchQuery.txn(txn).where({ [primaryKey]: candidateIds })).takeAll({ lock: true });
+                for (const record of claimed) {
+                    const inTransaction = record.txn(txn);
+                    if (this.shouldReallyDestroy) {
+                        await inTransaction.reallyDestroy(options);
+                    }
+                    else {
+                        await inTransaction.destroy(options);
+                    }
+                }
+                return {
+                    attempted: candidateIds.length,
+                    claimed: claimed.length,
+                    lastId: candidateIds.at(-1),
+                };
+            };
+            const results = this.dreamTransaction
+                ? await destroyBatch(this.dreamTransaction)
+                : await this.dreamClass.transaction(async (txn) => await destroyBatch(txn));
+            counter += results.claimed;
+            attemptedCount = results.attempted;
+            lastId = results.lastId;
+        } while (attemptedCount > 0 && attemptedCount === batchSize);
+        return counter;
+    }
     /**
      * Destroys all records matching the Query,
      * ignoring the SoftDelete decorator and
@@ -1791,12 +1987,15 @@ export default class Query {
      * @param __namedParameters - Options for destroying the instance
      * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
+     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
      * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
      * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    async reallyDestroy({ skipHooks, cascade, } = {}) {
-        return await this.clone({ shouldReallyDestroy: true }).destroy({ skipHooks, cascade });
+    async reallyDestroy({ skipHooks, cascade, lock, batchSize, } = {}) {
+        return await this.clone({ shouldReallyDestroy: true }).destroy({ skipHooks, cascade, lock, batchSize });
     }
     /**
      * Undestroys a SoftDelete model, unsetting

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

@@ -256,6 +256,32 @@ export default class QueryDriverBase {
     options = {}) {
         throw new Error('implement takeAll in child class');
     }
+    /**
+     * @internal
+     *
+     * Adapter seam for exclusive row locking. Given the select statement about to
+     * be executed, return a statement that additionally acquires an exclusive
+     * lock on each row it returns, held until the enclosing transaction commits
+     * or rolls back (Postgres: `SELECT ... FOR UPDATE OF <table>`).
+     *
+     * This is only ever reached when a caller opts into a locked read (today,
+     * `Query#destroy({ lock: true })`), and only from inside a transaction. The
+     * base implementation throws so that an adapter which has not implemented row
+     * locking fails loud rather than silently performing an unlocked read and
+     * quietly dropping the compare-and-set guarantee the caller asked for.
+     *
+     * @param kyselyQuery - the select statement to lock
+     * @param tableAlias - the alias of the Query's base table; only rows of that
+     * table are locked, so a joined query does not lock unrelated rows and does
+     * not fail on the nullable side of an outer join
+     */
+    applyRowLock(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    kyselyQuery, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    tableAlias) {
+        throw new Error('implement applyRowLock in child class');
+    }
     /**
      * Retrieves the max value of the specified column
      * for this Query

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

@@ -29,6 +29,9 @@ import MissingThroughAssociationSource from '../../errors/associations/MissingTh
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
 import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import ArrayEqualityRequiresArrayColumn from '../../errors/ops/ArrayEqualityRequiresArrayColumn.js';
+import RowLockIncompatibleWithDistinct from '../../errors/RowLockIncompatibleWithDistinct.js';
+import RowLockIncompatibleWithJoinLoad from '../../errors/RowLockIncompatibleWithJoinLoad.js';
 import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
 import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
 import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
@@ -39,6 +42,7 @@ import ASTSchemaBuilder from '../../helpers/cli/ASTSchemaBuilder.js';
 import generateMigration from '../../helpers/cli/generateMigration.js';
 import compact from '../../helpers/compact.js';
 import { normalizeDataForDb } from '../../helpers/db/normalizeDataForDb.js';
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import groupBy from '../../helpers/groupBy.js';
 import isEmpty from '../../helpers/isEmpty.js';
@@ -412,9 +416,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * @returns an array of dreams
      */
     async takeAll(options = {}) {
-        if (this.query['joinLoadActivated'])
+        if (this.query['joinLoadActivated']) {
+            // executeJoinLoad builds its own select and has nowhere to put a row
+            // lock, so a locked read here has to fail rather than quietly return
+            // unlocked rows and drop the guarantee the caller asked for
+            if (options.lock)
+                throw new RowLockIncompatibleWithJoinLoad();
             return await this.executeJoinLoad(options);
-        const kyselyQuery = this.buildSelect(options);
+        }
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database, so
+        // fail loudly here instead of emitting SQL that cannot run
+        if (options.lock && this.query['distinctColumn'])
+            throw new RowLockIncompatibleWithDistinct();
+        let kyselyQuery = this.buildSelect(options);
+        // row locking is adapter-specific, so it goes through the query driver seam
+        if (options.lock)
+            kyselyQuery = this.applyRowLock(kyselyQuery, this.query['baseSqlAlias']);
         const results = await executeDatabaseQuery(kyselyQuery, 'execute');
         const theAll = results.map(r => this.dbResultToDreamInstance(r, this.dreamClass));
         await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], theAll);
@@ -1484,8 +1501,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             b = '=';
             c = val;
         }
-        c = this.normalizedWhereValue(dreamClass, attr, c);
-        c2 = this.normalizedWhereValue(dreamClass, attr, c2);
+        c = maybeBindArrayAsSingleValue(dreamClass, a, b, this.normalizedWhereValue(dreamClass, attr, c));
+        c2 = maybeBindArrayAsSingleValue(dreamClass, a2, b2, this.normalizedWhereValue(dreamClass, attr, c2));
         if (a && c === undefined)
             throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, a);
         if (a2 && c2 === undefined)
@@ -2525,6 +2542,31 @@ export function resolvePostgresSsl(connectionConf) {
         return { rejectUnauthorized: false };
     return false;
 }
+const EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE = ['=', '!=', '<>'];
+/**
+ * Kysely renders a raw Javascript array passed as the right-hand side of a
+ * comparison as a value list (`($1, $2)`), which is what `in` / `not in` need,
+ * but which Postgres rejects for `=` against an array column
+ * (`operator does not exist: text[] = record`). For the equality operators,
+ * bind the array as a single parameter so that `ops.equal([...])` against an
+ * array column means literal array equality (`"col" = $1`).
+ *
+ * The rewrite is gated on the column actually being a database array column.
+ * An array reaching an equality operator against a *scalar* column is a
+ * mistake, and binding it as a single value would turn that mistake into a
+ * clause that matches nothing (`"name" = '{}'`) instead of one that raises, so
+ * it throws instead.
+ */
+function maybeBindArrayAsSingleValue(dreamClass, column, operator, val) {
+    if (!Array.isArray(val))
+        return val;
+    if (!EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE.includes(operator))
+        return val;
+    const isolatedColumn = maybeNamespacedColumnNameToColumnName(column ?? '');
+    if (!isDatabaseArrayColumn(dreamClass, isolatedColumn))
+        throw new ArrayEqualityRequiresArrayColumn(dreamClass, isolatedColumn, operator);
+    return sql.val(val);
+}
 function shouldSoftDelete(dream, reallyDestroy) {
     const dreamClass = dream.constructor;
     return dreamClass['softDelete'] && !reallyDestroy;

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

@@ -198,6 +198,27 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
         await client.end();
         DreamCLI.logger.logEndProgress();
     }
+    /**
+     * @internal
+     *
+     * Postgres implementation of the row-locking seam: appends
+     * `FOR UPDATE OF "<tableAlias>"` to the select, so every row the statement
+     * returns is exclusively locked until the enclosing transaction ends.
+     *
+     * Scoping the lock to the Query's own base table (rather than a bare
+     * `FOR UPDATE`) means a query that joins other tables neither locks rows the
+     * caller never asked about nor raises Postgres's "FOR UPDATE cannot be
+     * applied to the nullable side of an outer join".
+     *
+     * This is a waiting lock: neither `NOWAIT` nor `SKIP LOCKED` is applied, so a
+     * statement that collides with another transaction's lock blocks until that
+     * transaction ends. Callers that cannot afford an unbounded wait should set a
+     * `lock_timeout` on the connection; see the guarded-destroy notes on
+     * `Query#destroy`.
+     */
+    applyRowLock(kyselyQuery, tableAlias) {
+        return kyselyQuery.forUpdate(tableAlias);
+    }
     static supportsParallelTestDatabases = true;
     /**
      * @internal

package/dist/cjs/src/dream/internal/destroyAssociatedRecords.js

@@ -1,20 +1,69 @@
+import loadDependentDestroyTree from './loadDependentDestroyTree.js';
+/**
+ * @internal
+ *
+ * Marks a Dream instance as one whose `dependent: 'destroy'` associations were
+ * hydrated by this cascade's own call to `loadDependentDestroyTree`, using the
+ * same destroy options the cascade is running under.
+ *
+ * Associations a caller happened to preload themselves (e.g.
+ * `Post.preload('comments')`) are deliberately NOT trusted: they may have been
+ * loaded under different default scopes than the destroy requires — most
+ * importantly, `reallyDestroy` strips the soft-delete scope, so a
+ * caller-preloaded association could be missing soft-deleted records that the
+ * cascade must destroy.
+ */
+const CASCADE_LOADED = Symbol.for('dream:dependentDestroyTreeLoaded');
 /**
  * @internal
  *
  * Destroys all HasOne/HasMany associations on this
  * dream that are marked as `dependent: 'destroy'`.
  *
- * Expects associations to be preloaded onto the dream instance
- * via `loadDependentDestroyTree`. Iterates loaded associations
- * directly instead of querying the database.
+ * The whole dependent-destroy tree is loaded ONCE, at the root of the destroy
+ * operation, by `loadDependentDestroyTree`. Descendants reached by recursing
+ * through this function consume those already-hydrated associations rather
+ * than re-querying their own subtrees.
+ *
+ * A load still happens here when an association is not hydrated. That covers
+ * two cases:
+ *
+ * 1. the root of the operation, whose associations have not been loaded yet
+ * 2. a node past `RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS` levels of
+ *    self-reference, which the root's preload could not reach
+ *
+ * The second case is why the check is per-association-hydration rather than a
+ * "descendants are already loaded" flag: such a flag would truncate cascades
+ * deeper than the preload horizon.
+ *
+ * NOTE: reusing a hydrated subtree is only sound because the same `options`
+ * are forwarded unchanged all the way down the cascade (see the recursive
+ * `destroy`/`reallyDestroy` calls below), so every node's associations were
+ * loaded under the scopes this node would have used. Nothing in the types
+ * enforces that; if `options` ever start varying by depth, this reuse has to
+ * be revisited.
  */
 export default async function destroyAssociatedRecords(dream, txn, options) {
     const dreamClass = dream.constructor;
     const { reallyDestroy } = options;
+    // `loadDependentDestroyTree` hydrates and returns a CLONE rather than
+    // mutating the receiver, so the result must be assigned back — otherwise
+    // each association in the loop below would trigger its own reload.
+    let dreamWithAssociations = dream;
+    let alreadyLoadedTree = false;
     for (const associationName of dreamClass['dependentDestroyAssociationNames']()) {
-        const loaded = dream[associationName];
+        if (!alreadyLoadedTree && !cascadeLoaded(dreamWithAssociations, associationName)) {
+            dreamWithAssociations = await loadDependentDestroyTree(dreamWithAssociations, txn, {
+                reallyDestroy,
+                bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
+                defaultScopesToBypass: options.defaultScopesToBypass ?? [],
+            });
+            alreadyLoadedTree = true;
+        }
+        const loaded = dreamWithAssociations[associationName];
         const records = Array.isArray(loaded) ? loaded : loaded ? [loaded] : [];
         for (const record of records) {
+            markCascadeLoaded(record);
             if (reallyDestroy) {
                 await record.txn(txn).reallyDestroy(options);
             }
@@ -24,3 +73,26 @@ export default async function destroyAssociatedRecords(dream, txn, options) {
         }
     }
 }
+/**
+ * @internal
+ *
+ * True when this dream was hydrated by this cascade's own preload AND the
+ * given association is hydrated on it.
+ */
+function cascadeLoaded(dream, associationName) {
+    if (!dream[CASCADE_LOADED])
+        return false;
+    return dream.loaded(associationName);
+}
+/**
+ * @internal
+ *
+ * A plain assignment rather than `Object.defineProperty`: the key is a symbol,
+ * so it is already excluded from `Object.keys`, `for...in` and
+ * `JSON.stringify` without an explicit descriptor, and this runs once per node
+ * of a potentially wide cascade tree.
+ */
+function markCascadeLoaded(dream) {
+    ;
+    dream[CASCADE_LOADED] = true;
+}

package/dist/cjs/src/dream/internal/destroyDream.js

@@ -1,6 +1,5 @@
 import DreamApp from '../../dream-app/index.js';
 import destroyAssociatedRecords from './destroyAssociatedRecords.js';
-import loadDependentDestroyTree from './loadDependentDestroyTree.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -31,12 +30,12 @@ export default async function destroyDream(dream, txn = null, options) {
 async function destroyDreamWithTransaction(dream, txn, options) {
     const { cascade, reallyDestroy, skipHooks } = options;
     if (cascade) {
-        const dreamWithAssociations = await loadDependentDestroyTree(dream, txn, {
-            reallyDestroy,
-            bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
-            defaultScopesToBypass: options.defaultScopesToBypass ?? [],
-        });
-        await destroyAssociatedRecords(dreamWithAssociations, txn, options);
+        // NOTE: the dependent-destroy tree is loaded lazily, inside
+        // destroyAssociatedRecords, so that a cascaded descendant whose
+        // associations the root already preloaded does not re-query its own
+        // subtree. `dream` itself is intentionally never replaced by the loaded
+        // clone: the hooks and the delete below operate on the original.
+        await destroyAssociatedRecords(dream, txn, options);
     }
     if (!skipHooks) {
         await runHooksFor('beforeDestroy', dream, true, null, txn);

package/dist/cjs/src/errors/InvalidBatchSize.js

@@ -0,0 +1,19 @@
+export default class InvalidBatchSize extends Error {
+    batchSize;
+    constructor(batchSize) {
+        super();
+        this.batchSize = batchSize;
+    }
+    get message() {
+        return `
+Invalid batchSize provided.
+
+batchSize given:
+  ${String(this.batchSize)}
+
+batchSize must be a positive integer. A batchSize of 0 is especially dangerous,
+since a limit of 0 is treated as "no limit", which would collapse a batched
+operation into a single unbounded pass over the entire matched set.
+`;
+    }
+}

package/dist/cjs/src/errors/NoColumnsToAlterMigration.js

@@ -0,0 +1,17 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table;
+    alterDirection;
+    constructor(table, alterDirection) {
+        super();
+        this.table = table;
+        this.alterDirection = alterDirection;
+    }
+    get message() {
+        return `
+no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+
+Pass at least one column declaration with a resolvable type, e.g.:
+  name:string
+    `;
+    }
+}