@rvoh/dream 2.20.0 → 2.22.0

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithDistinct extends Error {
+    get message() {
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database
+        // ("FOR UPDATE is not allowed with DISTINCT clause"), so fail here, with a
+        // message that names the two incompatible parts, rather than surfacing a
+        // raw driver error from inside a per-batch transaction.
+        return `
+An exclusive row lock was requested on a query that also calls \`distinct\`.
+
+A locked read cannot be combined with DISTINCT. Drop the \`distinct\` call, or
+drop the lock.
+`;
+    }
+}

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithJoinLoad extends Error {
+    get message() {
+        // A join load builds its own select statement (one row per joined
+        // association row, later collapsed in memory), which cannot carry the
+        // Query's row lock. Rather than silently performing an unlocked read and
+        // dropping the compare-and-set guarantee the caller asked for, refuse.
+        return `
+An exclusive row lock was requested on a query that also uses leftJoinPreload.
+
+A join-loaded query cannot be locked. Use \`preload\` instead of
+\`leftJoinPreload\`, or drop the lock.
+`;
+    }
+}

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

@@ -0,0 +1,16 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration;
+    constructor(declaration) {
+        super();
+        this.declaration = declaration;
+    }
+    get message() {
+        return `
+could not determine a column type for the following migration column declaration:
+  ${this.declaration}
+
+Make sure the column includes a type, e.g.:
+  ${this.declaration.split(':')[0]}:string
+    `;
+    }
+}

package/dist/cjs/src/errors/ops/ArrayEqualityRequiresArrayColumn.js

@@ -0,0 +1,23 @@
+export default class ArrayEqualityRequiresArrayColumn extends Error {
+    dreamClass;
+    column;
+    operator;
+    constructor(dreamClass, column, operator) {
+        super();
+        this.dreamClass = dreamClass;
+        this.column = column;
+        this.operator = operator;
+    }
+    get message() {
+        return `
+Attempting to compare an array for equality against a column that is not an
+array in the database:
+
+  ${this.dreamClass.sanitizedName}#${this.column} (operator: ${this.operator})
+
+Whole-array equality (\`=\`, \`!=\`, \`<>\`) is only meaningful for array columns.
+If you meant "is this column one of these values", use \`ops.in([...])\`
+(or a bare array) instead.
+`;
+    }
+}

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -1,6 +1,6 @@
 import * as path from 'node:path';
 import pluralize from 'pluralize-esm';
-import generateMigrationContent from '../cli/generateMigrationContent.js';
+import generateMigrationContent, { MIGRATION_TABLE_NAME_PLACEHOLDER, } from '../cli/generateMigrationContent.js';
 import primaryKeyType from '../db/primaryKeyType.js';
 import hyphenize from '../hyphenize.js';
 import migrationVersion from '../migrationVersion.js';
@@ -9,6 +9,18 @@ import dreamPath from '../path/dreamPath.js';
 import snakeify from '../snakeify.js';
 import generateStiMigrationContent from './generateStiMigrationContent.js';
 import writeGeneratedFile from './writeGeneratedFile.js';
+/**
+ * Equivalent to `migrationName.match(new RegExp(`${marker}(.+)$`))?.[1]`, but
+ * without a regex: CodeQL flags `.+` anchored to `$` as a polynomial-ReDoS
+ * shape, and a plain `indexOf`/`slice` does the same leftmost-match-to-end
+ * job with no backtracking risk.
+ */
+function tableNameFromSuffix(migrationName, marker) {
+    const markerIndex = migrationName.indexOf(marker);
+    if (markerIndex === -1)
+        return undefined;
+    return migrationName.slice(markerIndex + marker.length) || undefined;
+}
 export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
