@rvoh/dream 2.40.2 → 2.42.0

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

@@ -18,14 +18,22 @@ import NoUpdateOnAssociationQuery from '../errors/NoUpdateOnAssociationQuery.js'
 import CannotPaginateWithLeftJoinPreload from '../errors/pagination/CannotPaginateWithLeftJoinPreload.js';
 import CannotPaginateWithLimit from '../errors/pagination/CannotPaginateWithLimit.js';
 import CannotPaginateWithOffset from '../errors/pagination/CannotPaginateWithOffset.js';
+import ColumnOverflow from '../errors/db/ColumnOverflow.js';
+import DataTypeColumnTypeMismatch from '../errors/db/DataTypeColumnTypeMismatch.js';
 import RecordNotFound from '../errors/RecordNotFound.js';
 import cloneDeepSafe from '../helpers/cloneDeepSafe.js';
+import cachedTypeForAttribute from '../helpers/db/cachedTypeForAttribute.js';
+import { isMismatchRaisedBeforeQuerying, normalizeDataForDb } from '../helpers/db/normalizeDataForDb.js';
 import isObject from '../helpers/isObject.js';
 import namespaceColumn from '../helpers/namespaceColumn.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { toSafeObject } from '../helpers/toSafeObject.js';
 import uniq from '../helpers/uniq.js';
 import ops from '../ops/index.js';
+import OpsStatement from '../ops/ops-statement.js';
+import BaseClockTime from '../utils/datetime/BaseClockTime.js';
+import CalendarDate from '../utils/datetime/CalendarDate.js';
+import { DateTime } from '../utils/datetime/DateTime.js';
 import assertRecognizedAssociationConditionKeys, { ASSOCIATION_CONDITION_KEYS, } from './internal/associations/assertRecognizedAssociationConditionKeys.js';
 import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
