turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/typed-sql.d.ts

@@ -19,7 +19,9 @@
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
- *     get a runtime value into the query is via `${...}`, which we bind.
+ *     get a runtime value into the query is via `${...}`, which we bind. A
+ *     plain array passed where the template belongs is refused at runtime
+ *     ({@link assertTemplateStrings}).
  *
  *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
  *     existing `client.raw()` behavior: a typed raw query is a literal escape
@@ -49,6 +51,7 @@
  */
 import type { PgCompatPool } from './client.js';
 import { type Dialect } from './dialect.js';
+import { type TurbineLogger } from './logger.js';
 import type { QueryEvent } from './query/deferred.js';
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
@@ -61,10 +64,37 @@ import type { QueryEvent } from './query/deferred.js';
  *
  * Exported for unit testing the parameterization invariant without a database.
  */
-export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[], dialect?: Pick<Dialect, 'paramPlaceholder'>): {
+export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[], dialect?: Pick<Dialect, 'paramPlaceholder'>, api?: string): {
     sql: string;
     params: unknown[];
 };
+/**
+ * Refuse a "template" that did not come from a tagged-template call.
+ *
+ * Only the static segments of a template reach the SQL text, and that is safe
+ * because the compiler wrote them. A plain array passed in their place (a
+ * JSON-parsed request field, a string split by hand) puts its text into the
+ * SQL with nothing escaped. A real `TemplateStringsArray` is frozen and carries
+ * a frozen `raw` array of the same length; `JSON.parse` and array literals
+ * produce neither.
+ *
+ * `unsafeApi` names the method that takes statement text instead, for the
+ * error message.
+ */
+export declare function assertTemplateStrings(strings: unknown, api: string, unsafeApi?: string): asserts strings is TemplateStringsArray;
+/**
+ * Raw-statement params with every `Date` (in arrays too) bound as UTC text,
+ * for a client reading zone-less temporal types as UTC (`utcTimestamps`).
+ *
+ * node-postgres renders a Date in the process's zone with its offset. A
+ * `timestamptz` keeps the instant either way, but a `timestamp` or `date`
+ * drops the offset and stores the local wall time, which then reads back
+ * shifted by the process offset. UTC text stores the instant's UTC fields,
+ * which is what a UTC read returns. Returns `params` itself when it holds no
+ * Date. An Invalid Date is refused (E003) instead of reaching the server as
+ * unparseable text.
+ */
+export declare function utcDateParams(params: unknown[], api: string): unknown[];
 /**
  * A pending typed raw SQL query. Implements the thenable contract, so it can be
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
@@ -100,6 +130,8 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * built outside a client, which then emits nothing, as before.
      */
     private readonly onQuery?;
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    private readonly logger;
     constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -120,7 +152,9 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
      * built outside a client, which then emits nothing, as before.
      */
-    onQuery?: ((event: QueryEvent) => void) | undefined);
+    onQuery?: ((event: QueryEvent) => void) | undefined, 
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    logger?: TurbineLogger);
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     private run;
     /**

package/dist/cjs/typed-sql.js

@@ -20,7 +20,9 @@
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
- *     get a runtime value into the query is via `${...}`, which we bind.
+ *     get a runtime value into the query is via `${...}`, which we bind. A
+ *     plain array passed where the template belongs is refused at runtime
+ *     ({@link assertTemplateStrings}).
  *
  *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
  *     existing `client.raw()` behavior: a typed raw query is a literal escape
@@ -51,8 +53,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypedSqlQuery = void 0;
 exports.buildTypedSql = buildTypedSql;
+exports.assertTemplateStrings = assertTemplateStrings;
+exports.utcDateParams = utcDateParams;
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
+const logger_js_1 = require("./logger.js");
 const query_events_js_1 = require("./query-events.js");
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
@@ -65,11 +70,10 @@ const query_events_js_1 = require("./query-events.js");
  *
  * Exported for unit testing the parameterization invariant without a database.
  */
-function buildTypedSql(strings, values, dialect = dialect_js_1.postgresDialect) {
-    // The tagged-template API guarantees `strings.length === values.length + 1`.
-    // Guard the directly-callable (exported) surface so a mismatched call can't
-    // silently desync placeholders from params (pg would reject it, but fail
-    // loudly here instead).
+function buildTypedSql(strings, values, dialect = dialect_js_1.postgresDialect, api = 'sql') {
+    assertTemplateStrings(strings, api);
+    // A tagged template always has `strings.length === values.length + 1`; a
+    // hand-built frozen one may not, and would desync placeholders from params.
     if (strings.length !== values.length + 1) {
         throw new errors_js_1.ValidationError(`sql template segment/value count mismatch: ${strings.length} segments, ${values.length} values.`);
     }
@@ -82,6 +86,92 @@ function buildTypedSql(strings, values, dialect = dialect_js_1.postgresDialect)
     }
     return { sql, params: values.slice() };
 }
