turbine-orm 0.32.0 → 0.32.1

package/dist/cli/index.d.ts

@@ -53,6 +53,74 @@ export interface CliArgs {
     allowRemote?: boolean;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
+/** Where a resolved `DATABASE_URL` came from, after the `.env` load. */
+export type DotEnvProvenance = 'shell' | 'dotenv' | 'none';
+/** Structured outcome of {@link loadDotEnvForCli}. */
+export interface DotEnvLoadResult {
+    /** A `.env` file was present in the working directory. */
+    fileExists: boolean;
+    /** The `.env` was actually read into the environment. */
+    loaded: boolean;
+    /** A `.env` exists but this runtime cannot auto-load it (Node < 20.12). */
+    unsupported: boolean;
+    /** Where `DATABASE_URL` ended up coming from once the load settled. */
+    databaseUrlProvenance: DotEnvProvenance;
+    /** Set when the loader threw (e.g. EACCES / a directory named `.env`). */
+    loadError?: string;
+}
+/**
+ * Load a local `.env` into `process.env` for the CLI, mirroring what
+ * `node --env-file=.env` does. Loaded UNCONDITIONALLY when a `.env` is present,
+ * so every variable it defines (not just `DATABASE_URL`) reaches the config
+ * file and user scripts.
+ *
+ * A pre-existing variable ALWAYS wins: `process.loadEnvFile()` never overrides
+ * an already-set variable, so a real shell/CI `DATABASE_URL` beats the file.
+ * Provenance is tracked so callers can warn when an `.env`-sourced
+ * `DATABASE_URL` silently overrides a differing `url` in `turbine.config.ts`:
+ * `DATABASE_URL` is `'dotenv'`-sourced only when it was absent before the load
+ * and present after.
+ *
+ * `process.loadEnvFile` is Node 20.12+. Turbine's engines allow `>=20.0.0`, so
+ * on older runtimes this no-ops with `unsupported: true` (never throws). A
+ * loader that throws (unreadable file, a directory named `.env`) is caught and
+ * surfaced as `loadError`, never a raw unhandled rejection. Deliberately
+ * CLI-only: the library must never read files.
+ *
+ * Dependencies are injectable purely so this is unit-testable without mutating
+ * the real process environment.
+ */
+export declare function loadDotEnvForCli(deps?: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fileExists?: (path: string) => boolean;
+    loadEnvFile?: ((path: string) => void) | null;
+}): DotEnvLoadResult;
+/**
+ * Decide whether to warn that an `.env`-sourced `DATABASE_URL` is overriding a
+ * differing, non-empty `url` in the config file. Pure so it is unit-testable.
+ *
+ * Precedence is unchanged (`.env` `DATABASE_URL` still wins), this only decides
+ * whether that override is silent or loud. We warn ONLY when all hold:
+ *   - no CLI `--url` override (an explicit override is the user's clear intent),
+ *   - `DATABASE_URL` came from `.env` (shell-exported stays silent, as before),
+ *   - the config file has a non-empty `url`, and
+ *   - the two URLs actually differ.
+ *
+ * Returns the warning message (URLs redacted), or `null` for no warning.
+ */
+export declare function dotEnvUrlConflictWarning(input: {
+    provenance: DotEnvProvenance;
+    envUrl: string | undefined;
+    fileConfigUrl: string | undefined;
+    overrideUrl: string | undefined;
+}): string | null;
+/**
+ * Read the consumer's `package.json` `"type"` field. Returns `'module'` for an
+ * ESM project, `'commonjs'` for an explicit or absent (defaulted) CommonJS
+ * project, and `'none'` when there is no readable/parseable package.json.
+ */
+export declare function detectConsumerModuleType(cwd?: string): 'module' | 'commonjs' | 'none';
 export declare function buildMigrateDeployOptions(_args: CliArgs): {
     allowDrift: false;
     allowDestructive: true;

package/dist/cli/index.js

@@ -24,13 +24,13 @@
  *   npx turbine migrate create add_users_table
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { basename, dirname, extname, relative, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
-import { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, } from './config.js';
+import { configTemplate, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.js';
 import { createMigration, inspectMigrationDeploy, listMigrationFiles, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
@@ -191,7 +191,9 @@ function requireUrl(config) {
         newline();
         console.log(`  ${dim('Set it in one of these ways:')}`);
         console.log(`    ${dim('1.')} Add ${cyan('url')} to ${cyan('turbine.config.ts')}`);
-        console.log(`    ${dim('2.')} Set ${cyan('DATABASE_URL')} environment variable`);
+        // .env auto-load needs Node 20.12+ (process.loadEnvFile); be honest below it.
+        const envFileNote = typeof process.loadEnvFile === 'function' ? '(auto-loaded)' : '(needs Node 20.12+ to auto-load)';
+        console.log(`    ${dim('2.')} Set ${cyan('DATABASE_URL')} in your environment or a ${cyan('.env')} file ${dim(envFileNote)}`);
         console.log(`    ${dim('3.')} Pass ${cyan('--url')} flag`);
         newline();
         process.exit(1);
@@ -217,8 +219,12 @@ async function loadSchemaFile(schemaFile) {
     try {
         const fileUrl = pathToFileURL(absPath).href;
         const mod = await import(fileUrl);
-        const schema = mod.default ?? mod;
-        if (!schema.tables) {
+        // Unwrap the same CJS-interop double-wrapped default that bites config files
+        // in a "type": "commonjs" project under the tsx loader (see
+        // unwrapModuleDefault). Without this, `mod.default ?? mod` reads
+        // `{ default: schemaDef }` and `.tables` is undefined.
+        const schema = unwrapModuleDefault(mod);
+        if (!schema?.tables) {
             error('Schema file must export a SchemaDef with a "tables" property.');
             process.exit(1);
         }
@@ -255,29 +261,151 @@ function printCjsHintIfApplicable(err) {
         console.log(`  ${dim('Turbine is an ESM package; without it, Node/tsx tries to')} ${cyan('require()')} ${dim('it and fails.')}`);
     }
 }
+/**
+ * Load a local `.env` into `process.env` for the CLI, mirroring what
+ * `node --env-file=.env` does. Loaded UNCONDITIONALLY when a `.env` is present,
+ * so every variable it defines (not just `DATABASE_URL`) reaches the config
+ * file and user scripts.
+ *
+ * A pre-existing variable ALWAYS wins: `process.loadEnvFile()` never overrides
+ * an already-set variable, so a real shell/CI `DATABASE_URL` beats the file.
+ * Provenance is tracked so callers can warn when an `.env`-sourced
+ * `DATABASE_URL` silently overrides a differing `url` in `turbine.config.ts`:
+ * `DATABASE_URL` is `'dotenv'`-sourced only when it was absent before the load
+ * and present after.
+ *
+ * `process.loadEnvFile` is Node 20.12+. Turbine's engines allow `>=20.0.0`, so
+ * on older runtimes this no-ops with `unsupported: true` (never throws). A
+ * loader that throws (unreadable file, a directory named `.env`) is caught and
+ * surfaced as `loadError`, never a raw unhandled rejection. Deliberately
+ * CLI-only: the library must never read files.
+ *
+ * Dependencies are injectable purely so this is unit-testable without mutating
+ * the real process environment.
+ */
+export function loadDotEnvForCli(deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const fileExists = deps.fileExists ?? existsSync;
+    const envPath = join(cwd, '.env');
+    const hadUrlBefore = Boolean(env.DATABASE_URL);
+    const shellOrNone = hadUrlBefore ? 'shell' : 'none';
+    if (!fileExists(envPath)) {
+        return { fileExists: false, loaded: false, unsupported: false, databaseUrlProvenance: shellOrNone };
+    }
+    const loader = deps.loadEnvFile !== undefined
+        ? deps.loadEnvFile
+        : typeof process.loadEnvFile === 'function'
+            ? process.loadEnvFile.bind(process)
+            : null;
+    if (!loader) {
+        return { fileExists: true, loaded: false, unsupported: true, databaseUrlProvenance: shellOrNone };
+    }
+    try {
+        loader(envPath);
+    }
+    catch (err) {
+        return {
+            fileExists: true,
+            loaded: false,
+            unsupported: false,
+            databaseUrlProvenance: shellOrNone,
+            loadError: err instanceof Error ? err.message : String(err),
+        };
+    }
+    // `.env`-sourced only if DATABASE_URL was absent before and present after.
+    const provenance = hadUrlBefore ? 'shell' : env.DATABASE_URL ? 'dotenv' : 'none';
+    return { fileExists: true, loaded: true, unsupported: false, databaseUrlProvenance: provenance };
+}
+/**
+ * Decide whether to warn that an `.env`-sourced `DATABASE_URL` is overriding a
+ * differing, non-empty `url` in the config file. Pure so it is unit-testable.
+ *
+ * Precedence is unchanged (`.env` `DATABASE_URL` still wins), this only decides
+ * whether that override is silent or loud. We warn ONLY when all hold:
+ *   - no CLI `--url` override (an explicit override is the user's clear intent),
+ *   - `DATABASE_URL` came from `.env` (shell-exported stays silent, as before),
+ *   - the config file has a non-empty `url`, and
+ *   - the two URLs actually differ.
+ *
+ * Returns the warning message (URLs redacted), or `null` for no warning.
+ */
+export function dotEnvUrlConflictWarning(input) {
+    if (input.overrideUrl)
+        return null;
+    if (input.provenance !== 'dotenv')
+        return null;
+    const fileUrl = input.fileConfigUrl?.trim();
+    if (!fileUrl)
+        return null;
+    if (!input.envUrl)
+        return null;
+    if (fileUrl === input.envUrl)
+        return null;
+    return (`DATABASE_URL from .env (${redactUrl(input.envUrl)}) is overriding the url in your config file ` +
+        `(${redactUrl(fileUrl)}). Using the .env value. Remove DATABASE_URL from .env, or unset the config url, ` +
+        `to silence this.`);
+}
+/**
+ * Read the consumer's `package.json` `"type"` field. Returns `'module'` for an
+ * ESM project, `'commonjs'` for an explicit or absent (defaulted) CommonJS
+ * project, and `'none'` when there is no readable/parseable package.json.
+ */
+export function detectConsumerModuleType(cwd = process.cwd()) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return 'none';
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.type === 'module' ? 'module' : 'commonjs';
+    }
+    catch {
+        return 'none';
+    }
+}
 // ---------------------------------------------------------------------------
 // Command: init
 // ---------------------------------------------------------------------------
 async function cmdInit(args, config) {
     banner();
     header('Initializing Turbine project');
-    // Detect environment
+    // Detect environment. main() has already auto-loaded a local `.env` into
+    // process.env (when DATABASE_URL was not otherwise set), so these messages
+    // describe the real, post-load state, no more "if set" hand-waving.
     const envUrl = process.env.DATABASE_URL;
     const hasEnvFile = existsSync('.env');
     const hasEnvLocal = existsSync('.env.local');
+    // On Node < 20.12 (no process.loadEnvFile) main() could not auto-load .env, so
+    // we cannot claim it "has no DATABASE_URL"; we simply could not read it.
+    const canAutoLoadEnv = typeof process.loadEnvFile === 'function';
     if (envUrl) {
-        success(`Detected ${cyan('DATABASE_URL')} in environment`);
+        success(`Detected ${cyan('DATABASE_URL')} in the environment`);
     }
-    else if (hasEnvLocal) {
-        info(`Found ${cyan('.env.local')} — Turbine will use ${cyan('DATABASE_URL')} from it if set`);
+    else if (hasEnvFile && !canAutoLoadEnv) {
+        info(`Found ${cyan('.env')} ${dim('(this Node version cannot auto-load it. Upgrade to Node 20.12+ or export')} ${cyan('DATABASE_URL')}${dim(')')}`);
     }
     else if (hasEnvFile) {
-        info(`Found ${cyan('.env')} — Turbine will use ${cyan('DATABASE_URL')} from it if set`);
+        // .env exists but did not provide DATABASE_URL; if it had, the auto-load
+        // in main() would have populated envUrl above.
+        info(`Found ${cyan('.env')} ${dim('(no')} ${cyan('DATABASE_URL')} ${dim('set in it yet)')}`);
+    }
+    else if (hasEnvLocal) {
+        info(`Found ${cyan('.env.local')} ${dim('(note: Turbine only auto-loads')} ${cyan('.env')}${dim(')')}`);
     }
     else {
         info(`No ${cyan('DATABASE_URL')} found in environment`);
     }
     newline();
+    // Heads-up (not an edit) about the consumer's module system. A CommonJS
+    // project (`npm init -y` default, or no "type" field) works fine now that the
+    // config loader unwraps the CJS-interop double-wrapped default, but ESM is the
+    // smoother path for a TypeScript config file.
+    const moduleType = detectConsumerModuleType();
+    if (moduleType === 'commonjs') {
+        info(`Your ${cyan('package.json')} is a CommonJS project ${dim('(no')} ${cyan('"type": "module"')}${dim(').')}`);
+        console.log(`  ${dim('Turbine works either way. For the smoothest TypeScript config experience, consider adding')} ${cyan('"type": "module"')}${dim('.')}`);
+        newline();
+    }
     const configPath = findConfigFile();
     // Create config file
     if (configPath && !args.force) {
@@ -1687,6 +1815,18 @@ async function main() {
         showVersion();
         return;
     }
+    // Load a local `.env` so `DATABASE_URL` (and every other var it defines) is
+    // available to the config file, to `turbine()` in user scripts, and to command
+    // resolution: exactly what the quickstart promises. A pre-existing env var
+    // always wins. Surfaces the honest state when the file cannot be read.
+    const dotEnv = loadDotEnvForCli();
+    if (dotEnv.loadError) {
+        warn(`Could not read ${cyan('.env')}: ${dotEnv.loadError}. Continuing without it.`);
+    }
+    else if (dotEnv.fileExists && dotEnv.unsupported) {
+        warn(`Found ${cyan('.env')} but this Node version cannot auto-load it. ` +
+            `Upgrade to Node 20.12+ or export ${cyan('DATABASE_URL')} yourself.`);
+    }
     // If the user has a TypeScript config file, register the tsx ESM loader
     // before we attempt to import it. Otherwise Node throws
     // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
@@ -1697,17 +1837,16 @@ async function main() {
             failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
         }
     }
-    // Load config file
-    let fileConfig = {};
-    try {
-        fileConfig = await loadConfig();
-    }
-    catch (err) {
-        if (args.command !== 'init') {
-            warn(`Could not load config: ${err instanceof Error ? err.message : String(err)}`);
-            if (err instanceof Error)
-                printCjsHintIfApplicable(err);
-        }
+    // Load config file. A config that exists but fails to import is surfaced
+    // loudly (with a name + the underlying error) instead of being swallowed and
+    // later misreported as a missing database URL.
+    const { config: fileConfig, loadError } = await loadConfigResult();
+    if (loadError && args.command !== 'init') {
+        const underlying = loadError.error instanceof Error ? loadError.error.message : String(loadError.error);
+        warn(`Could not load ${cyan(loadError.filename)}: ${underlying}`);
+        if (loadError.error instanceof Error)
+            printCjsHintIfApplicable(loadError.error);
+        newline();
     }
     const overrides = {
         url: args.url,
@@ -1717,6 +1856,19 @@ async function main() {
         exclude: args.exclude,
     };
     const config = resolveConfig(fileConfig, overrides);
+    // Warn (don't change precedence) when an .env-sourced DATABASE_URL is silently
+    // overriding a differing, non-empty url in the config file (a wrong-database
+    // hazard for push/migrate/seed). Shell-exported DATABASE_URL stays silent.
+    const urlConflict = dotEnvUrlConflictWarning({
+        provenance: dotEnv.databaseUrlProvenance,
+        envUrl: process.env.DATABASE_URL,
+        fileConfigUrl: fileConfig.url,
+        overrideUrl: overrides.url,
+    });
+    if (urlConflict && args.command !== 'init') {
+        warn(urlConflict);
+        newline();
+    }
     try {
         switch (args.command) {
             case 'init':

package/dist/client.js

@@ -386,9 +386,25 @@ export class TurbineClient {
                 idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
                 connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
             };
+            // Did the caller supply ANY explicit connection target? If not, and a
+            // DATABASE_URL is present in the environment, fall back to it so
+            // `turbine()` with no arguments just works (the convention Prisma/Drizzle
+            // use, and what the generated factory JSDoc + `turbine init` promise).
+            // We only read the already-populated env var; the library never parses
+            // .env files (that is the CLI's job). An explicit host/port/db/user/pass
+            // still takes precedence, so this never overrides a deliberate config.
+            const hasExplicitConnection = config.connectionString != null ||
+                config.host != null ||
+                config.port != null ||
+                config.database != null ||
+                config.user != null ||
+                config.password != null;
             if (config.connectionString) {
                 poolConfig.connectionString = config.connectionString;
             }
+            else if (!hasExplicitConnection && process.env.DATABASE_URL) {
+                poolConfig.connectionString = process.env.DATABASE_URL;
+            }
             else {
                 poolConfig.host = config.host ?? 'localhost';
                 poolConfig.port = config.port ?? 5432;

package/dist/errors.d.ts

@@ -91,7 +91,18 @@ export declare class NotFoundError extends TurbineError {
 /** Thrown when a query or transaction exceeds the configured timeout */
 export declare class TimeoutError extends TurbineError {
     readonly timeoutMs: number;
-    constructor(timeoutMs: number, context?: string);
+    /**
+     * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
+     *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
+     *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
+     * @param context human label for the operation ("Query", "Transaction").
+     * @param options optional `message` override and pg `cause` to preserve, used
+     *   when wrapping a driver error rather than a client-side timer expiry.
+     */
+    constructor(timeoutMs: number, context?: string, options?: {
+        message?: string;
+        cause?: unknown;
+    });
 }
 /** Thrown when query arguments fail validation (unknown column, invalid operator, etc.) */
 export declare class ValidationError extends TurbineError {
@@ -99,7 +110,14 @@ export declare class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export declare class ConnectionError extends TurbineError {
-    constructor(message: string);
+    /**
+     * @param message human-readable connection failure description.
+     * @param options optional pg/driver `cause` to preserve, used when wrapping a
+     *   connection-class driver error via `wrapPgError`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 /** Thrown when a relation reference is invalid */
 export declare class RelationError extends TurbineError {
@@ -297,6 +315,8 @@ export declare class UnsupportedFeatureError extends TurbineError {
  *   23P01 (exclusion_violation)   -> ExclusionConstraintError
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */

package/dist/errors.js

@@ -144,8 +144,16 @@ export class NotFoundError extends TurbineError {
 /** Thrown when a query or transaction exceeds the configured timeout */
 export class TimeoutError extends TurbineError {
     timeoutMs;
-    constructor(timeoutMs, context = 'Query') {
-        super(TurbineErrorCode.TIMEOUT, `[turbine] ${context} timed out after ${timeoutMs}ms`);
+    /**
+     * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
+     *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
+     *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
+     * @param context human label for the operation ("Query", "Transaction").
+     * @param options optional `message` override and pg `cause` to preserve, used
+     *   when wrapping a driver error rather than a client-side timer expiry.
+     */
+    constructor(timeoutMs, context = 'Query', options) {
+        super(TurbineErrorCode.TIMEOUT, options?.message ?? `[turbine] ${context} timed out after ${timeoutMs}ms`, options);
         this.name = 'TimeoutError';
         this.timeoutMs = timeoutMs;
     }
@@ -159,8 +167,13 @@ export class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export class ConnectionError extends TurbineError {
-    constructor(message) {
-        super(TurbineErrorCode.CONNECTION, message);
+    /**
+     * @param message human-readable connection failure description.
+     * @param options optional pg/driver `cause` to preserve, used when wrapping a
+     *   connection-class driver error via `wrapPgError`.
+     */
+    constructor(message, options) {
+        super(TurbineErrorCode.CONNECTION, message, options);
         this.name = 'ConnectionError';
     }
 }
@@ -477,6 +490,35 @@ function parseColumnsFromDetail(detail) {
         return undefined;
     return m[1].split(',').map((s) => s.trim());
 }
+/**
+ * Connection-class error codes. Covers both pg SQLSTATEs (class 08
+ * connection_exception, plus a few class-53/57 admin/availability codes) and
+ * Node driver-level error codes that arrive on the same `.code` field when the
+ * socket never reaches Postgres. All map to {@link ConnectionError} (E004).
+ *
+ * `57014` (query_canceled, a server-side `statement_timeout` cancellation) is
+ * intentionally NOT here: it maps to {@link TimeoutError} (E002) instead.
+ */
+const CONNECTION_ERROR_CODES = new Set([
+    // pg SQLSTATE class 08: connection_exception
+    '08000', // connection_exception
+    '08001', // sqlclient_unable_to_establish_sqlconnection
+    '08003', // connection_does_not_exist
+    '08004', // sqlserver_rejected_establishment_of_sqlconnection
+    '08006', // connection_failure
+    '08P01', // protocol_violation
+    // pg SQLSTATE class 53/57 (server unavailable / shutting down)
+    '53300', // too_many_connections
+    '57P01', // admin_shutdown
+    '57P02', // crash_shutdown
+    '57P03', // cannot_connect_now
+    // Node driver-level socket errors (surface on err.code too)
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EPIPE',
+]);
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.
@@ -489,6 +531,8 @@ function parseColumnsFromDetail(detail) {
  *   23P01 (exclusion_violation)   -> ExclusionConstraintError
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */
@@ -541,7 +585,21 @@ export function wrapPgError(err) {
             return new SerializationFailureError({
                 cause: err,
             });
+        case '57014':
+            // query_canceled: a server-side statement_timeout cancelled the query.
+            // Turbine did not set the deadline (that lives in Postgres config), so
+            // there is no client-side budget to report → timeoutMs = 0.
+            return new TimeoutError(0, 'Query', {
+                message: '[turbine] Query canceled by server-side statement_timeout',
+                cause: err,
+            });
         default:
+            if (CONNECTION_ERROR_CODES.has(e.code)) {
+                const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? e.message : undefined;
+                return new ConnectionError(pgMessage
+                    ? `[turbine] Database connection error: ${pgMessage}`
+                    : `[turbine] Database connection error (${e.code})`, { cause: err });
+            }
             return err;
     }
 }

package/dist/generate.js

@@ -670,7 +670,8 @@ export function generateIndex(schema, options) {
     lines.push('/**');
     lines.push(' * Create a new Turbine client instance.');
     lines.push(' *');
-    lines.push(' * @param config - Connection configuration. Falls back to DATABASE_URL env var.');
+    lines.push(' * @param config - Connection configuration. Omit it (or pass no connection');
+    lines.push(' *   fields) to fall back to the `DATABASE_URL` environment variable.');
     lines.push(' * @returns A fully-typed TurbineClient with table accessors.');
     lines.push(' */');
     lines.push('export function turbine(config?: TurbineConfig): TurbineClient {');

package/dist/powql.js

@@ -582,7 +582,7 @@ export class PowqlInterface {
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
-            console.warn(`[turbine] findMany on "${this.table}" has no limit — this scans the whole table.`);
+            console.warn(`[turbine] findMany on "${this.table}" has no limit: this scans the whole table.`);
         }
         const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
         const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';

package/dist/query/builder.d.ts

@@ -22,6 +22,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     private readonly sqlTemplateCache;
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    private lastCacheHit;
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
@@ -183,8 +192,42 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     private acquireSql;
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    private crossCheckCache;
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires