turbine-orm 0.32.0 → 0.32.2

package/README.md

@@ -25,27 +25,28 @@ See [How It Works](#how-it-works) for the `json_agg` query strategy itself — b
 
 ## Benchmarks
 
-Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizzle 0.45** (relational queries) on a **Neon** PostgreSQL database (pooled endpoint, US-East, PostgreSQL 17.8). 100 iterations, 20 warmup, Node v22. Same schema, same data (1K users, 10K posts, 50K comments), same connection pool config. _Measured April 2026 on turbine-orm 0.7.1; the core read path these scenarios exercise is unchanged through 0.17.0 — see [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) to reproduce._
+Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizzle 0.45** (relational queries) on a **local PostgreSQL 17.9** database over a Unix socket. 200 iterations, 20 warmup, Node v24. Same schema, same data (1K users, 10K posts, 50K comments), same connection pool config. _Measured 2026-07-14 on turbine-orm 0.32.0 (Apple Silicon MacBook Pro, macOS). A local socket has no network round-trip, so these numbers are sub-millisecond and are **not** comparable to the earlier pooled-Neon table: they isolate per-query overhead instead of hiding it behind ~35 ms of network latency. See [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) to reproduce._
 
 | Scenario | Turbine | Prisma 7 | Drizzle 0.45 |
 |---|---|---|---|
-| findMany — 100 users (flat) | **51.97 ms** | 52.90 ms | 53.51 ms |
-| findMany — 50 users + posts (L2) | **55.84 ms** | 56.10 ms | 88.80 ms |
-| findMany — 10 users → posts → comments (L3) | 52.77 ms | 59.35 ms | **52.38 ms** |
-| findUnique — single user by PK | **47.66 ms** | 52.15 ms | 47.78 ms |
-| findUnique — user + posts + comments (L3) | **51.71 ms** | 54.42 ms | 52.47 ms |
-| count — all users | **44.57 ms** | 47.54 ms | 46.75 ms |
-| stream — iterate 50K rows (batch 1000) | 3,207 ms | **3,099 ms** | 4,620 ms |
-| atomic increment — `view_count + 1` | 49.76 ms | 49.09 ms | **46.25 ms** |
-| pipeline — 5-query batch | 318 ms | 327 ms | **316 ms** |
+| findMany, 100 users (flat) | **0.22 ms** | 0.53 ms | 0.34 ms |
+| findMany, 50 users + posts (L2) | 2.41 ms | 4.63 ms | **1.82 ms** |
+| findMany, 10 users → posts → comments (L3) | 1.13 ms | 3.69 ms | **1.01 ms** |
+| findUnique, single user by PK | **0.06 ms** | 0.11 ms | 0.09 ms |
+| findUnique, user + posts + comments (L3) | **0.18 ms** | 0.43 ms | 0.30 ms |
+| count, all users | **0.06 ms** | 0.08 ms | 0.07 ms |
+| stream, iterate 50K rows (batch 1000) | 58.6 ms | 69.7 ms | **48.9 ms** |
+| atomic increment, `view_count + 1` | 0.13 ms | 0.23 ms | **0.11 ms** |
+| pipeline, 5-query batch | **0.20 ms** | 0.61 ms | 0.58 ms |
+| hot findUnique, 500x same shape | **0.05 ms** | 0.09 ms | 0.10 ms |
 
-**Against a real pooled database, most single-query scenarios are within noise** — network round-trip to Neon is ~33–40 ms, which swamps per-query CPU overhead. But a few results stand out:
+**Over a local socket the network floor disappears, so per-query overhead becomes the whole signal.** The picture that emerges (stable across two full runs):
 
-- **L2 nested reads.** Turbine and Prisma are neck-and-neck (~56 ms), while Drizzle is **1.59× slower** (89 ms) on the 50-user + posts scenario. Turbine's `json_agg` approach and SQL template caching pay off here.
-- **Streaming 50K rows.** Turbine's optimized streaming (speculative first fetch + batch size 1000) matches Prisma at ~3.1–3.2 s. Drizzle's keyset pagination is 1.49× slower at 4.6 s. Turbine's cursor still gives you correctness on any `orderBy` and clean early-`break` semantics.
-- **Pipeline batching** puts 5 independent queries through a single round-trip using the Postgres extended-query pipeline protocol — all three ORMs are tied here since each runs 5 queries sequentially in a transaction.
+- **Turbine leads flat reads, findUnique, count, pipeline, and the hot path.** SQL template caching and prepared statements keep its per-call overhead lowest on simple and repeated-shape queries, and its real Postgres pipeline protocol (one TCP flush for 5 queries) runs the dashboard batch ~3x faster than Prisma's or Drizzle's sequential transaction.
+- **Drizzle leads nested reads (L2), streaming, and atomic increment.** Its relational query builder emits tighter SQL for the posts/comments joins, and its keyset pagination drains 50K rows fastest. Turbine's `json_agg` nesting is close behind and still 1.9x to 3.3x ahead of Prisma on the same L2/L3 shapes. L3 is a genuine Turbine/Drizzle near-tie that flips between runs.
+- **Prisma trails on every scenario here.** Its engine-less client's per-query work is no longer masked by network latency; on a pooled remote database (the regime we measured previously) these same deltas compress back into the noise floor.
 
-Performance is at parity with Prisma and Drizzle — the real reasons to choose Turbine are elsewhere: **one dependency and no WASM** (vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler), the **only read-only Studio** in the TS ORM ecosystem, **PII-safe error messages** that never leak user data, and **SQL-first migrations** with SHA-256 drift detection. Deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes — no manual assertion, no helper annotation.
+Net: on a local socket Turbine wins 6 of 10 scenarios, loses L2 / streaming / atomic increment to Drizzle, and trades the L3 lead run-to-run. It is competitive-to-ahead across the board rather than a clean sweep, and the honest takeaway is unchanged: performance is close enough that the real reasons to choose Turbine are elsewhere. **One dependency and no WASM** (vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler), the **only read-only Studio** in the TS ORM ecosystem, **PII-safe error messages** that never leak user data, and **SQL-first migrations** with SHA-256 drift detection. Deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes, with no manual assertion and no helper annotation.
 
 > Full analysis with p50/p95/p99 and methodology notes: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md).
 > Reproduce: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench.ts`
@@ -64,16 +65,22 @@ npx turbine init --url postgres://user:pass@localhost:5432/mydb
 npx turbine generate
 ```
 