+/**
+ * Refuse a "template" that did not come from a tagged-template call.
+ *
+ * Only the static segments of a template reach the SQL text, and that is safe
+ * because the compiler wrote them. A plain array passed in their place (a
+ * JSON-parsed request field, a string split by hand) puts its text into the
+ * SQL with nothing escaped. A real `TemplateStringsArray` is frozen and carries
+ * a frozen `raw` array of the same length; `JSON.parse` and array literals
+ * produce neither.
+ *
+ * `unsafeApi` names the method that takes statement text instead, for the
+ * error message.
+ */
+function assertTemplateStrings(strings, api, unsafeApi = 'rawUnsafe') {
+    if (Array.isArray(strings) && Object.isFrozen(strings)) {
+        const raw = strings.raw;
+        if (Array.isArray(raw) && Object.isFrozen(raw) && raw.length === strings.length) {
+            if (strings.every((s) => typeof s === 'string'))
+                return;
+            throw new errors_js_1.ValidationError(`${api}: a segment of the template contains an invalid escape sequence, so it has no text. ` +
+                'Fix the escape (write a literal backslash as `\\\\`).');
+        }
+    }
+    const received = Array.isArray(strings) ? 'a plain array' : strings === null ? 'null' : typeof strings;
+    throw new errors_js_1.ValidationError(`${api} must be called as a tagged template, for example ${api}\`SELECT * FROM users WHERE id = \${id}\`, ` +
+        `so that every interpolated value is sent as a bound parameter. It received ${received} instead, whose ` +
+        'text would reach the SQL unescaped. To run statement text built at runtime (DDL, a migration file), use ' +
+        `\`${unsafeApi}(text, ...values)\` and keep untrusted input out of the text.`);
+}
+/**
+ * A `Date` in the form node-postgres sends under `parseInputDatesAsUTC`:
+ * `YYYY-MM-DDTHH:MM:SS.mmm+00:00`, with ` BC` for years before 1.
+ */
+function utcDateText(date) {
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    let year = date.getUTCFullYear();
+    const bc = year < 1;
+    if (bc)
+        year = 1 - year;
+    return (`${pad(year, 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}` +
+        `T${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}` +
+        `.${pad(date.getUTCMilliseconds(), 3)}+00:00${bc ? ' BC' : ''}`);
+}
+function utcDateValue(value, api, position, nested) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new errors_js_1.ValidationError(`${api}: parameter $${position} ${nested ? 'contains' : 'is'} an Invalid Date, which has no SQL value. ` +
+                'Pass a valid Date, or null for SQL NULL.');
+        }
+        return utcDateText(value);
+    }
+    if (!Array.isArray(value))
+        return value;
+    let out;
+    for (let i = 0; i < value.length; i++) {
+        const converted = utcDateValue(value[i], api, position, true);
+        if (converted !== value[i]) {
+            out ??= value.slice();
+            out[i] = converted;
+        }
+    }
+    return out ?? value;
+}
+/**
+ * Raw-statement params with every `Date` (in arrays too) bound as UTC text,
+ * for a client reading zone-less temporal types as UTC (`utcTimestamps`).
+ *
+ * node-postgres renders a Date in the process's zone with its offset. A
+ * `timestamptz` keeps the instant either way, but a `timestamp` or `date`
+ * drops the offset and stores the local wall time, which then reads back
+ * shifted by the process offset. UTC text stores the instant's UTC fields,
+ * which is what a UTC read returns. Returns `params` itself when it holds no
+ * Date. An Invalid Date is refused (E003) instead of reaching the server as
+ * unparseable text.
+ */
+function utcDateParams(params, api) {
+    let out;
+    for (let i = 0; i < params.length; i++) {
+        const converted = utcDateValue(params[i], api, i + 1, false);
+        if (converted !== params[i]) {
+            out ??= params.slice();
+            out[i] = converted;
+        }
+    }
+    return out ?? params;
+}
 /**
  * A pending typed raw SQL query. Implements the thenable contract, so it can be
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
@@ -99,6 +189,7 @@ class TypedSqlQuery {
     logging;
     runScoped;
     onQuery;
+    logger;
     constructor(pool, sql, params, logging, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -119,19 +210,22 @@ class TypedSqlQuery {
      * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
      * built outside a client, which then emits nothing, as before.
      */
