turbine-orm 0.5.0 → 0.7.1

package/dist/cli/loader.js

@@ -0,0 +1,91 @@
+/**
+ * turbine-orm CLI — TypeScript loader registration
+ *
+ * The CLI loads user-supplied config and schema files via dynamic `import()`.
+ * Plain Node has no built-in `.ts` loader, so importing `turbine.config.ts`
+ * blows up with `ERR_UNKNOWN_FILE_EXTENSION` unless we register a TypeScript
+ * loader first.
+ *
+ * Strategy:
+ *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
+ *      probe whether `tsx/esm` is resolvable from the user's CWD.
+ *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
+ *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *
+ * `tsx` is intentionally NOT a runtime dependency — many projects already
+ * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+/**
+ * Detect whether a config / schema file path needs the tsx ESM loader.
+ * Returns true for `.ts`, `.mts`, and `.cts` files; false for `.js`, `.mjs`,
+ * `.cjs`, `.json`, missing paths, or anything else.
+ */
+export function needsTsLoader(filePath) {
+    if (!filePath)
+        return false;
+    return /\.(ts|mts|cts)$/i.test(filePath);
+}
+/**
+ * Probe whether `tsx/esm` is resolvable from the user's current working
+ * directory. Returns true if `tsx` is installed in the user's project.
+ *
+ * Accepts an injected `resolver` so unit tests don't need a real filesystem.
+ */
+export function canResolveTsx(resolver) {
+    try {
+        if (resolver) {
+            resolver('tsx/esm');
+            return true;
+        }
+        // Probe relative to the user's CWD, not Turbine's install location.
+        // This way we honour whatever `tsx` version the user has pinned.
+        const userRequire = createRequire(`${process.cwd()}/`);
+        userRequire.resolve('tsx/esm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let tsLoaderState = null;
+/**
+ * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
+ * work. Safe to call multiple times — internal flag prevents double registration.
+ *
+ * Returns:
+ *   - 'registered'  loader was successfully registered this call
+ *   - 'already'     a loader was previously registered (idempotent)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'missing'     `tsx` is not installed in the user's project
+ */
+export async function registerTsLoader() {
+    if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
+        return 'already';
+    }
+    if (!canResolveTsx()) {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+    try {
+        const mod = await import('node:module');
+        const register = mod.register;
+        if (typeof register !== 'function') {
+            tsLoaderState = 'unsupported';
+            return 'unsupported';
+        }
+        register('tsx/esm', pathToFileURL(`${process.cwd()}/`));
+        tsLoaderState = 'registered';
+        return 'registered';
+    }
+    catch {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+}
+/** Reset the loader state — used by unit tests only. */
+export function _resetTsLoaderStateForTests() {
+    tsLoaderState = null;
+}
+//# sourceMappingURL=loader.js.map

package/dist/cli/migrate.d.ts

@@ -73,19 +73,30 @@ export declare function parseMigrationSQL(filePath: string): {
 };
 /**
  * Create a new migration file.
+ * If `autoContent` is provided, the UP/DOWN sections are pre-populated with the given SQL.
  */
-export declare function createMigration(migrationsDir: string, name: string): MigrationFile;
+export declare function createMigration(migrationsDir: string, name: string, autoContent?: {
+    up: string;
+    down: string;
+}): MigrationFile;
 /**
  * Apply all pending migrations (UP).
  *
  * Features:
  * - Idempotent: running twice is safe (already-applied migrations are skipped)
  * - Advisory lock: prevents concurrent migration runs
- * - Checksum validation: detects modified migration files
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
  * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
  */
 export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
     step?: number;
+    allowDrift?: boolean /** @deprecated use allowDrift */;
+    force?: boolean;
 }): Promise<{
     applied: MigrationFile[];
     errors: Array<{

package/dist/cli/migrate.js

@@ -11,15 +11,19 @@
  *   -- DOWN
  *   DROP TABLE users;
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import pg from 'pg';
+import { MigrationError } from '../errors.js';
+import { quoteIdent } from '../query.js';
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
+const QUOTED_TRACKING_TABLE = quoteIdent(TRACKING_TABLE);
 const CREATE_TRACKING_TABLE = `
-  CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+  CREATE TABLE IF NOT EXISTS ${QUOTED_TRACKING_TABLE} (
     id SERIAL PRIMARY KEY,
     name TEXT NOT NULL UNIQUE,
     checksum TEXT NOT NULL,
@@ -31,7 +35,7 @@ async function ensureTrackingTable(client) {
 }
 async function getAppliedMigrations(client) {
     await ensureTrackingTable(client);
-    const result = await client.query(`SELECT id, name, applied_at, checksum FROM ${TRACKING_TABLE} ORDER BY id ASC`);
+    const result = await client.query(`SELECT id, name, applied_at, checksum FROM ${QUOTED_TRACKING_TABLE} ORDER BY id ASC`);
     return result.rows;
 }
 // ---------------------------------------------------------------------------
@@ -139,30 +143,45 @@ export function parseMigrationSQL(filePath) {
     return parseMigrationContent(content);
 }
 /**
- * Simple checksum for a migration file (for drift detection).
+ * SHA-256 checksum for migration drift detection.
+ * Returns a hex-encoded hash of the file content.
  */
 function checksum(content) {
-    let hash = 0;
-    for (let i = 0; i < content.length; i++) {
-        const chr = content.charCodeAt(i);
-        hash = ((hash << 5) - hash + chr) | 0;
-    }
-    return Math.abs(hash).toString(36);
+    return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+/** Detect legacy djb2 checksums (short alphanumeric strings, pre-v0.6) */
+function isLegacyChecksum(hash) {
+    return hash.length < 64;
 }
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
 /**
  * Create a new migration file.
+ * If `autoContent` is provided, the UP/DOWN sections are pre-populated with the given SQL.
  */
-export function createMigration(migrationsDir, name) {
+export function createMigration(migrationsDir, name, autoContent) {
     mkdirSync(migrationsDir, { recursive: true });
     const now = new Date();
     const ts = formatTimestamp(now);
     const safeName = sanitizeName(name);
     const filename = `${ts}_${safeName}.sql`;
     const filePath = join(migrationsDir, filename);
-    const template = `-- Migration: ${name}
+    let template;
+    if (autoContent) {
+        template = `-- Migration: ${name} (auto-generated from schema diff)
+-- Created: ${now.toISOString()}
+-- Review this file before running: npx turbine migrate up
+
+-- UP
+${autoContent.up}
+
+-- DOWN
+${autoContent.down}
+`;
+    }
+    else {
+        template = `-- Migration: ${name}
 -- Created: ${now.toISOString()}
 
 -- UP
@@ -171,6 +190,7 @@ export function createMigration(migrationsDir, name) {
 -- DOWN
 -- Write your rollback SQL here
 `;
+    }
     writeFileSync(filePath, template, 'utf-8');
     return {
         filename,
@@ -185,17 +205,16 @@ export function createMigration(migrationsDir, name) {
 /** Fixed lock ID for Turbine migrations — prevents concurrent migrate runs */
 const MIGRATION_LOCK_ID = 8_347_291; // arbitrary but stable
 async function acquireLock(client) {
-    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [MIGRATION_LOCK_ID]);
+    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [
+        MIGRATION_LOCK_ID,
+    ]);
     return result.rows[0]?.pg_try_advisory_lock ?? false;
 }
 async function releaseLock(client) {
     await client.query(`SELECT pg_advisory_unlock($1)`, [MIGRATION_LOCK_ID]);
 }
-// ---------------------------------------------------------------------------
-// Checksum validation
-// ---------------------------------------------------------------------------
 /**
- * Validate that applied migration files have not been modified since they were run.
+ * Validate that applied migration files have not been modified or deleted since they were run.
  * Returns an array of mismatched migrations (empty if all are clean).
  */
 async function validateChecksums(client, migrationsDir) {
@@ -205,15 +224,31 @@ async function validateChecksums(client, migrationsDir) {
     const mismatches = [];
     for (const migration of applied) {
         const file = fileMap.get(migration.name);
-        if (!file)
-            continue; // file deleted — not a checksum issue
+        if (!file) {
+            mismatches.push({
+                name: migration.name,
+                expected: migration.checksum,
+                actual: '',
+                type: 'missing',
+            });
+            continue;
+        }
         const content = readFileSync(file.path, 'utf-8');
         const currentHash = checksum(content);
         if (currentHash !== migration.checksum) {
+            // Auto-upgrade legacy djb2 checksums to SHA-256 without flagging as modified
+            if (isLegacyChecksum(migration.checksum)) {
+                await client.query(`UPDATE ${QUOTED_TRACKING_TABLE} SET checksum = $1 WHERE name = $2`, [
+                    currentHash,
+                    migration.name,
+                ]);
+                continue;
+            }
             mismatches.push({
                 name: migration.name,
                 expected: migration.checksum,
                 actual: currentHash,
+                type: 'modified',
             });
         }
     }
@@ -225,37 +260,57 @@ async function validateChecksums(client, migrationsDir) {
  * Features:
  * - Idempotent: running twice is safe (already-applied migrations are skipped)
  * - Advisory lock: prevents concurrent migration runs
- * - Checksum validation: detects modified migration files
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
  * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
  */
 export async function migrateUp(connectionString, migrationsDir, options) {
     const client = new pg.Client({ connectionString });
     await client.connect();
+    // Treat `force` as an alias for `allowDrift` for backwards compatibility.
+    const allowDrift = options?.allowDrift === true || options?.force === true;
     try {
         // Acquire advisory lock to prevent concurrent migrations
         const gotLock = await acquireLock(client);
         if (!gotLock) {
-            return {
-                applied: [],
-                errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
         try {
             await ensureTrackingTable(client);
-            // Validate checksums of already-applied migrations
-            const mismatches = await validateChecksums(client, migrationsDir);
-            if (mismatches.length > 0) {
-                const names = mismatches.map((m) => m.name).join(', ');
-                return {
-                    applied: [],
-                    errors: [{
-                            file: { filename: '', path: '', name: '', timestamp: '' },
-                            error: `Checksum mismatch: migration file(s) modified after application: ${names}. This is dangerous — applied migrations should be immutable. Use --force to skip this check.`,
-                        }],
-                };
+            // Validate checksums of already-applied migrations.
+            // Drift = an APPLIED migration's on-disk file has changed (or been deleted)
+            // since it was run. Either situation means the database state and the
+            // migration history no longer agree, so we BLOCK the run by default.
+            // Users can pass `allowDrift: true` (CLI: `--allow-drift`) to force past
+            // the block when they are intentionally rewriting history.
+            if (!allowDrift) {
+                const mismatches = await validateChecksums(client, migrationsDir);
+                if (mismatches.length > 0) {
+                    const modified = mismatches.filter((m) => m.type === 'modified');
+                    const missing = mismatches.filter((m) => m.type === 'missing');
+                    const lines = [
+                        '[turbine] Migration drift detected — refusing to apply pending migrations.',
+                        '',
+                        'Applied migrations should be immutable. The following files no longer match their applied state:',
+                        '',
+                    ];
+                    for (const m of modified) {
+                        lines.push(`  - ${m.name}.sql  (modified on disk)`);
+                    }
+                    for (const m of missing) {
+                        lines.push(`  - ${m.name}.sql  (deleted from disk)`);
+                    }
+                    lines.push('');
+                    lines.push('Fix one of these:');
+                    lines.push('  1. Restore the file(s) to their original content, OR');
+                    lines.push('  2. Roll back the affected migrations with `npx turbine migrate down`, OR');
+                    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced — make sure you know what you are doing).');
+                    throw new MigrationError(lines.join('\n'));
+                }
             }
             const applied = await getAppliedMigrations(client);
             const appliedNames = new Set(applied.map((m) => m.name));
@@ -277,7 +332,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
                 try {
                     await client.query('BEGIN');
                     await client.query(up);
-                    await client.query(`INSERT INTO ${TRACKING_TABLE} (name, checksum) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [file.name, hash]);
+                    await client.query(`INSERT INTO ${QUOTED_TRACKING_TABLE} (name, checksum) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [file.name, hash]);
                     await client.query('COMMIT');
                     results.push(file);
                 }
@@ -313,13 +368,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
     try {
         const gotLock = await acquireLock(client);
         if (!gotLock) {
-            return {
-                rolledBack: [],
-                errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
         try {
             await ensureTrackingTable(client);
@@ -337,7 +386,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
                 const file = fileMap.get(migration.name);
                 if (!file) {
                     errors.push({
-                        file: { filename: migration.name + '.sql', path: '', name: migration.name, timestamp: '' },
+                        file: { filename: `${migration.name}.sql`, path: '', name: migration.name, timestamp: '' },
                         error: `Migration file not found for "${migration.name}"`,
                     });
                     continue;
@@ -350,7 +399,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
                 try {
                     await client.query('BEGIN');
                     await client.query(down);
-                    await client.query(`DELETE FROM ${TRACKING_TABLE} WHERE name = $1`, [migration.name]);
+                    await client.query(`DELETE FROM ${QUOTED_TRACKING_TABLE} WHERE name = $1`, [migration.name]);
                     await client.query('COMMIT');
                     results.push(file);
                 }

package/dist/cli/ui.d.ts

@@ -34,7 +34,7 @@ export declare const symbols: {
     readonly warning: "⚠" | "!";
     readonly dot: "." | "∙";
     readonly line: "─" | "-";
-    readonly vertLine: "│" | "|";
+    readonly vertLine: "|" | "│";
     readonly topLeft: "╭" | "+";
     readonly topRight: "+" | "╮";
     readonly bottomLeft: "+" | "╰";

package/dist/cli/ui.js

@@ -7,9 +7,7 @@
 // ---------------------------------------------------------------------------
 // ANSI escape codes
 // ---------------------------------------------------------------------------
-const isColorSupported = process.env['NO_COLOR'] == null &&
-    process.env['TERM'] !== 'dumb' &&
-    (process.stdout.isTTY ?? false);
+const isColorSupported = process.env.NO_COLOR == null && process.env.TERM !== 'dumb' && (process.stdout.isTTY ?? false);
 function code(open, close) {
     if (!isColorSupported)
         return (s) => s;
@@ -96,9 +94,7 @@ export function table(headers, rows) {
         return ` ${bold(h)}${' '.repeat(Math.max(0, w - stripAnsi(h).length))} `;
     })
         .join(dim(symbols.vertLine));
-    const separator = colWidths
-        .map((w) => symbols.line.repeat(w + 2))
-        .join(dim(symbols.line));
+    const separator = colWidths.map((w) => symbols.line.repeat(w + 2)).join(dim(symbols.line));
     const bodyLines = rows.map((row) => row
         .map((cell, i) => {
         const w = colWidths[i];
@@ -177,7 +173,7 @@ export function info(msg) {
     console.log(`  ${blue(symbols.info)} ${msg}`);
 }
 export function label(key, value) {
-    console.log(`  ${dim(key + ':')} ${value}`);
+    console.log(`  ${dim(`${key}:`)} ${value}`);
 }
 export function newline() {
     console.log('');
@@ -191,7 +187,7 @@ export function divider() {
 // ---------------------------------------------------------------------------
 export function banner() {
     console.log('');
-    console.log(`  ${bold(cyan('turbine'))} ${dim('by')} ${bold('BataData')}`);
+    console.log(`  ${bold(cyan('turbine-orm'))}`);
     console.log(`  ${dim('TypeScript ORM with json_agg nested queries')}`);
     console.log('');
 }
@@ -208,7 +204,7 @@ export function elapsed(startMs) {
 // Strip ANSI codes (for width calculation)
 // ---------------------------------------------------------------------------
 export function stripAnsi(s) {
-    // eslint-disable-next-line no-control-regex
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape codes require control characters
     return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
 // ---------------------------------------------------------------------------

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * @batadata/turbine — TurbineClient
+ * turbine-orm — TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -16,16 +16,70 @@
  * const user = await db.users.findUnique({ where: { id: 1 } });
  *
  * // With base client (dynamic):
- * import { TurbineClient } from '@batadata/turbine';
+ * import { TurbineClient } from 'turbine-orm';
  * const db = new TurbineClient({ connectionString: '...' }, schema);
  * const users = db.table<User>('users');
  * ```
  */
 import pg from 'pg';
-import { QueryInterface, type DeferredQuery, type QueryInterfaceOptions } from './query.js';
+import { type ErrorMessageMode } from './errors.js';
 import { type PipelineResults } from './pipeline.js';
+import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query.js';
 import type { SchemaMetadata } from './schema.js';
+/**
+ * Minimal pg-compatible query result.
+ * `pg.Pool`, `@neondatabase/serverless` Pool, `@vercel/postgres` Pool and
+ * any driver speaking the node-postgres API all satisfy this shape.
+ */
+export interface PgCompatQueryResult<R = Record<string, unknown>> {
+    rows: R[];
+    rowCount: number | null;
+    fields?: Array<{
+        name: string;
+        dataTypeID: number;
+    }>;
+}
+/**
+ * Minimal pg-compatible client used by TurbineClient for transactions.
+ * `pg.PoolClient` satisfies this; so do Neon and Vercel's equivalents.
+ */
+export interface PgCompatPoolClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    release(err?: Error | boolean): void;
+}
+/**
+ * Minimal pg-compatible pool. Pass any driver that satisfies this interface
+ * via `TurbineConfig.pool` — lets Turbine run on Neon HTTP, Vercel Postgres,
+ * Cloudflare Hyperdrive, or any other serverless Postgres driver.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { TurbineClient } from 'turbine-orm';
+ *
+ * const neonPool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = new TurbineClient({ pool: neonPool }, schema);
+ * ```
+ */
+export interface PgCompatPool {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+    /** Optional — pools that expose stats (pg.Pool does; Neon HTTP does not) */
+    readonly totalCount?: number;
+    readonly idleCount?: number;
+    readonly waitingCount?: number;
+    /** Optional — pg.Pool supports 'error' event; HTTP drivers typically do not */
+    on?(event: 'error', listener: (err: Error) => void): this;
+}
 export interface TurbineConfig {
+    /**
+     * An external pg-compatible pool. Use this to plug in serverless drivers
+     * like `@neondatabase/serverless`, `@vercel/postgres`, or any other pg-API
+     * compatible pool. When provided, all connection-string fields are ignored
+     * and Turbine will NOT create its own pg.Pool.
+     */
+    pool?: PgCompatPool;
     /** Postgres connection string (e.g. postgres://user:pass@host:5432/db) */
     connectionString?: string;
     /** Host (used if connectionString is not set) */
@@ -38,6 +92,13 @@ export interface TurbineConfig {
     user?: string;
     /** Password */
     password?: string;
+    /** SSL/TLS options for the connection (required for most cloud providers) */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+        key?: string;
+        cert?: string;
+    };
     /** Maximum number of connections in the pool (default: 10) */
     poolSize?: number;
     /** Idle timeout in ms before a connection is closed (default: 30000) */
@@ -50,6 +111,20 @@ export interface TurbineConfig {
     defaultLimit?: number;
     /** Log a warning when findMany() is called without a limit (default: false) */
     warnOnUnlimited?: boolean;
+    /**
+     * Controls how `NotFoundError` (and other where-aware errors) format their
+     * messages.
+     *
+     *   - `'safe'`    (default): the message includes only the keys of the where
+     *     clause (e.g. `where: { id, email }`). Values are redacted to avoid
+     *     leaking PII into error logs (Sentry, Datadog, etc.).
+     *   - `'verbose'`: the message includes the full JSON-serialized where
+     *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+     *
+     * The full `where` object is always available as `err.where` for
+     * programmatic access regardless of mode.
+     */
+    errorMessages?: ErrorMessageMode;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {
@@ -101,6 +176,10 @@ export declare class TransactionClient {
      * Create a pool-like wrapper around the transaction client.
      * This allows QueryInterface to work with the transaction connection
      * without knowing it's in a transaction.
+     *
+     * pg driver errors thrown by queries are translated into typed Turbine
+     * errors via wrapPgError so transaction-scoped queries surface the same
+     * typed errors as pool-scoped queries.
      */
     private createTxPool;
 }
@@ -109,10 +188,13 @@ export declare class TurbineClient {
     readonly pool: pg.Pool;
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
+    private static int8ParserRegistered;
     private readonly logging;
     private readonly tableCache;
     private readonly middlewares;
     private readonly queryOptions;
+    /** True when Turbine created the pool and is responsible for tearing it down */
+    private readonly ownsPool;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
      * Register a middleware function that runs before/after every query.
@@ -209,11 +291,17 @@ export declare class TurbineClient {
     connect(): Promise<void>;
     /**
      * Gracefully shut down the connection pool.
+     *
+     * If Turbine was given an external pool via `TurbineConfig.pool`, this
+     * method is a no-op — the caller is responsible for the pool's lifecycle.
      */
     disconnect(): Promise<void>;
     /** Alias for disconnect() */
     end(): Promise<void>;
-    /** Pool statistics for monitoring. */
+    /**
+     * Pool statistics for monitoring. Returns zeros for pools that don't
+     * expose connection counts (e.g., stateless HTTP drivers like Neon).
+     */
     get stats(): {
         totalCount: number;
         idleCount: number;