-> **CLI prerequisites.** The `turbine` CLI loads your `turbine.config.ts` / `turbine/schema.ts` directly, so a fresh project needs (1) `tsx` installed — otherwise `.ts` config loading fails with *"Loading .ts config / schema files requires tsx to be installed"* — and (2) `"type": "module"` in `package.json`, since Turbine is ESM. Without it you'll hit `Error [ERR_REQUIRE_ESM]: Cannot require() ES Module`. `create-next-app` sets neither by default. See [USING-TURBINE-ORM.md §0](docs/USING-TURBINE-ORM.md) for details.
+> **CLI prerequisites.** The `turbine` CLI loads your `turbine.config.ts` / `turbine/schema.ts` directly, so a fresh project needs `tsx` installed (otherwise `.ts` config loading fails with *"Loading .ts config / schema files requires tsx to be installed"*). Turbine ships both ESM and CommonJS builds, so the CLI loads your config and schema correctly in either an ESM (`"type": "module"`) or a CommonJS project; ESM is recommended but not required. See [USING-TURBINE-ORM.md §0](docs/USING-TURBINE-ORM.md) for details.
 
-Works with both ESM and CommonJS:
+The `turbine-orm` package ships real dual builds, so importing the package works from either module system:
 
 ```typescript
 // ESM
-import { turbine } from './generated/turbine';
+import { turbine } from 'turbine-orm';
 
 // CommonJS
-const { turbine } = require('./generated/turbine');
+const { turbine } = require('turbine-orm');
+```
+
+The generated client (`./generated/turbine/`) is TypeScript source: it re-exports across files with ESM-style `./metadata.js` specifiers, so you consume it through your bundler, `tsx`, or `tsc` like the rest of your app:
+
+```typescript
+import { turbine } from './generated/turbine';
 ```
 
 This introspects your database and generates a fully-typed client at `./generated/turbine/`.
@@ -601,12 +608,14 @@ Commands:
   migrate create <name>        Create a new SQL migration file
   migrate create <name> --auto Auto-generate from schema diff
   migrate up                   Apply pending migrations
+  migrate deploy               Apply pending migrations without prompts
   migrate down                 Rollback last migration
   migrate status               Show applied/pending migrations
   seed                         Run seed file
   status                       Show database schema summary
   doctor                       Check relations for missing FK indexes (--fix emits migration)
   studio                       Launch local read-only Studio web UI
+  mcp                          Start read-only MCP server over JSON-RPC stdio
   observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
 Options:

package/dist/cjs/cli/config.js