@@ -359,12 +367,25 @@ export default class Query {
     }
     /**
      * Finds a record matching the Query with the
-     * specified primary key. Returns null if not found.
+     * specified primary key. Returns null if not found,
+     * including when the primary key is a value its column
+     * cannot hold (for example, `'abc'` for an integer
+     * primary key).
+     *
+     * When the database rejects a value elsewhere in the Query (for
+     * example, in a `whereNot`, `whereAny` or `leftJoinPreload`
+     * clause), that rejection is raised as `DataTypeColumnTypeMismatch`
+     * or `ColumnOverflow`, since a record may still match. Inside a
+     * transaction, a primary key the database rejects is raised that
+     * way too, because the database has then aborted the transaction.
      *
      * ```ts
      * await User.query().find(123)
      * // User{id: 123}
      *
+     * await User.query().find('abc')
+     * // null
+     *
      * await User.query().find(null)
      * // null
      *
@@ -378,14 +399,22 @@ export default class Query {
     async find(primaryKey) {
         if (!primaryKey)
             return null;
-        return await this.where({
-            [this.dreamInstance['_primaryKey']]: primaryKey,
-        }).first();
+        const lookup = { [this.dreamInstance['_primaryKey']]: primaryKey };
+        return await this.where(lookup).firstForLookup(lookup);
     }
     /**
      * Finds a record matching the Query with the
-     * specified primary key. If not found, an exception
-     * is raised.
+     * specified primary key. If not found, `RecordNotFound`
+     * is raised, including when the primary key is a value
+     * its column cannot hold (for example, `'abc'` for an
+     * integer primary key).
+     *
+     * When the database rejects a value elsewhere in the Query (for
+     * example, in a `whereNot`, `whereAny` or `leftJoinPreload`
+     * clause), that rejection is raised as `DataTypeColumnTypeMismatch`
+     * or `ColumnOverflow`, since a record may still match. Inside a
+     * transaction, a primary key the database rejects is raised that
+     * way too, because the database has then aborted the transaction.
      *
      * ```ts
      * await User.query().findOrFail(123)
@@ -394,6 +423,7 @@ export default class Query {
      *
      * @param primaryKey - The primary key of the record to look up
      * @returns The found record
+     * @throws RecordNotFound if no record is found
      */
     async findOrFail(primaryKey) {
         const record = await this.find(primaryKey);
@@ -404,7 +434,22 @@ export default class Query {
     /**
      * Finds a record matching the Query and the
      * specified where statement. If not found, null
-     * is returned.
+     * is returned, including when a value the where
+     * statement compares for equality (a plain value or
+     * `ops.equal`) is one its column cannot hold: for example,
+     * `'abc'` for a uuid column, or a date string Dream cannot
+     * parse for a date column.
+     *
+     * A value the database rejects anywhere else (in a list of values,
+     * under another operator such as `ops.not.equal` or `ops.lessThan`,
+     * or elsewhere in the Query, such as a `whereNot` or `whereAny`
+     * clause) is raised as `DataTypeColumnTypeMismatch` or
+     * `ColumnOverflow`, since a record may still match; so is a date,
+     * datetime or time string there that Dream cannot parse. Inside a
+     * transaction, an equality value the database rejects is raised that
+     * way too, because the database has then aborted the transaction; a
+     * date, datetime or time string Dream cannot parse never reaches the
+     * database, so it is treated as not found there as well.
      *
      * ```ts
      * await User.query().findBy({ email: 'how@yadoin' })
@@ -415,12 +460,27 @@ export default class Query {
      * @returns Either the first record found matching the attributes, or else null
      */
     async findBy(whereStatement) {
-        return await this._where(whereStatement, 'where').first();
+        return await this._where(whereStatement, 'where').firstForLookup(whereStatement);
     }
     /**
      * Finds a record matching the Query and the
-     * specified where statement. If not found, an exception
-     * is raised.
+     * specified where statement. If not found, `RecordNotFound`
+     * is raised, including when a value the where
+     * statement compares for equality (a plain value or
+     * `ops.equal`) is one its column cannot hold: for example,
+     * `'abc'` for a uuid column, or a date string Dream cannot
+     * parse for a date column.
+     *
+     * A value the database rejects anywhere else (in a list of values,
+     * under another operator such as `ops.not.equal` or `ops.lessThan`,
+     * or elsewhere in the Query, such as a `whereNot` or `whereAny`
+     * clause) is raised as `DataTypeColumnTypeMismatch` or
+     * `ColumnOverflow`, since a record may still match; so is a date,
+     * datetime or time string there that Dream cannot parse. Inside a
+     * transaction, an equality value the database rejects is raised that
+     * way too, because the database has then aborted the transaction; a
+     * date, datetime or time string Dream cannot parse never reaches the
+     * database, so it is treated as not found there as well.
      *
      * ```ts
      * await User.query().findOrFailBy({ email: 'how@yadoin' })
@@ -429,6 +489,7 @@ export default class Query {
      *
      * @param whereStatement - The where statement used to locate the record
      * @returns The first record found matching the attributes
+     * @throws RecordNotFound if no record is found
      */
     async findOrFailBy(whereStatement) {
         const record = await this.findBy(whereStatement);
@@ -436,6 +497,98 @@ export default class Query {
             throw new RecordNotFound(this.dreamInstance['sanitizedConstructorName']);
         return record;
     }
+    /**
+     * @internal
+     *
+     * The first record of this Query, for `find` and `findBy`, whose `lookup`
+     * (the primary key or where statement they were given) is already applied.
+     * Returns null when the lookup's own values tell that no record can match
+     * (see `lookupValueCannotBeHeld`); every other error is raised. Preloads
+     * run after the lookup's statement, so a rejected value in a preload clause
+     * is raised.
+     */
+    async firstForLookup(lookup) {
+        const hasPreloads = Object.keys(this.preloadStatements).length > 0;
+        const lookupQuery = hasPreloads ? this.clone({ preloadStatements: {}, preloadOnStatements: {} }) : this;
+        let record;
+        try {
+            record = await lookupQuery.first();
+        }
+        catch (error) {
+            if (await this.lookupValueCannotBeHeld(error, lookup))
+                return null;
+            throw error;
+        }
+        if (record && hasPreloads)
+            await this.dbDriverInstance().hydratePreload(record);
+        return record;
+    }
+    /**
+     * @internal
+     *
+     * Whether `error`, raised by a `find` or `findBy` statement, is a value of
+     * the lookup's own equality comparisons (see `lookupEqualityValues`) that
+     * its column cannot hold. Every matching record must equal each of those
+     * values, so when one cannot be held, no record can match. A rejected value
+     * anywhere else (a negated or OR'd clause, a join's `and` clause, a list of
+     * values, a negated or ordering operator) does not tell that, so it is
+     * raised.
+     *
+     * When Dream itself could not convert a value (a date, datetime or time
+     * string it cannot parse), nothing reached the database, and Dream's
+     * conversion of the lookup's values alone tells whether one of them was
+     * the value. When the database rejected the statement, the driver is asked
+     * whether it rejects one of the lookup's values on its own; inside a
+     * transaction it cannot be asked, since the database has aborted the
+     * transaction, so the error is raised.
+     */
+    async lookupValueCannotBeHeld(error, lookup) {
+        if (!(error instanceof DataTypeColumnTypeMismatch || error instanceof ColumnOverflow))
+            return false;
+        const equalityValues = this.lookupEqualityValues(lookup);
+        const convertForDb = ({ column, value }) => normalizeDataForDb({ val: value, dreamClass: this.dreamClass, column });
+        if (isMismatchRaisedBeforeQuerying(error))
+            return equalityValues.some(equalityValue => {
+                try {
+                    convertForDb(equalityValue);
+                    return false;
+                }
+                catch (conversionError) {
+                    if (conversionError instanceof DataTypeColumnTypeMismatch)
+                        return true;
+                    throw conversionError;
+                }
+            });
+        if (this.dreamTransaction)
+            return false;
+        return await Query.dbDriverClass(this.connectionName).rejectsAnyValueForColumnType(this.connectionName, this.connectionOverride ?? 'primary', equalityValues.map(equalityValue => ({
+            value: convertForDb(equalityValue),
+            dbType: cachedTypeForAttribute(this.dreamClass, equalityValue.column),
+        })));
+    }
+    /**
+     * @internal
+     *
+     * The values a `find` or `findBy` lookup compares a column of this model
+     * with `=`, as a plain value or `ops.equal`: the primary key for `find`.
+     * Lists of values, other operators, ranges, associations, subqueries and
+     * nulls are left out, since a value there that its column cannot hold does
+     * not stop a record from matching the lookup.
+     */
+    lookupEqualityValues(lookup) {
+        return Object.entries(lookup).flatMap(([column, comparison]) => {
+            if (!cachedTypeForAttribute(this.dreamClass, column))
+                return [];
+            if (comparison instanceof OpsStatement) {
+                if (comparison.operator !== '=')
+                    return [];
+                const value = comparison.value;
+                // an array compared with `=` is a whole value of an array column
+                return Array.isArray(value) || isScalarWhereValue(value) ? [{ column, value }] : [];
+            }
+            return isScalarWhereValue(comparison) ? [{ column, value: comparison }] : [];
+        });
+    }
     /**
      * Finds all records matching the Query in batches,
      * and then calls the provided callback for each found record.
@@ -1970,10 +2123,7 @@ export default class Query {
      * @returns boolean - true if any records match the query, false otherwise
      */
     async exists() {
-        // Implementing via `limit(1).all()`, rather than the simpler `!!(await this.first())`
-        // because it avoids the step of finding the first. Just find any, and return
-        // that one.
-        return (await this.limit(1).all()).length > 0;
+        return await this.dbDriverInstance().exists();
     }
     /**
      * Returns the first record in the database
@@ -2749,3 +2899,17 @@ function isCursorPrimaryKey(value) {
 function isCursorRowKey(value) {
     return value === null || isCursorPrimaryKey(value);
 }
+/**
+ * Whether a where-clause value is compared with a column as one value: a
+ * string, number, bigint or boolean, or a date or time object, which Dream
+ * converts to a string before sending it.
+ */
+function isScalarWhereValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'bigint' ||
+        typeof value === 'boolean' ||
+        value instanceof DateTime ||
+        value instanceof CalendarDate ||
+        value instanceof BaseClockTime);
+}

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

@@ -226,6 +226,31 @@ export default class QueryDriverBase {
     static isUniqueConstraintViolation(error) {
         return false;
     }
+    /**
+     * @internal
+     *
+     * The columns of the unique index whose violation `error` reports, in index
+     * order, when that index is on `table` and is a plain one: every key is a
+     * column and it has no predicate. `createOrFindBy` and `createOrUpdateBy`
+     * ask this after a failed insert to tell which of their attributes
+     * conflicted. Returns null when the driver cannot tell, when the index is
+     * on another table, or when it is an expression or partial index; the
+     * default returns null.
+     *
+     * @param connectionName - the connection the insert ran on
+     * @param error - the error the insert raised
+     * @param table - the table the insert wrote to
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async violatedUniqueIndexColumns(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    connectionName, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    error, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    table) {
+        return null;
+    }
     /**
      * @internal
      *
@@ -238,6 +263,48 @@ export default class QueryDriverBase {
     static isDeadlock(error) {
         return false;
     }
+    /**
+     * @internal
+     *
+     * The Dream error to raise in place of `error` when `error` is the database
+     * rejecting a value for the column it is written to or compared with: a value
+     * the column's type cannot represent, a null in a NOT NULL column, or a CHECK
+     * constraint violation. Saves and reads (selects, aggregates, plucks and
+     * preloads) raise the returned error; bulk `Query#update` and `Query#delete`
+     * do not consult this. A driver that does not recognize the error returns
+     * null, and the original error propagates unchanged.
+     */
+    static dataIncompatibleWithDatabaseFieldError(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    error) {
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * Whether the database rejects any of `values` as input for its `dbType`
+     * (the column type in the model's schema), judged by the database's own
+     * input rules. `find` and `findBy` ask this, outside a transaction, after
+     * the database rejected their statement, passing the values their lookup
+     * compares for equality: when one of those is rejected, no record can match
+     * the lookup, which then returns null; otherwise the rejected value was
+     * elsewhere in the Query, and the statement's error is raised. A driver that
+     * cannot tell returns false; the default does.
+     *
+     * @param connectionName - the connection the lookup ran on
+     * @param dbConnectionType - the connection type to ask on
+     * @param values - each value as sent to the database, with its column's type
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async rejectsAnyValueForColumnType(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    connectionName, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    dbConnectionType, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    values) {
+        return false;
+    }
     /**
      * @internal
      *
@@ -517,6 +584,19 @@ export default class QueryDriverBase {
     async avgBy(groupColumn, aggregatedColumn) {
         throw new Error('implement avgBy in child class');
     }
+    /**
+     * Returns true if a record matches the Query, false otherwise
+     *
+     * ```ts
+     * await User.where({ email: 'how@yadoin' }).exists()
+     * ```
+     *
+     * @returns true if any records match the Query, false otherwise
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async exists() {
+        throw new Error('implement exists in child class');
+    }
     /**
      * Retrieves the number of records in the database
      *

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

@@ -11,7 +11,6 @@ import { NoResultError, PostgresDialect, sql, } from 'kysely';
 import pluralize from 'pluralize-esm';
 import { CliFileWriter } from '../../cli/CliFileWriter.js';
 import DreamCLI from '../../cli/index.js';
-import { CHECK_VIOLATION, COLUMN_OVERFLOW, INVALID_INPUT_SYNTAX, NOT_NULL_VIOLATION, pgErrorType, } from '../../db/errors.js';
 import { default as _db } from '../../db/index.js';
 import validateColumn from '../../db/validators/validateColumn.js';
 import associationToGetterSetterProp from '../../decorators/field/association/associationToGetterSetterProp.js';
@@ -33,10 +32,6 @@ import CannotSaveMissingDream from '../../errors/CannotSaveMissingDream.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';
-import NotNullViolation from '../../errors/db/NotNullViolation.js';
 import UnexpectedUndefined from '../../errors/UnexpectedUndefined.js';
 import generateMigration from '../../helpers/cli/generateMigration.js';
 import compact from '../../helpers/compact.js';
@@ -407,7 +402,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             return (await new driverClass(query)['executeJoinLoad']())[0] || null;
         }
         const kyselyQuery = new this.constructor(this.query.limit(1)).buildSelect();
-        const results = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirst');
+        const results = await this.executeReadQuery(kyselyQuery, 'executeTakeFirst');
         if (results) {
             const theFirst = this.dbResultToDreamInstance(results, this.dreamClass);
             if (theFirst)
@@ -449,7 +444,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         // 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 results = await this.executeReadQuery(kyselyQuery, 'execute');
         const theAll = results.map(r => this.dbResultToDreamInstance(r, this.dreamClass));
         await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], theAll);
         return theAll;
@@ -475,7 +470,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             bypassOrder: true,
         });
         kyselyQuery = kyselyQuery.select(max(this.namespaceColumn(columnName)));
-        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        const data = await this.executeReadQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.max;
     }
     /**
@@ -516,7 +511,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             bypassOrder: true,
         });
         kyselyQuery = kyselyQuery.select(min(this.namespaceColumn(columnName)));
-        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        const data = await this.executeReadQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.min;
     }
     /**
@@ -557,7 +552,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             bypassOrder: true,
         });
         kyselyQuery = kyselyQuery.select(sum(this.namespaceColumn(columnName)));
-        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        const data = await this.executeReadQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.sum === null ? null : parseFloat(data.sum);
     }
     /**
@@ -598,7 +593,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             bypassOrder: true,
         });
         kyselyQuery = kyselyQuery.select(avg(this.namespaceColumn(columnName)));
-        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        const data = await this.executeReadQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return data.avg;
     }
     /**
@@ -619,6 +614,12 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         const { avg } = this.dbFor('select').fn;
         return this.groupedAggregate(groupColumn, avg(this.namespaceColumn(aggregatedColumn)));
     }
+    async exists() {
+        const kyselyQuery = new this.constructor(this.query.limit(1))
+            .buildSelect({ bypassSelectAll: true, bypassOrder: true })
+            .select(sql `1`.as('present'));
+        return (await this.executeReadQuery(kyselyQuery, 'executeTakeFirst')) !== undefined;
+    }
     /**
      * Retrieves the number of records in the database
      *
@@ -641,7 +642,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             ? count(sql `DISTINCT ${sql.ref(distinctColumn)}`)
             : count(query['namespaceColumn'](query.dreamInstance['_primaryKey']));
         kyselyQuery = kyselyQuery.select(countClause.as('tablecount'));
-        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        const data = await this.executeReadQuery(kyselyQuery, 'executeTakeFirstOrThrow');
         return parseInt(data.tablecount.toString());
     }
     /**
@@ -690,7 +691,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             .select(`${groupColumnRef} as groupvalue`)
             .select(aggregateExpression.as('aggregatevalue'))
             .groupBy(groupColumnRef);
-        const rows = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const rows = await this.executeReadQuery(kyselyQuery, 'execute');
         const result = new Map();
         for (const row of rows) {
             result.set(row.groupvalue, coerceValue ? coerceValue(row.aggregatevalue) : row.aggregatevalue);
@@ -722,7 +723,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             // which the pg package then returns in an object with a single `id` key)
             kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(field)} as ${shortAlias}`);
         });
-        return (await executeDatabaseQuery(kyselyQuery, 'execute')).map(singleResult => shortAliases.map(alias => singleResult[alias]));
+        return (await this.executeReadQuery(kyselyQuery, 'execute')).map(singleResult => shortAliases.map(alias => singleResult[alias]));
     }
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used
@@ -815,17 +816,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         catch (error) {
             if (dream.isPersisted && error instanceof NoResultError)
                 throw new CannotSaveMissingDream(dream);
-            switch (pgErrorType(error)) {
-                case COLUMN_OVERFLOW:
-                    throw new ColumnOverflow(error instanceof Error ? error : new Error('database column overflow'));
-                case INVALID_INPUT_SYNTAX:
-                    throw new DataTypeColumnTypeMismatch(error instanceof Error ? error : new Error('database column type error'));
-                case NOT_NULL_VIOLATION:
-                    throw new NotNullViolation(error instanceof Error ? error : new Error('not null violation'));
-                case CHECK_VIOLATION:
-                    throw new CheckConstraintViolation(error instanceof Error ? error : new Error('check constraint violation'));
-            }
-            throw error;
+            throw this.dataIncompatibleWithDatabaseFieldError(error) ?? error;
+        }
+    }
+    /**
+     * @internal
+     *
+     * Runs a read statement (a select, aggregate, pluck or preload), raising the
+     * driver's Dream error for a value the database rejects in place of the
+     * database's own error (see `dataIncompatibleWithDatabaseFieldError`).
+     */
+    async executeReadQuery(kyselyQuery, command) {
+        try {
+            return await executeDatabaseQuery(kyselyQuery, command);
+        }
+        catch (error) {
+            throw (this.constructor.dataIncompatibleWithDatabaseFieldError(error) ?? error);
         }
     }
     dbConnectionType(sqlCommandType) {
@@ -1047,7 +1053,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         });
         if (this.query['limitStatement'])
             pageSelect = pageSelect.limit(this.query['limitStatement']);
-        return (await executeDatabaseQuery(pageSelect, 'execute')).map(row => pageColumns.map(({ alias }) => row[alias]));
+        return (await this.executeReadQuery(pageSelect, 'execute')).map(row => pageColumns.map(({ alias }) => row[alias]));
     }
     /**
      * @internal
@@ -1080,7 +1086,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         keyColumns.forEach(({ alias }) => {
             keySelect = keySelect.orderBy(`${baseSqlAlias}.${alias}`, this.orderByDirection('asc'));
         });
-        return (await executeDatabaseQuery(keySelect, 'execute')).map(row => keyColumns.map(({ alias }) => row[alias]));
+        return (await this.executeReadQuery(keySelect, 'execute')).map(row => keyColumns.map(({ alias }) => row[alias]));
     }
     orderByDirection(direction) {
         return orderByDirection(direction);
@@ -1225,7 +1231,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 columnAliasMap[column] = columnAlias;
             });
         });
-        const queryResults = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const queryResults = await this.executeReadQuery(kyselyQuery, 'execute');
         const aliasToDreamIdMap = queryResults.reduce((aliasToDreamIdMap, singleSqlResult) => {
             this.fleshOutJoinLoadExecutionResults({
                 currentAlias: this.query['baseSqlAlias'],
@@ -2728,7 +2734,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             .buildSelect({ bypassSelectAll: true })
             .selectAll(alias)
             .select(`${this.namespaceColumn(dreamClass.primaryKey, dreamClass.table)} as ${basePrimaryKeyAlias}`);
-        const rows = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const rows = await this.executeReadQuery(kyselyQuery, 'execute');
         const preloadedDreamsAndWhatTheyPointTo = rows.map((row) => {
             const hydratedDream = this.dbResultToDreamInstance(row, dreamClassToHydrate);
             return {

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

@@ -9,8 +9,12 @@
 import pg from 'pg';
 import { sql } from 'kysely';
 import DreamCLI from '../../cli/index.js';
-import { DEADLOCK_DETECTED, LOCK_NOT_AVAILABLE, pgErrorType, UNIQUE_VIOLATION } from '../../db/errors.js';
+import { CHECK_VIOLATION, COLUMN_OVERFLOW, DEADLOCK_DETECTED, INVALID_INPUT_SYNTAX, LOCK_NOT_AVAILABLE, NOT_NULL_VIOLATION, pgErrorType, UNIQUE_VIOLATION, } from '../../db/errors.js';
 import DreamApp from '../../dream-app/index.js';
+import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
+import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
+import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
+import NotNullViolation from '../../errors/db/NotNullViolation.js';
 import SortableScopeLockWaitTimedOut from '../../errors/SortableScopeLockWaitTimedOut.js';
 import { findCitextArrayOid, findCorrespondingArrayOid, findEnumArrayOids, parsePostgresBigint, parsePostgresDate, parsePostgresDatetime, parsePostgresDatetimeTz, parsePostgresDecimal, parsePostgresTime, parsePostgresTimeTz, } from '../../helpers/customPgParsers.js';
 import { testDatabasePoolSize } from '../../db/testDatabasePool.js';
@@ -281,9 +285,87 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
     static isUniqueConstraintViolation(error) {
         return pgErrorType(error) === UNIQUE_VIOLATION;
     }
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.violatedUniqueIndexColumns}.
+     * A unique violation names the index it hit in the error's `constraint`
+     * field (a unique constraint's index shares its name), and one catalog query
+     * reads that index's key columns. `INCLUDE` columns are not keys and are
+     * left out.
+     */
+    static async violatedUniqueIndexColumns(connectionName, error, table) {
+        if (!(error instanceof pg.DatabaseError) || pgErrorType(error) !== UNIQUE_VIOLATION)
+            return null;
+        if (!error.constraint || !error.schema || !error.table)
+            return null;
+        const tableParts = table.split('.');
+        const tableName = tableParts.at(-1);
+        const tableSchema = tableParts.length > 1 ? tableParts[0] : undefined;
+        if (error.table !== tableName || (tableSchema !== undefined && error.schema !== tableSchema))
+            return null;
+        // the returned columns are aliased to single words: result keys come back camelized
+        const result = await sql `
+      SELECT
+        (idx.indexprs IS NULL AND idx.indpred IS NULL) AS plain,
+        ARRAY(
+          SELECT att.attname::text
+          FROM unnest(idx.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+          JOIN pg_catalog.pg_attribute AS att ON att.attrelid = idx.indrelid AND att.attnum = k.attnum
+          WHERE k.ord <= idx.indnkeyatts
+          ORDER BY k.ord
+        ) AS columns
+      FROM pg_catalog.pg_index AS idx
+      JOIN pg_catalog.pg_class AS cls ON cls.oid = idx.indexrelid
+      JOIN pg_catalog.pg_namespace AS ns ON ns.oid = cls.relnamespace
+      WHERE ns.nspname = ${error.schema} AND cls.relname = ${error.constraint} AND idx.indisunique
+    `.execute(this.dbFor(connectionName, 'primary'));
+        const index = result.rows[0];
+        if (!index?.plain || !index.columns.length)
+            return null;
+        return index.columns;
+    }
     static isDeadlock(error) {
         return pgErrorType(error) === DEADLOCK_DETECTED;
     }
+    static dataIncompatibleWithDatabaseFieldError(error) {
+        // pgErrorType recognizes only a pg DatabaseError, which is an Error
+        const databaseError = error;
+        switch (pgErrorType(error)) {
+            case COLUMN_OVERFLOW:
+                return new ColumnOverflow(databaseError);
+            case INVALID_INPUT_SYNTAX:
+                return new DataTypeColumnTypeMismatch(databaseError);
+            case NOT_NULL_VIOLATION:
+                return new NotNullViolation(databaseError);
+            case CHECK_VIOLATION:
+                return new CheckConstraintViolation(databaseError);
+            default:
+                return null;
+        }
+    }
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.rejectsAnyValueForColumnType}.
+     * One statement casts every value to its type, so Postgres's own input
+     * function for each type is the judge: a cast it rejects raises `22P02` or
+     * `22003`. Callers never ask inside a transaction, which a rejected cast
+     * would abort.
+     */
+    static async rejectsAnyValueForColumnType(connectionName, dbConnectionType, values) {
+        if (!values.length)
+            return false;
+        const casts = values.map(({ value, dbType }) => sql `CAST(${value} AS ${sql.raw(dbType)})`);
+        try {
+            await sql `SELECT ${sql.join(casts)}`.execute(this.dbFor(connectionName, dbConnectionType));
+            return false;
+        }
+        catch (error) {
+            const errorType = pgErrorType(error);
+            return errorType === INVALID_INPUT_SYNTAX || errorType === COLUMN_OVERFLOW;
+        }
+    }
     /**
      * @internal
      *

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

@@ -1,7 +1,11 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 export default async function findOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
+    // where().first() rather than findBy: a value the database rejects is raised, never read as no match,
+    // so it cannot lead to creating a record that already exists
     const existingRecord = await dreamClass
         .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+        .where(findOrCreateLookupStatement(dreamClass, attributes))
+        .first();
     if (existingRecord)
         return existingRecord;
     const { createWith, skipHooks } = extraOpts;