turbine-orm 0.32.0 → 0.32.2

package/dist/cli/config.d.ts

@@ -49,9 +49,61 @@ export type TurbineConfig = TurbineCliConfig;
  * silently matches zero tables. Used by `turbine generate` to fail loudly.
  */
 export declare function looksLikeSchemaFilePath(schema: string): boolean;
+/** A config-file load attempt that failed, kept so the CLI can surface it. */
+export interface ConfigLoadError {
+    /** The config file whose import threw (e.g. `turbine.config.ts`). */
+    filename: string;
+    /** The underlying error thrown by the dynamic import. */
+    error: unknown;
+}
+/** Result of {@link loadConfigResult}: the resolved config plus any load failure. */
+export interface ConfigLoadResult {
+    config: TurbineCliConfig;
+    /**
+     * Set when a config file existed but failed to import. The config is still
+     * returned as `{}` so resolution falls through to env vars and CLI flags, but
+     * the CLI should surface this rather than let it masquerade as a missing URL.
+     */
+    loadError?: ConfigLoadError;
+}
+/**
+ * Unwrap the module object returned by `import(configFile)` down to the actual
+ * config value.
+ *
+ * With `"type": "commonjs"` in the consumer's package.json (the `npm init -y`
+ * default) plus the tsx loader, importing `turbine.config.ts` yields a
+ * CJS-interop DOUBLE-wrapped default: `mod.default` is itself `{ default: config }`.
+ * A naive `mod.default ?? mod` then reads every field as `undefined`, so every
+ * command fails with a misleading "No database URL provided".
+ *
+ * This prefers `default` when present (the historical behavior) and then keeps
+ * descending through any additional pure `{ default: … }` wrappers, so both the
+ * correct single-default shape and the double-wrapped shape resolve to the same
+ * config. A genuine config object (which has real fields, never a lone
+ * `default`) is returned untouched.
+ */
+export declare function unwrapModuleDefault(mod: unknown): unknown;
+/**
+ * {@link unwrapModuleDefault} specialized for config files: a non-object export
+ * collapses to `{}` so downstream resolution falls through to env vars/flags.
+ */
+export declare function unwrapConfigModule(mod: unknown): TurbineCliConfig;
+/**
+ * Attempt to load a turbine config file from the given directory, returning the
+ * resolved config together with any load failure so the caller can surface it.
+ *
+ * Candidates are tried in {@link CONFIG_FILES} priority order. The first one
+ * that imports successfully wins. If a candidate exists but throws (syntax
+ * error, ESM/CJS interop failure, etc.) we remember the first such error and
+ * keep trying lower-priority candidates; if none load, the remembered error is
+ * returned in `loadError` while `config` stays `{}` so env/flag resolution can
+ * still proceed.
+ */
+export declare function loadConfigResult(cwd?: string): Promise<ConfigLoadResult>;
 /**
  * Attempt to load a turbine config file from the current directory.
- * Returns the config if found, or an empty object.
+ * Returns the config if found, or an empty object. Load failures are swallowed
+ * here; callers that need to surface them should use {@link loadConfigResult}.
  */
 export declare function loadConfig(cwd?: string): Promise<TurbineCliConfig>;
 /**

package/dist/cli/config.js

@@ -25,15 +25,66 @@ export function looksLikeSchemaFilePath(schema) {
 // ---------------------------------------------------------------------------
 const CONFIG_FILES = ['turbine.config.ts', 'turbine.config.mts', 'turbine.config.js', 'turbine.config.mjs'];
 const DEFAULT_SEED_CANDIDATES = ['seed.ts', 'seed.js', 'seed.sql'];
-// ---------------------------------------------------------------------------
-// Load config
-// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
- * Attempt to load a turbine config file from the current directory.
- * Returns the config if found, or an empty object.
+ * True when `value` is a pure ESM/CJS-interop wrapper: an object whose only
+ * meaningful export is `default` (the `__esModule` marker is ignored). No
+ * Turbine config field is named `default`, so a real config never matches.
  */