@@ -33,12 +45,17 @@ export default async function generateMigration({ migrationName, columnsWithType
         });
     }
     else {
-        const tableName = migrationName.match(/-to-(.+)$/)?.[1];
+        const toTableName = tableNameFromSuffix(migrationName, '-to-');
+        const fromTableName = toTableName
+            ? undefined
+            : tableNameFromSuffix(migrationName, '-from-');
+        const tableName = toTableName || fromTableName;
         content = generateMigrationContent({
-            table: tableName ? pluralize(snakeify(tableName)) : '<table-name>',
+            table: tableName ? pluralize(snakeify(tableName)) : MIGRATION_TABLE_NAME_PLACEHOLDER,
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             createOrAlter: 'alter',
+            alterDirection: fromTableName ? 'remove' : 'add',
         });
     }
     await writeGeneratedFile({

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -2,11 +2,19 @@ import pluralize from 'pluralize-esm';
 import lookupModelByGlobalName from '../../dream-app/helpers/lookupModelByGlobalName.js';
 import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
+import NoColumnsToAlterMigration from '../../errors/NoColumnsToAlterMigration.js';
+import UnparseableMigrationColumn from '../../errors/UnparseableMigrationColumn.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
+// Sentinel table name used by generateMigration.ts when a standalone
+// migration name matches neither a `-to-<table>` nor `-from-<table>` suffix.
+// That path intentionally produces a stub the user is expected to hand-edit
+// (e.g. an index-only migration with no column operations at all), so it's
+// exempt from the "no valid columns" check below.
+export const MIGRATION_TABLE_NAME_PLACEHOLDER = '<table-name>';
 const STI_TYPE_COLUMN_NAME = 'type';
 // deleted_at is deliberately NOT in this list: the SoftDelete default scope's
 // `WHERE deleted_at IS NULL` is unselective on healthy tables, Dream internals
@@ -15,8 +23,9 @@ const STI_TYPE_COLUMN_NAME = 'type';
 // default. See spec/unit/cli/generateMigrationContent.spec.ts
 // ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
+export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', alterDirection = 'add', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
+    const removingInUp = altering && alterDirection === 'remove';
     let requireCitextExtension = false;
     const checkConstraints = [];
     // When creating a new table, we automatically emit `created_at`,
@@ -65,7 +74,17 @@ export default function generateMigrationContent({ connectionName = 'default', t
         // when creating a migration for an STI child, we don't want to include notNull;
         // instead, we'll add a check constraint that uses the STI child class name
         const sqlAttributeType = getAttributeType(attributeType, descriptors);
-        if (attributeType === undefined || ['hasone', 'hasmany'].includes(processedAttrType))
+        if (attributeType === undefined) {
+            // In alter mode (both `-to-`/add and `-from-`/remove), a column whose
+            // type can't be resolved (e.g. a mistyped declaration with no `:type`
+            // segment) must not silently vanish from the generated migration —
+            // that's especially dangerous for `-from-` migrations, whose whole
+            // premise is describing removed columns so `down` can restore them.
+            if (altering)
+                throw new UnparseableMigrationColumn(attributeDeclaration);
+            return acc;
+        }
+        if (['hasone', 'hasmany'].includes(processedAttrType))
             return acc;
         if (attributeType === 'citext')
             requireCitextExtension = true;
@@ -169,6 +188,25 @@ export async function down(db: Kysely<any>): Promise<void> {
 }\
 `;
     }
+    // An alter migration (either `-to-`/add or `-from-`/remove) with no valid
+    // columns to add/drop would otherwise emit a bare `.alterTable(...).execute()`
+    // with no column operation at all, which Postgres rejects at migration-run
+    // time rather than generation time. Fail loudly here instead.
+    //
+    // This guard is scoped to the standalone `g:migration` `-to-`/`-from-` flow
+    // only (`stiChildClassName` is unset there). `g:sti-child` legitimately
+    // calls this function in alter mode with zero `columnsWithTypes` — a
+    // zero-attribute STI child is a documented use case (see `g:sti-child`'s
+    // help example in src/cli/index.ts), and `generateStiMigrationContent`
+    // handles the type-column/check-constraint machinery separately from the
+    // `columnDefs` this check inspects, so an empty `columnDefs` there is
+    // expected, not a sign of a mistyped/unparseable column list.
+    if (altering &&
+        columnDefs.length === 0 &&
+        table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
+        !stiChildClassName) {
+        throw new NoColumnsToAlterMigration(table, alterDirection);
+    }
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`
         : '';
@@ -179,7 +217,22 @@ export async function down(db: Kysely<any>): Promise<void> {
     const newlineIndent = '\n  ';
     const newlineDoubleIndent = '\n    ';
     const doubleNewlineIndent = '\n\n  ';
-    const columnDefLines = columnDefs.length ? newlineDoubleIndent + columnDefs.join(newlineDoubleIndent) : '';
+    // For a `-from-` migration (`alterDirection: 'remove'`), `down` re-adds the
+    // column(s) that `up` removed. The generator has no way to know the
+    // column's original default, so a non-optional (`.notNull()`) column with
+    // no default emitted here will fail at migration-run time against a table
+    // that already has rows. We can't fix that without a lot more heavy
+    // lifting (and the risk that comes with it), so flag it with a comment
+    // instead of silently generating a `down` that's likely to break.
+    const NO_KNOWN_DEFAULT_COMMENT = "// NOTE: the generator doesn't know this column's original default; this addColumn will fail against a table with existing rows unless you add a default by hand.";
+    const finalColumnDefs = removingInUp
+        ? columnDefs.map(def => def.includes('.notNull()') && !def.includes('.defaultTo(')
+            ? `${NO_KNOWN_DEFAULT_COMMENT}\n    ${def}`
+            : def)
+        : columnDefs;
+    const columnDefLines = finalColumnDefs.length
+        ? newlineDoubleIndent + finalColumnDefs.join(newlineDoubleIndent)
+        : '';
     const columnDropLines = columnDrops.length
         ? newlineDoubleIndent + columnDrops.join(newlineDoubleIndent) + newlineDoubleIndent
         : '';
@@ -190,21 +243,33 @@ export async function down(db: Kysely<any>): Promise<void> {
             newlineDoubleIndent +
             ".addColumn('updated_at', 'timestamp', col => col.notNull())" +
             (emitDeletedAtColumn ? newlineDoubleIndent + ".addColumn('deleted_at', 'timestamp')" : '');
+    // For `alterDirection: 'remove'` (a `-from-` migration), the enum *type*
+    // itself must never be created or dropped here, even when the column
+    // declaration includes inline enum values — enums are frequently reused
+    // across columns/tables, so `up` must drop only the column (no `dropType`)
+    // and `down` must re-add only the column (no `createType`), identical to
+    // referencing an existing enum by name with no values.
+    const enumCreateStatements = removingInUp ? '' : generateEnumStatements(columnsWithTypes);
+    const enumDropStatements = removingInUp ? '' : generateEnumDropStatements(columnsWithTypes);
+    const addColumnsBody = `${citextExtension}${enumCreateStatements}  await db.schema
+    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
+    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}`;
+    const removeColumnsBody = `  ${altering
+        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
+        : `await db.schema.dropTable('${table}').execute()`}${enumDropStatements}`;
+    const upBody = removingInUp ? removeColumnsBody : addColumnsBody;
+    const downBody = removingInUp ? addColumnsBody : removeColumnsBody;
     return `\
 ${dreamDbImports.length ? `import { ${dreamDbImports.join(', ')} } from '@rvoh/dream/db'\n` : ''}import { ${kyselyImports.join(', ')} } from 'kysely'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function up(db: Kysely<any>): Promise<void> {
-${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
-    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
-    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}
+${upBody}
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function down(db: Kysely<any>): Promise<void> {
-  ${altering
-        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
-        : `await db.schema.dropTable('${table}').execute()`}${generateEnumDropStatements(columnsWithTypes)}
+${downBody}
 }\
 `;
 }

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

@@ -117,11 +117,27 @@ const ops = {
     /**
      * Creates an `OpsStatement` using the `=` operator for strict equality.
      *
+     * **Array columns:** passing an array means literal array equality — the
+     * whole array is bound as a single parameter, so the column must match
+     * element-for-element, in order. This is the opt-in counterpart to a bare
+     * array in a where clause (`Post.where({ tags: ['a', 'b'] })`), which means
+     * `IN`, and to `ops.any`, which tests for containment of a single element.
+     * Element types are constrained by the column, so an enum array column
+     * rejects a string that is not a member of its enum.
+     *
+     * Note that PostgreSQL defines no equality operator for `json` (as opposed
+     * to `jsonb`), so `ops.equal` against a `json[]` column raises at the
+     * database.
+     *
      * @param equal - The value the column must equal.
      * @returns An `OpsStatement` using the `=` operator.
      *
      * @example
      * User.where({ role: ops.equal('admin') })
+     *
+     * @example
+     * // matches only rows whose tags column is exactly ['a', 'b'], in that order
+     * Post.where({ tags: ops.equal(['a', 'b']) })
      */
     equal: (equal) => new OpsStatement('=', equal),
     /**
@@ -260,6 +276,9 @@ const ops = {
         /**
          * Creates an `OpsStatement` using the `!=` operator for inequality.
          *
+         * **Array columns:** as with `ops.equal`, passing an array compares against
+         * the whole array rather than against its elements.
+         *
          * @param equal - The value the column must not equal.
          * @returns An `OpsStatement` using the `!=` operator.
          *

package/dist/esm/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/esm/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/esm/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/esm/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