@@ -40,6 +40,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.looksLikeSchemaFilePath = looksLikeSchemaFilePath;
+exports.unwrapModuleDefault = unwrapModuleDefault;
+exports.unwrapConfigModule = unwrapConfigModule;
+exports.loadConfigResult = loadConfigResult;
 exports.loadConfig = loadConfig;
 exports.findConfigFile = findConfigFile;
 exports.resolveConfig = resolveConfig;
@@ -66,15 +69,66 @@ 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.
  */
-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.
+ */
+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.
+ */
+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.
+ */
+async function loadConfigResult(cwd) {
     const dir = cwd ?? process.cwd();
+    let loadError;
     for (const filename of CONFIG_FILES) {
         const filePath = (0, node_path_1.join)(dir, filename);
         if (!(0, node_fs_1.existsSync)(filePath))
@@ -82,21 +136,27 @@ async function loadConfig(cwd) {
         try {
             const absPath = (0, node_path_1.resolve)(filePath);
             const fileUrl = (0, node_url_1.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 Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
-            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}.
+ */
+async function loadConfig(cwd) {
+    return (await loadConfigResult(cwd)).config;
 }
 /**
  * Find the config file path (for display purposes).

package/dist/cjs/cli/index.js

@@ -59,6 +59,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgs = parseArgs;
+exports.loadDotEnvForCli = loadDotEnvForCli;
+exports.dotEnvUrlConflictWarning = dotEnvUrlConflictWarning;
+exports.detectConsumerModuleType = detectConsumerModuleType;
 exports.buildMigrateDeployOptions = buildMigrateDeployOptions;
 exports.getSeedExecutionPlan = getSeedExecutionPlan;
 exports.isLoopbackHost = isLoopbackHost;
@@ -230,7 +233,9 @@ function requireUrl(config) {
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.dim)('Set it in one of these ways:')}`);
         console.log(`    ${(0, ui_js_1.dim)('1.')} Add ${(0, ui_js_1.cyan)('url')} to ${(0, ui_js_1.cyan)('turbine.config.ts')}`);
-        console.log(`    ${(0, ui_js_1.dim)('2.')} Set ${(0, ui_js_1.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(`    ${(0, ui_js_1.dim)('2.')} Set ${(0, ui_js_1.cyan)('DATABASE_URL')} in your environment or a ${(0, ui_js_1.cyan)('.env')} file ${(0, ui_js_1.dim)(envFileNote)}`);
         console.log(`    ${(0, ui_js_1.dim)('3.')} Pass ${(0, ui_js_1.cyan)('--url')} flag`);
         (0, ui_js_1.newline)();
         process.exit(1);
@@ -256,8 +261,12 @@ async function loadSchemaFile(schemaFile) {
     try {
         const fileUrl = (0, node_url_1.pathToFileURL)(absPath).href;
         const mod = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
-        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 = (0, config_js_1.unwrapModuleDefault)(mod);
+        if (!schema?.tables) {
             (0, ui_js_1.error)('Schema file must export a SchemaDef with a "tables" property.');
             process.exit(1);
         }
@@ -294,29 +303,151 @@ function printCjsHintIfApplicable(err) {
         console.log(`  ${(0, ui_js_1.dim)('Turbine is an ESM package; without it, Node/tsx tries to')} ${(0, ui_js_1.cyan)('require()')} ${(0, ui_js_1.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.
+ */
+function loadDotEnvForCli(deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const fileExists = deps.fileExists ?? node_fs_1.existsSync;
+    const envPath = (0, node_path_1.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.
+ */
+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 (${(0, ui_js_1.redactUrl)(input.envUrl)}) is overriding the url in your config file ` +
+        `(${(0, ui_js_1.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.
+ */
+function detectConsumerModuleType(cwd = process.cwd()) {
+    const pkgPath = (0, node_path_1.join)(cwd, 'package.json');
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return 'none';
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, 'utf-8'));
+        return pkg.type === 'module' ? 'module' : 'commonjs';
+    }
+    catch {
+        return 'none';
+    }
+}
 // ---------------------------------------------------------------------------
 // Command: init
 // ---------------------------------------------------------------------------
 async function cmdInit(args, config) {
     (0, ui_js_1.banner)();
     (0, ui_js_1.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 = (0, node_fs_1.existsSync)('.env');
     const hasEnvLocal = (0, node_fs_1.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) {
-        (0, ui_js_1.success)(`Detected ${(0, ui_js_1.cyan)('DATABASE_URL')} in environment`);
+        (0, ui_js_1.success)(`Detected ${(0, ui_js_1.cyan)('DATABASE_URL')} in the environment`);
     }
-    else if (hasEnvLocal) {
-        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env.local')} — Turbine will use ${(0, ui_js_1.cyan)('DATABASE_URL')} from it if set`);
+    else if (hasEnvFile && !canAutoLoadEnv) {
+        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(this Node version cannot auto-load it. Upgrade to Node 20.12+ or export')} ${(0, ui_js_1.cyan)('DATABASE_URL')}${(0, ui_js_1.dim)(')')}`);
     }
     else if (hasEnvFile) {
-        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env')} — Turbine will use ${(0, ui_js_1.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.
+        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(no')} ${(0, ui_js_1.cyan)('DATABASE_URL')} ${(0, ui_js_1.dim)('set in it yet)')}`);
+    }
+    else if (hasEnvLocal) {
+        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env.local')} ${(0, ui_js_1.dim)('(note: Turbine only auto-loads')} ${(0, ui_js_1.cyan)('.env')}${(0, ui_js_1.dim)(')')}`);
     }
     else {
         (0, ui_js_1.info)(`No ${(0, ui_js_1.cyan)('DATABASE_URL')} found in environment`);
     }
     (0, ui_js_1.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') {
+        (0, ui_js_1.info)(`Your ${(0, ui_js_1.cyan)('package.json')} is a CommonJS project ${(0, ui_js_1.dim)('(no')} ${(0, ui_js_1.cyan)('"type": "module"')}${(0, ui_js_1.dim)(').')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Turbine works either way. For the smoothest TypeScript config experience, consider adding')} ${(0, ui_js_1.cyan)('"type": "module"')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.newline)();
+    }
     const configPath = (0, config_js_1.findConfigFile)();
     // Create config file
     if (configPath && !args.force) {
@@ -1726,6 +1857,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) {
+        (0, ui_js_1.warn)(`Could not read ${(0, ui_js_1.cyan)('.env')}: ${dotEnv.loadError}. Continuing without it.`);
+    }
+    else if (dotEnv.fileExists && dotEnv.unsupported) {
+        (0, ui_js_1.warn)(`Found ${(0, ui_js_1.cyan)('.env')} but this Node version cannot auto-load it. ` +
+            `Upgrade to Node 20.12+ or export ${(0, ui_js_1.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`.
@@ -1736,17 +1879,16 @@ async function main() {
             failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
         }
     }
-    // Load config file
-    let fileConfig = {};
-    try {
-        fileConfig = await (0, config_js_1.loadConfig)();
-    }
-    catch (err) {
-        if (args.command !== 'init') {
-            (0, ui_js_1.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 (0, config_js_1.loadConfigResult)();
+    if (loadError && args.command !== 'init') {
+        const underlying = loadError.error instanceof Error ? loadError.error.message : String(loadError.error);
+        (0, ui_js_1.warn)(`Could not load ${(0, ui_js_1.cyan)(loadError.filename)}: ${underlying}`);
+        if (loadError.error instanceof Error)
+            printCjsHintIfApplicable(loadError.error);
+        (0, ui_js_1.newline)();
     }
     const overrides = {
         url: args.url,
@@ -1756,6 +1898,19 @@ async function main() {
         exclude: args.exclude,
     };
     const config = (0, config_js_1.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') {
+        (0, ui_js_1.warn)(urlConflict);
+        (0, ui_js_1.newline)();
+    }
     try {
         switch (args.command) {
             case 'init':

package/dist/cjs/client.js

@@ -394,9 +394,25 @@ 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/cjs/errors.js

@@ -152,8 +152,16 @@ exports.NotFoundError = NotFoundError;
 /** Thrown when a query or transaction exceeds the configured timeout */
 class TimeoutError extends TurbineError {
     timeoutMs;
-    constructor(timeoutMs, context = 'Query') {
-        super(exports.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(exports.TurbineErrorCode.TIMEOUT, options?.message ?? `[turbine] ${context} timed out after ${timeoutMs}ms`, options);
         this.name = 'TimeoutError';
         this.timeoutMs = timeoutMs;
     }
@@ -169,8 +177,13 @@ class ValidationError extends TurbineError {
 exports.ValidationError = ValidationError;
 /** Thrown when a database connection fails */
 class ConnectionError extends TurbineError {
-    constructor(message) {
-        super(exports.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(exports.TurbineErrorCode.CONNECTION, message, options);
         this.name = 'ConnectionError';
     }
 }
@@ -501,6 +514,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.
@@ -513,6 +555,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.
  */
@@ -565,7 +609,21 @@ 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/cjs/generate.js

@@ -677,7 +677,8 @@ 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 {');