-export async function loadConfig(cwd) {
+function isPureDefaultWrapper(value) {
+    const keys = Object.keys(value).filter((k) => k !== '__esModule');
+    return keys.length === 1 && keys[0] === 'default';
+}
+/**
+ * Unwrap the module object returned by `import(configFile)` down to the actual
+ * config value.
+ *
+ * With `"type": "commonjs"` in the consumer's package.json (the `npm init -y`
+ * default) plus the tsx loader, importing `turbine.config.ts` yields a
+ * CJS-interop DOUBLE-wrapped default: `mod.default` is itself `{ default: config }`.
+ * A naive `mod.default ?? mod` then reads every field as `undefined`, so every
+ * command fails with a misleading "No database URL provided".
+ *
+ * This prefers `default` when present (the historical behavior) and then keeps
+ * descending through any additional pure `{ default: … }` wrappers, so both the
+ * correct single-default shape and the double-wrapped shape resolve to the same
+ * config. A genuine config object (which has real fields, never a lone
+ * `default`) is returned untouched.
+ */
+export function unwrapModuleDefault(mod) {
+    // Step 1: prefer `default` at the top level (mirrors `mod.default ?? mod`).
+    let value = isPlainObject(mod) && mod.default != null ? mod.default : mod;
+    // Step 2: peel off any further pure interop wrappers, bounded to avoid a
+    // pathological self-referential object spinning forever.
+    for (let depth = 0; depth < 10 && isPlainObject(value) && isPureDefaultWrapper(value); depth++) {
+        value = value.default;
+    }
+    return value;
+}
+/**
+ * {@link unwrapModuleDefault} specialized for config files: a non-object export
+ * collapses to `{}` so downstream resolution falls through to env vars/flags.
+ */
+export function unwrapConfigModule(mod) {
+    const value = unwrapModuleDefault(mod);
+    return isPlainObject(value) ? value : {};
+}
+/**
+ * Attempt to load a turbine config file from the given directory, returning the
+ * resolved config together with any load failure so the caller can surface it.
+ *
+ * Candidates are tried in {@link CONFIG_FILES} priority order. The first one
+ * that imports successfully wins. If a candidate exists but throws (syntax
+ * error, ESM/CJS interop failure, etc.) we remember the first such error and
+ * keep trying lower-priority candidates; if none load, the remembered error is
+ * returned in `loadError` while `config` stays `{}` so env/flag resolution can
+ * still proceed.
+ */
+export async function loadConfigResult(cwd) {
     const dir = cwd ?? process.cwd();
+    let loadError;
     for (const filename of CONFIG_FILES) {
         const filePath = join(dir, filename);
         if (!existsSync(filePath))
@@ -41,21 +92,27 @@ export async function loadConfig(cwd) {
         try {
             const absPath = resolve(filePath);
             const fileUrl = pathToFileURL(absPath).href;
-            // For .ts files, we need to rely on Node's --experimental-strip-types
-            // or the tsx loader. Dynamic import handles .js/.mjs natively.
+            // For .ts files, we rely on the tsx loader being registered by the CLI
+            // before this runs. Dynamic import handles .js/.mjs natively.
             const mod = await import(fileUrl);
-            const config = mod.default ?? mod;
-            return config;
+            return { config: unwrapConfigModule(mod) };
         }
         catch (err) {
-            // If importing a .ts file fails, try the next one
-            if (filename.endsWith('.ts') || filename.endsWith('.mts')) {
-                continue;
-            }
-            throw new Error(`Failed to load config from ${filename}: ${err instanceof Error ? err.message : String(err)}`);
+            // Remember the first real load failure but keep trying lower-priority
+            // candidates (e.g. a working .js next to a broken .ts).
+            if (!loadError)
+                loadError = { filename, error: err };
         }
     }
-    return {};
+    return loadError ? { config: {}, loadError } : { config: {} };
+}
+/**
+ * Attempt to load a turbine config file from the current directory.
+ * Returns the config if found, or an empty object. Load failures are swallowed
+ * here; callers that need to surface them should use {@link loadConfigResult}.
+ */
+export async function loadConfig(cwd) {
+    return (await loadConfigResult(cwd)).config;
 }
 /**
  * Find the config file path (for display purposes).

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.
  */