turbine-orm 0.5.0 → 0.7.0

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',
             });
         }
     }
@@ -235,27 +270,23 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         // 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 (skip with --force)
+            if (!options?.force) {
+                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 parts = [];
+                    if (modified.length > 0)
+                        parts.push(`modified: ${modified.map((m) => m.name).join(', ')}`);
+                    if (missing.length > 0)
+                        parts.push(`deleted: ${missing.map((m) => m.name).join(', ')}`);
+                    throw new MigrationError(`[turbine] Migration integrity check failed — ${parts.join('; ')}. Applied migrations should be immutable. Use --force to skip this check.`);
+                }
             }
             const applied = await getAppliedMigrations(client);
             const appliedNames = new Set(applied.map((m) => m.name));
@@ -277,7 +308,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 +344,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 +362,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 +375,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.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,69 @@
  * 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 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 +91,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) */
@@ -101,6 +161,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 +173,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 +276,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;

package/dist/client.js

@@ -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,28 +16,15 @@
  * 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 } from './query.js';
+import { TimeoutError, wrapPgError } from './errors.js';
 import { executePipeline } from './pipeline.js';
-/**
- * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
- * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
- *
- * NOTE: For values exceeding Number.MAX_SAFE_INTEGER, the parser falls back
- * to returning the raw string to avoid precision loss. The generated TypeScript
- * type maps int8/bigint to `number`, which is correct for the vast majority of
- * use cases (IDs, counts, timestamps). If you store values > 2^53 - 1 in a
- * bigint column, the runtime return type will be `string` for those rows.
- */
-pg.types.setTypeParser(20, (val) => {
-    const n = Number(val);
-    return Number.isSafeInteger(n) ? n : val; // fall back to string for huge values
-});
+import { QueryInterface } from './query.js';
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',
@@ -119,20 +106,36 @@ export class TransactionClient {
                 sql += `$${i + 1}`;
             }
         });
-        const result = await this.client.query(sql, values);
-        return result.rows;
+        try {
+            const result = await this.client.query(sql, values);
+            return result.rows;
+        }
+        catch (err) {
+            throw wrapPgError(err);
+        }
     }
     /**
      * 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.
      */
     createTxPool() {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
         return {
-            query: (text, values) => client.query(text, values),
+            query: async (text, values) => {
+                try {
+                    return await client.query(text, values);
+                }
+                catch (err) {
+                    throw wrapPgError(err);
+                }
+            },
             connect: () => Promise.resolve(client),
         };
     }
@@ -145,38 +148,81 @@ export class TurbineClient {
     pool;
     /** The schema metadata this client was built from */
     schema;
+    static int8ParserRegistered = false;
     logging;
     tableCache = new Map();
     middlewares = [];
     queryOptions;
+    /** True when Turbine created the pool and is responsible for tearing it down */
+    ownsPool = true;
     constructor(config = {}, schema) {
+        /**
+         * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
+         * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
+         *
+         * NOTE: For values exceeding Number.MAX_SAFE_INTEGER, the parser falls back
+         * to returning the raw string to avoid precision loss. The generated TypeScript
+         * type maps int8/bigint to `number`, which is correct for the vast majority of
+         * use cases (IDs, counts, timestamps). If you store values > 2^53 - 1 in a
+         * bigint column, the runtime return type will be `string` for those rows.
+         *
+         * NOTE: We intentionally do NOT register a parser for numeric (OID 1700).
+         * Postgres numeric is arbitrary-precision, so the default pg driver behavior
+         * of returning a string is correct and matches the generated TypeScript type
+         * (numeric → string). Users who want number can cast explicitly in SQL.
+         */
+        // Only register the int8 parser when we own the pg driver. External
+        // pools (Neon HTTP, Vercel Postgres) may ship their own pg-types fork
+        // and rely on their own parser configuration — don't mutate global state
+        // we don't own.
+        if (!config.pool && !TurbineClient.int8ParserRegistered) {
+            pg.types.setTypeParser(20, (val) => {
+                const n = Number(val);
+                return Number.isSafeInteger(n) ? n : val;
+            });
+            TurbineClient.int8ParserRegistered = true;
+        }
         this.logging = config.logging ?? false;
         this.schema = schema;
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
         };
-        const poolConfig = {
-            max: config.poolSize ?? 10,
-            idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
-            connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
-        };
-        if (config.connectionString) {
-            poolConfig.connectionString = config.connectionString;
+        if (config.pool) {
+            // External pool — use directly. Turbine doesn't manage its lifecycle.
+            this.pool = config.pool;
+            this.ownsPool = false;
+            if (this.logging) {
+                console.log(`[turbine] Using external pool — ${Object.keys(schema.tables).length} tables`);
+            }
         }
         else {
-            poolConfig.host = config.host ?? 'localhost';
-            poolConfig.port = config.port ?? 5432;
-            poolConfig.database = config.database ?? 'postgres';
-            poolConfig.user = config.user ?? 'postgres';
-            poolConfig.password = config.password;
-        }
-        this.pool = new pg.Pool(poolConfig);
-        this.pool.on('error', (err) => {
-            console.error('[turbine] Unexpected pool error:', err.message);
-        });
-        if (this.logging) {
-            console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+            const poolConfig = {
+                max: config.poolSize ?? 10,
+                idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
+                connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
+            };
+            if (config.connectionString) {
+                poolConfig.connectionString = config.connectionString;
+            }
+            else {
+                poolConfig.host = config.host ?? 'localhost';
+                poolConfig.port = config.port ?? 5432;
+                poolConfig.database = config.database ?? 'postgres';
+                poolConfig.user = config.user ?? 'postgres';
+                poolConfig.password = config.password;
+            }
+            if (config.ssl !== undefined) {
+                poolConfig.ssl = config.ssl;
+            }
+            this.pool = new pg.Pool(poolConfig);
+            this.ownsPool = true;
+            this.pool.on('error', (err) => {
+                console.error('[turbine] Unexpected pool error:', err.message);
+            });
+            if (this.logging) {
+                console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+            }
         }
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -283,8 +329,13 @@ export class TurbineClient {
         if (this.logging) {
             console.log(`[turbine] Raw SQL: ${sql.trim().substring(0, 120)}...`);
         }
-        const result = await this.pool.query(sql, values);
-        return result.rows;
+        try {
+            const result = await this.pool.query(sql, values);
+            return result.rows;
+        }
+        catch (err) {
+            throw wrapPgError(err);
+        }
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
@@ -368,7 +419,7 @@ export class TurbineClient {
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
-                        reject(new Error(`[turbine] Transaction timed out after ${timeout}ms`));
+                        reject(new TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
                 try {
@@ -419,8 +470,17 @@ export class TurbineClient {
     }
     /**
      * 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.
      */
     async disconnect() {
+        if (!this.ownsPool) {
+            if (this.logging) {
+                console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');
+            }
+            return;
+        }
         await this.pool.end();
         if (this.logging) {
             console.log('[turbine] Pool disconnected');
@@ -430,12 +490,15 @@ export class TurbineClient {
     async end() {
         return this.disconnect();
     }
-    /** 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() {
         return {
-            totalCount: this.pool.totalCount,
-            idleCount: this.pool.idleCount,
-            waitingCount: this.pool.waitingCount,
+            totalCount: this.pool.totalCount ?? 0,
+            idleCount: this.pool.idleCount ?? 0,
+            waitingCount: this.pool.waitingCount ?? 0,
         };
     }
 }