-    onQuery) {
+    onQuery, 
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    logger = logger_js_1.consoleLogger) {
         this.pool = pool;
         this.sql = sql;
         this.params = params;
         this.logging = logging;
         this.runScoped = runScoped;
         this.onQuery = onQuery;
+        this.logger = logger;
     }
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     run() {
         return this.runScoped(async () => {
             if (this.logging) {
-                console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
+                (0, logger_js_1.logTo)(this.logger, 'debug', `Typed SQL: ${this.sql.trim().substring(0, 120)}...`, { code: 'typed-sql' });
             }
             const result = await (0, query_events_js_1.runReportedStatement)(this.onQuery, (0, query_events_js_1.rawIdentity)('sql'), this.sql, this.params, () => this.pool.query(this.sql, this.params), errors_js_1.wrapPgError);
             return result.rows;

package/dist/cli/code-first-tags.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Code-first column tags for `turbine generate`.
+ *
+ * `pii`, `updatedAt`, `maxLength` and `tsType` exist only in the `defineSchema()`
+ * file: the database has no column for them, so a client generated from
+ * introspection alone returns PII by default, never stamps `updatedAt`, and
+ * types a `jsonb` column as `unknown`. `generate` reads the schema file and
+ * overlays its tags onto the introspected schema with the two functions here.
+ *
+ * Lives under `cli/` because only the CLI uses it. `schemaDefToMetadata` (the
+ * library path) shares the tag list through `declaredTagsOf`.
+ */
+import { type SchemaMetadata } from '../schema.js';
+import type { SchemaDef } from '../schema-builder.js';
+import { type CodeFirstColumnTags } from '../schema-metadata.js';
+/** Declared tags per table (database name), per column (database name). */
+export type CodeFirstTagMap = Map<string, Map<string, CodeFirstColumnTags>>;
+/**
+ * Collect the code-first-only tags a {@link SchemaDef} declares, keyed by the
+ * database table and column they land on (the same `camelToSnake(field)` rule
+ * {@link schemaDefToMetadata} uses). Tables and columns that declare no tag are
+ * absent from the result.
+ *
+ * Introspection can not see these flags, because the database has no column for
+ * them. `turbine generate` overlays them onto the introspected schema with
+ * {@link applyCodeFirstColumnTags}.
+ */
+export declare function extractCodeFirstColumnTags(def: SchemaDef): CodeFirstTagMap;
+/** What {@link applyCodeFirstColumnTags} changed. */
+export interface AppliedColumnTags {
+    /** Tables that received at least one tag. */
+    tables: number;
+    pii: number;
+    updatedAt: number;
+    maxLength: number;
+    /**
+     * Declared `tsType`s, as generator `columnTypes` entries
+     * (`'<table>.<column>'` by database name). Returned rather than written onto
+     * the schema so they go through the generator's own key and type-text
+     * validation, the same as a `columnTypes` entry in the config file.
+     */
+    columnTypes: Record<string, string>;
+}
+/**
+ * Overlay declared tags onto an introspected schema, in place, matching tables
+ * and columns by their database names.
+ *
+ * `pii` and `updatedAt` are set wherever declared. `maxLength` only fills a gap:
+ * the live column's own length wins when introspection read one.
+ *
+ * A `pii` or `updatedAt` tag that names a table or column the database does not
+ * have is an error, never a skip: a typo or an un-pushed schema would otherwise
+ * generate a client that silently returns the column it was tagged to hide.
+ * Every problem is reported at once. `maxLength` is also in the DDL, so a
+ * missing table or column only costs that fill-in. `inScope` lets the caller say
+ * that a missing table was deliberately left out of the client (an `exclude`
+ * filter), which is not an error either.
+ */
+export declare function applyCodeFirstColumnTags(schema: SchemaMetadata, tags: CodeFirstTagMap, options?: {
+    source?: string;
+    inScope?: (table: string) => boolean;
+}): AppliedColumnTags;

package/dist/cli/code-first-tags.js

@@ -0,0 +1,120 @@
+/**
+ * Code-first column tags for `turbine generate`.
+ *
+ * `pii`, `updatedAt`, `maxLength` and `tsType` exist only in the `defineSchema()`
+ * file: the database has no column for them, so a client generated from
+ * introspection alone returns PII by default, never stamps `updatedAt`, and
+ * types a `jsonb` column as `unknown`. `generate` reads the schema file and
+ * overlays its tags onto the introspected schema with the two functions here.
+ *
+ * Lives under `cli/` because only the CLI uses it. `schemaDefToMetadata` (the
+ * library path) shares the tag list through `declaredTagsOf`.
+ */
+import { ValidationError } from '../errors.js';
+import { printableCatalogName } from '../introspect.js';
+import { closestName } from '../query/utils.js';
+import { camelToSnake } from '../schema.js';
+import { declaredTagsOf } from '../schema-metadata.js';
+/**
+ * Collect the code-first-only tags a {@link SchemaDef} declares, keyed by the
+ * database table and column they land on (the same `camelToSnake(field)` rule
+ * {@link schemaDefToMetadata} uses). Tables and columns that declare no tag are
+ * absent from the result.
+ *
+ * Introspection can not see these flags, because the database has no column for
+ * them. `turbine generate` overlays them onto the introspected schema with
+ * {@link applyCodeFirstColumnTags}.
+ */
+export function extractCodeFirstColumnTags(def) {
+    const out = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            const tags = declaredTagsOf(config);
+            if (Object.keys(tags).length === 0)
+                continue;
+            let columns = out.get(tableDef.name);
+            if (!columns) {
+                columns = new Map();
+                out.set(tableDef.name, columns);
+            }
+            columns.set(camelToSnake(field), tags);
+        }
+    }
+    return out;
+}
+/** A tag the database has no column for, so only the schema file can supply it. */
+function isCodeFirstOnly(tags) {
+    return tags.pii === true || tags.updatedAt === true;
+}
+/**
+ * Overlay declared tags onto an introspected schema, in place, matching tables
+ * and columns by their database names.
+ *
+ * `pii` and `updatedAt` are set wherever declared. `maxLength` only fills a gap:
+ * the live column's own length wins when introspection read one.
+ *
+ * A `pii` or `updatedAt` tag that names a table or column the database does not
+ * have is an error, never a skip: a typo or an un-pushed schema would otherwise
+ * generate a client that silently returns the column it was tagged to hide.
+ * Every problem is reported at once. `maxLength` is also in the DDL, so a
+ * missing table or column only costs that fill-in. `inScope` lets the caller say
+ * that a missing table was deliberately left out of the client (an `exclude`
+ * filter), which is not an error either.
+ */
+export function applyCodeFirstColumnTags(schema, tags, options = {}) {
+    const applied = { tables: 0, pii: 0, updatedAt: 0, maxLength: 0, columnTypes: {} };
+    const problems = [];
+    for (const [tableName, columns] of tags) {
+        const shown = printableCatalogName(tableName);
+        if (!Object.hasOwn(schema.tables, tableName)) {
+            if (options.inScope && !options.inScope(tableName))
+                continue;
+            if (![...columns.values()].some(isCodeFirstOnly))
+                continue;
+            const near = closestName(tableName, Object.keys(schema.tables));
+            problems.push(`table "${shown}" is not in the database${near ? ` (did you mean "${printableCatalogName(near)}"?)` : ''}`);
+            continue;
+        }
+        const table = schema.tables[tableName];
+        let touched = false;
+        for (const [columnName, declared] of columns) {
+            const column = table.columns.find((c) => c.name === columnName);
+            if (!column) {
+                if (!isCodeFirstOnly(declared))
+                    continue;
+                const near = closestName(columnName, table.columns.map((c) => c.name));
+                problems.push(`column "${printableCatalogName(columnName)}" on table "${shown}" is not in the database` +
+                    `${near ? ` (did you mean "${printableCatalogName(near)}"?)` : ''}`);
+                continue;
+            }
+            if (declared.pii) {
+                column.pii = true;
+                applied.pii++;
+                touched = true;
+            }
+            if (declared.updatedAt) {
+                column.updatedAt = true;
+                applied.updatedAt++;
+                touched = true;
+            }
+            if (declared.maxLength !== undefined && column.maxLength === undefined) {
+                column.maxLength = declared.maxLength;
+                applied.maxLength++;
+                touched = true;
+            }
+            if (declared.tsType !== undefined) {
+                applied.columnTypes[`${tableName}.${columnName}`] = declared.tsType;
+                touched = true;
+            }
+        }
+        if (touched)
+            applied.tables++;
+    }
+    if (problems.length > 0) {
+        const from = options.source ? ` in ${options.source}` : '';
+        throw new ValidationError(`Cannot apply the column tags declared${from}: ${problems.join('; ')}. ` +
+            'Run `turbine push` so the database has them, or fix the name in the schema file. ' +
+            'Generating without the tags would return the columns they mark as PII.');
+    }
+    return applied;
+}

package/dist/cli/compile-query.js

@@ -101,6 +101,9 @@ export const COLUMN_NAMING_ARG_KEYS = [
     '_avg',
     '_min',
     '_max',
+    // Keys are column names and the result is a stored value (or one equal to it),
+    // the same reason `_min` / `_max` are listed.
+    '_percentile',
 ];
 /**
  * Does this args object carry a key that names a column, AT ANY DEPTH?
@@ -147,6 +150,12 @@ export function carriesColumnNamingArg(args, depth = 0) {
 // ---------------------------------------------------------------------------
 // Compile
 // ---------------------------------------------------------------------------
+/**
+ * Any non-array object, class instances included. Deliberately NOT the shared
+ * `isPlainRecord`: the builder walks a `with` (and a `where`) by its own keys
+ * whatever its prototype, so a report that skipped a class-instance `with`
+ * would list no relation while the SQL loads one.
+ */
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/cli/config.d.ts

@@ -24,12 +24,22 @@ export interface TurbineCliConfig {
      * to hand-edit every call site. A typo here is an error, not a silent no-op.
      */
     relationNames?: Record<string, Record<string, string>>;
+    /**
+     * TypeScript type overrides for generated row and input types, as
+     * `{ '<table>.<column>': '<type>' }` with database names. The main use is a
+     * `json` / `jsonb` column, which otherwise generates as `unknown`:
+     * `{ 'users.settings': '{ theme: string; beta?: boolean }' }`. The type text
+     * is emitted verbatim. A key naming no table or column is an error, not a
+     * silent no-op. A code-first column's `tsType` feeds the same map.
+     */
+    columnTypes?: Record<string, string>;
     /**
      * Extension for the generated `index.ts` sibling imports (F3):
-     * `'js'` (`./types.js`), `'none'` (`./types`), or `'auto'` (default:
-     * tsconfig-detected, falling back to `'js'`).
+     * `'js'` (`./types.js`), `'ts'` (`./types.ts`, for Node's native type
+     * stripping), `'none'` (`./types`), or `'auto'` (default: tsconfig-detected,
+     * falling back to `'js'`; never picks `'ts'`).
      */
-    importExtension?: 'js' | 'none' | 'auto';
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     /**
      * Keep raw database column names as generated field names (snake_case)
      * instead of camelCase (F4). Opt-in; default `false`.
@@ -54,7 +64,11 @@ export interface TurbineCliConfig {
      * are set.
      */
     seed?: string;
-    /** Schema builder file path (for push command) */
+    /**
+     * The `defineSchema()` file (default `./turbine/schema.ts`): what `push` applies,
+     * and where `generate` reads the `pii` / `updatedAt` / `maxLength` tags the
+     * database cannot store.
+     */
     schemaFile?: string;
     /**
      * Database adapter for PostgreSQL-compatible databases that need
@@ -159,14 +173,22 @@ export interface ResolvedConfig {
     migrationsDir: string;
     seedFile?: string;
     schemaFile: string;
+    /**
+     * True when `--schema-file` or the config `schemaFile` key named the file, as
+     * opposed to the `./turbine/schema.ts` default. A named file that is missing is
+     * an error; a missing default just means a database-first project.
+     */
+    schemaFileConfigured?: boolean;
     /** Resolved generator import-extension mode (F3). */
-    importExtension: 'js' | 'none' | 'auto';
+    importExtension: 'js' | 'ts' | 'none' | 'auto';
     /** Resolved keep-column-names generator flag (F4). */
     keepColumnNames: boolean;
     /** Resolved opt-out of the unique-FK → hasOne introspection flip (F2). */
     legacyToManyUniques: boolean;
     /** Resolved derived-relation rename map, or undefined when none is declared. */
     relationNames?: Record<string, Record<string, string>>;
+    /** Column type overrides for the generator, or undefined when none is declared. */
+    columnTypes?: Record<string, string>;
 }
 export interface CliOverrides {
     url?: string;
@@ -176,10 +198,17 @@ export interface CliOverrides {
     schemaFile?: string;
     include?: string[];
     exclude?: string[];
-    importExtension?: 'js' | 'none' | 'auto';
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     keepColumnNames?: boolean;
     legacyToManyUniques?: boolean;
 }
+/**
+ * The first candidate that is a non-blank string. An empty or whitespace-only
+ * value counts as unset, because an exported-but-empty variable (`DATABASE_URL=`
+ * in a shell profile or a `.env` template) is how "not configured" is usually
+ * spelled, and `??` would let it beat a real value further down the chain.
+ */
+export declare function firstNonEmpty(...candidates: Array<string | undefined>): string | undefined;
 /**
  * Merge config file values with CLI overrides and env vars.
  * Priority: CLI flags > env vars > config file > defaults.

package/dist/cli/config.js

@@ -149,23 +149,38 @@ export function findConfigFile(cwd) {
     }
     return null;
 }
+/**
+ * The first candidate that is a non-blank string. An empty or whitespace-only
+ * value counts as unset, because an exported-but-empty variable (`DATABASE_URL=`
+ * in a shell profile or a `.env` template) is how "not configured" is usually
+ * spelled, and `??` would let it beat a real value further down the chain.
+ */
+export function firstNonEmpty(...candidates) {
+    for (const value of candidates) {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return undefined;
+}
 /**
  * Merge config file values with CLI overrides and env vars.
  * Priority: CLI flags > env vars > config file > defaults.
  */
 export function resolveConfig(fileConfig, overrides) {
     return {
-        url: overrides.url ?? process.env.DATABASE_URL ?? fileConfig.url ?? '',
+        url: firstNonEmpty(overrides.url, process.env.DATABASE_URL, fileConfig.url) ?? '',
         out: overrides.out ?? fileConfig.out ?? './generated/turbine',
         schema: overrides.schema ?? fileConfig.schema ?? 'public',
         include: overrides.include ?? fileConfig.include ?? [],
         relationNames: fileConfig.relationNames,
+        columnTypes: fileConfig.columnTypes,
         exclude: overrides.exclude ?? fileConfig.exclude ?? [],
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
         // `seedFile` is canonical (what the docs and `turbine init` use); `seed` is a
         // back-compat alias kept working for configs scaffolded before 0.50.
         seedFile: fileConfig.seedFile ?? fileConfig.seed,
         schemaFile: overrides.schemaFile ?? fileConfig.schemaFile ?? './turbine/schema.ts',
+        schemaFileConfigured: (overrides.schemaFile ?? fileConfig.schemaFile) !== undefined,
         importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
         keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
         legacyToManyUniques: overrides.legacyToManyUniques ?? fileConfig.legacyToManyUniques ?? false,

package/dist/cli/destructive.d.ts

@@ -19,16 +19,19 @@
  * the optional-`COLUMN` shorthand (`ALTER TABLE t DROP email`), data-modifying
  * CTEs (`WITH d AS (DELETE ...) SELECT ...`), `MERGE ... THEN DELETE`, dynamic
  * SQL inside a `DO`/function body, an `UPDATE` whose only WHERE sits inside a
- * subquery (which restricts nothing), a `DROP ... CASCADE` of a non-table
- * object (which takes dependent COLUMNS with it), a detached partition, and an
- * `EXPLAIN ANALYZE` of any of the above (which really executes it).
+ * subquery (which restricts nothing) or is a constant-true predicate (`WHERE
+ * true`, `WHERE 1 = 1`), a `DROP ... CASCADE` of a non-table object (which takes
+ * dependent COLUMNS with it), a detached partition, an `ON CONFLICT DO UPDATE`
+ * with no `WHERE` (it rewrites every conflicting row), a `PREPARE`d destructive
+ * statement, `lo_unlink` (it deletes large objects), and an `EXPLAIN ANALYZE` of
+ * any of the above (which really executes it).
  *
  * The lexing, "where does a statement end" and "which characters are code",
  * is NOT done here: it lives in `sql-statements.ts` and is shared with the
  * migration runner. Two lexers is how this guard came to disagree with the
  * executor about what a file contained (see that module's header).
  */
-export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'drop-cascade' | 'detach-partition' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type' | 'merge-delete' | 'rename' | 'rewrite-rule' | 'dynamic-destructive' | 'dynamic-unclassified';
+export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'drop-cascade' | 'detach-partition' | 'truncate' | 'delete' | 'update-without-where' | 'overwrite-on-conflict' | 'large-object-unlink' | 'alter-column-type' | 'merge-delete' | 'rename' | 'rewrite-rule' | 'dynamic-destructive' | 'dynamic-unclassified';
 export interface DestructiveStatement {
     /** The offending SQL statement (trimmed, possibly long, display truncated) */
     statement: string;