turbine-orm 0.7.0 → 0.7.1

package/README.md

@@ -147,6 +147,30 @@ const deleted = await db.users.delete({
 });
 ```
 
+### Atomic update operators
+
+For race-free counter updates, pass an operator object instead of a literal. Turbine generates `col = col + $n` style SQL so concurrent updates are safe.
+
+```typescript
+// Atomic increment — no read-modify-write race
+await db.posts.update({
+  where: { id: 1 },
+  data: { viewCount: { increment: 1 } },
+});
+
+// Other supported operators on numeric columns
+await db.posts.update({
+  where: { id: 1 },
+  data: {
+    viewCount:  { increment: 5 },
+    likesCount: { decrement: 1 },
+    score:      { multiply: 2 },
+    rank:       { divide: 2 },
+    title:      { set: 'New title' }, // explicit set, equivalent to a literal
+  },
+});
+```
+
 ### Transactions
 
 ```typescript
@@ -273,6 +297,73 @@ try {
 
 Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation).
 
+## WHERE Operator Reference
+
+Every operator supported by the `where` clause. Operators compose freely with `AND`, `OR`, `NOT`, and the relation filters `some` / `every` / `none`.
+
+### Equality
+
+| Operator | Description | Example |
+|---|---|---|
+| literal | Implicit equality | `where: { email: 'a@b.com' }` |
+| `equals` | Explicit equality | `where: { email: { equals: 'a@b.com' } }` |
+| `not` | Inequality (or `not: null` for `IS NOT NULL`) | `where: { role: { not: 'admin' } }` |
+
+### Sets
+
+| Operator | Description | Example |
+|---|---|---|
+| `in` | Match any value in the array | `where: { id: { in: [1, 2, 3] } }` |
+| `notIn` | Match none of the values in the array | `where: { role: { notIn: ['banned', 'spam'] } }` |
+
+### Comparison
+
+| Operator | Description | Example |
+|---|---|---|
+| `gt` | Greater than | `where: { score: { gt: 100 } }` |
+| `gte` | Greater than or equal | `where: { score: { gte: 100 } }` |
+| `lt` | Less than | `where: { score: { lt: 100 } }` |
+| `lte` | Less than or equal | `where: { score: { lte: 100 } }` |
+
+### String
+
+| Operator | Description | Example |
+|---|---|---|
+| `contains` | Substring match (`LIKE %v%`) | `where: { title: { contains: 'sql' } }` |
+| `startsWith` | Prefix match (`LIKE v%`) | `where: { email: { startsWith: 'admin@' } }` |
+| `endsWith` | Suffix match (`LIKE %v`) | `where: { email: { endsWith: '@acme.com' } }` |
+| `mode: 'insensitive'` | Switch any string operator to `ILIKE` | `where: { title: { contains: 'SQL', mode: 'insensitive' } }` |
+
+LIKE wildcards in user input are escaped automatically — `%`, `_`, and `\` are treated as literals.
+
+### Relation filters
+
+Filter parent rows by predicates against their related child rows. Available on `hasMany` and `hasOne` relations.
+
+| Operator | Description | Example |
+|---|---|---|
+| `some` | At least one related row matches | `where: { posts: { some: { published: true } } }` |
+| `every` | Every related row matches | `where: { posts: { every: { published: true } } }` |
+| `none` | No related row matches | `where: { posts: { none: { published: false } } }` |
+
+### Array columns
+
+Operators for Postgres array columns (`text[]`, `int[]`, etc.).
+
+| Operator | Description | Example |
+|---|---|---|
+| `has` | Array contains the given element | `where: { tags: { has: 'sql' } }` |
+| `hasEvery` | Array contains every element in the list | `where: { tags: { hasEvery: ['sql', 'postgres'] } }` |
+| `hasSome` | Array contains at least one element from the list | `where: { tags: { hasSome: ['sql', 'mysql'] } }` |
+
+### Combinators
+
+| Operator | Description | Example |
+|---|---|---|
+| `AND` | All sub-clauses must match | `where: { AND: [{ orgId: 1 }, { role: 'admin' }] }` |
+| `OR` | Any sub-clause matches | `where: { OR: [{ role: 'admin' }, { role: 'owner' }] }` |
+| `NOT` | Negate a sub-clause | `where: { NOT: { role: 'banned' } }` |
+
 ## CLI
 
 ```
@@ -492,7 +583,6 @@ All three ORMs now use single-query approaches for nested relations. Turbine use
 Turbine is focused and opinionated. Here's what it doesn't do:
 
 - **PostgreSQL only.** No MySQL, SQLite, or MSSQL. This is by design — the `json_agg` approach is PostgreSQL-specific, and going deep on one database enables the performance advantage.
-- **No incremental updates.** Prisma's `{ count: { increment: 1 } }` syntax is not yet supported. Use raw SQL for atomic increments.
 - **No full-text search operators.** TSVECTOR/TSQUERY are not exposed in the query builder. Use `db.raw` for full-text queries.
 - **Large nested result sets.** `json_agg` builds the entire JSON array in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause to cap the aggregation size.
 - **No admin UI.** Turbine Studio is planned but not yet available.
@@ -500,6 +590,14 @@ Turbine is focused and opinionated. Here's what it doesn't do:
 ## Examples
 
 - **[Next.js](./examples/nextjs/)** — Server-rendered app with nested relations, streaming, and live code demos
+- **[Neon Edge](./examples/neon-edge/)** — Vercel Edge route handler talking to Neon over HTTP via `@neondatabase/serverless`
+- **[Vercel Postgres](./examples/vercel-postgres/)** — Next.js app router route handler on `@vercel/postgres`
+- **[Cloudflare Worker](./examples/cloudflare-worker/)** — Worker `fetch` handler with `pg` over Cloudflare Hyperdrive
+- **[Supabase](./examples/supabase/)** — Standalone script over the standard `pg` driver against Supabase
+
+## Guides
+
+- **[Migrating from Prisma](./docs/migrate-from-prisma.md)** — API mapping table, side-by-side `findMany`, and notes on the differences
 
 ## Requirements
 

package/dist/cjs/cli/index.js

@@ -61,6 +61,7 @@ const generate_js_1 = require("../generate.js");
 const introspect_js_1 = require("../introspect.js");
 const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
+const loader_js_1 = require("./loader.js");
 const migrate_js_1 = require("./migrate.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
@@ -113,6 +114,9 @@ function parseArgs() {
             case '--auto':
                 result.auto = true;
                 break;
+            case '--allow-drift':
+                result.allowDrift = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -135,6 +139,36 @@ function parseArgs() {
     return result;
 }
 // ---------------------------------------------------------------------------
+// TypeScript loader — user-facing error helper
+// ---------------------------------------------------------------------------
+/**
+ * Print a friendly error explaining how to install tsx, then exit.
+ * Called when we know we need to load a `.ts` file but the loader isn't available.
+ */
+function failMissingTsLoader(filePath, reason) {
+    (0, ui_js_1.newline)();
+    (0, ui_js_1.error)(`Cannot load TypeScript file: ${filePath}`);
+    (0, ui_js_1.newline)();
+    if (reason === 'unsupported') {
+        console.log(`  ${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
+        console.log(`  ${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
+    }
+    else {
+        console.log(`  ${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Install it as a dev dependency:')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        console.log(`    ${(0, ui_js_1.dim)('or')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('pnpm add -D tsx')}`);
+        console.log(`    ${(0, ui_js_1.dim)('or')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('yarn add -D tsx')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Alternatively, rename your file to')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('or')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+    }
+    (0, ui_js_1.newline)();
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function requireUrl(config) {
@@ -157,6 +191,15 @@ async function loadSchemaFile(schemaFile) {
         console.log(`  ${(0, ui_js_1.dim)('Create one with:')} ${(0, ui_js_1.cyan)('turbine init')}`);
         process.exit(1);
     }
+    // If this is a TypeScript file, ensure the tsx ESM loader is registered
+    // before we attempt the dynamic import. Without this, Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    if ((0, loader_js_1.needsTsLoader)(absPath)) {
+        const status = await (0, loader_js_1.registerTsLoader)();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(schemaFile, status);
+        }
+    }
     try {
         const fileUrl = (0, node_url_1.pathToFileURL)(absPath).href;
         const mod = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
@@ -171,6 +214,11 @@ async function loadSchemaFile(schemaFile) {
         (0, ui_js_1.error)(`Failed to load schema file: ${schemaFile}`);
         if (err instanceof Error) {
             console.log(`  ${(0, ui_js_1.dim)(err.message)}`);
+            // If the error is the classic ERR_UNKNOWN_FILE_EXTENSION, give a hint.
+            if (err.message.includes('ERR_UNKNOWN_FILE_EXTENSION') || err.message.includes('Unknown file extension')) {
+                (0, ui_js_1.newline)();
+                console.log(`  ${(0, ui_js_1.dim)('Hint: install')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to load .ts files:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+            }
         }
         process.exit(1);
     }
@@ -521,9 +569,10 @@ async function cmdMigrate(args, config) {
         console.log(`    ${(0, ui_js_1.cyan)('status')}                Show migration status`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('--auto')}         Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${(0, ui_js_1.cyan)('--step, -n')}     Number of migrations to apply/rollback`);
-        console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}      Show SQL without executing`);
+        console.log(`    ${(0, ui_js_1.cyan)('--auto')}           Auto-generate UP/DOWN SQL from schema diff`);
+        console.log(`    ${(0, ui_js_1.cyan)('--step, -n')}       Number of migrations to apply/rollback`);
+        console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}        Show SQL without executing`);
+        console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}    Bypass checksum validation on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate create add_users_table')}`);
@@ -639,9 +688,18 @@ async function cmdMigrateUp(args, config) {
         (0, ui_js_1.newline)();
         return;
     }
+    // Big, loud warning when bypassing drift detection — this is a deliberately
+    // dangerous operation and the user should see it on every invocation.
+    if (args.allowDrift) {
+        (0, ui_js_1.warn)('--allow-drift is set — checksum validation is DISABLED for this run.');
+        console.log(`  ${(0, ui_js_1.dim)('Applied migrations may have been modified or deleted on disk.')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Proceed only if you are intentionally rewriting migration history.')}`);
+        (0, ui_js_1.newline)();
+    }
     const spinner = new ui_js_1.Spinner('Applying migrations').start();
     const result = await (0, migrate_js_1.migrateUp)(url, config.migrationsDir, {
         step: args.step,
+        allowDrift: args.allowDrift,
     });
     if (result.applied.length === 0 && result.errors.length === 0) {
         spinner.succeed('All migrations are up to date');
@@ -970,6 +1028,7 @@ function showMigrateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
     console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}    Number of migrations to apply/rollback`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}      Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}      Show detailed output`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
@@ -1078,6 +1137,16 @@ async function main() {
         showVersion();
         return;
     }
+    // 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`.
+    const configPath = (0, config_js_1.findConfigFile)();
+    if ((0, loader_js_1.needsTsLoader)(configPath)) {
+        const status = await (0, loader_js_1.registerTsLoader)();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
+        }
+    }
     // Load config file
     let fileConfig = {};
     try {

package/dist/cjs/cli/loader.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.needsTsLoader = needsTsLoader;
+exports.canResolveTsx = canResolveTsx;
+exports.registerTsLoader = registerTsLoader;
+exports._resetTsLoaderStateForTests = _resetTsLoaderStateForTests;
+const node_module_1 = require("node:module");
+const node_url_1 = require("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.
+ */
+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.
+ */
+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 = (0, node_module_1.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
+ */
+async function registerTsLoader() {
+    if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
+        return 'already';
+    }
+    if (!canResolveTsx()) {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('node:module')));
+        const register = mod.register;
+        if (typeof register !== 'function') {
+            tsLoaderState = 'unsupported';
+            return 'unsupported';
+        }
+        register('tsx/esm', (0, node_url_1.pathToFileURL)(`${process.cwd()}/`));
+        tsLoaderState = 'registered';
+        return 'registered';
+    }
+    catch {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+}
+/** Reset the loader state — used by unit tests only. */
+function _resetTsLoaderStateForTests() {
+    tsLoaderState = null;
+}

package/dist/cjs/cli/migrate.js

@@ -276,12 +276,19 @@ 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`).
  */
 async function migrateUp(connectionString, migrationsDir, options) {
     const client = new pg_1.default.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);
@@ -290,18 +297,35 @@ async function migrateUp(connectionString, migrationsDir, options) {
         }
         try {
             await ensureTrackingTable(client);
-            // Validate checksums of already-applied migrations (skip with --force)
-            if (!options?.force) {
+            // 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 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 errors_js_1.MigrationError(`[turbine] Migration integrity check failed — ${parts.join('; ')}. Applied migrations should be immutable. Use --force to skip this check.`);
+                    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 errors_js_1.MigrationError(lines.join('\n'));
                 }
             }
             const applied = await getAppliedMigrations(client);

package/dist/cjs/client.js

@@ -195,6 +195,11 @@ class TurbineClient {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
         };
+        // Apply NotFoundError message redaction mode (default: safe — values are
+        // stripped from messages to avoid leaking PII into error logs).
+        if (config.errorMessages) {
+            (0, errors_js_1.setErrorMessageMode)(config.errorMessages);
+        }
         if (config.pool) {
             // External pool — use directly. Turbine doesn't manage its lifecycle.
             this.pool = config.pool;
@@ -399,6 +404,24 @@ class TurbineClient {
     async $transaction(fn, options) {
         const client = await this.pool.connect();
         const timeout = options?.timeout;
+        /**
+         * Track whether the connection has already been released so the finally
+         * block doesn't double-release. When a timeout fires we destroy the
+         * connection eagerly to abort the in-flight backend query.
+         */
+        let released = false;
+        const releaseOnce = (err) => {
+            if (released)
+                return;
+            released = true;
+            try {
+                client.release(err);
+            }
+            catch {
+                // pg may throw if the client is already released — swallow.
+            }
+        };
+        let timedOut = false;
         try {
             // BEGIN with optional isolation level
             let beginSQL = 'BEGIN';
@@ -422,10 +445,22 @@ class TurbineClient {
             }
             let result;
             if (timeout) {
-                // Race between the function and a timeout
+                // Race between the function and a timeout. If the timeout fires we
+                // need to actually abort the in-flight query — otherwise the backend
+                // keeps running until pg's own timeout, holding a pool slot the whole
+                // time. The simplest reliable cancellation is to destroy the
+                // connection: passing a truthy argument to client.release() tells the
+                // pg pool to discard the client (its socket is closed, which causes
+                // Postgres to abort the active query and roll back the transaction).
+                // The pool will spin up a fresh connection on the next checkout.
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
+                        timedOut = true;
+                        // Destroy the connection to abort the in-flight backend query.
+                        // We do this BEFORE rejecting so the socket is gone by the time
+                        // the caller's catch block runs.
+                        releaseOnce(new Error('[turbine] Transaction timeout — connection destroyed'));
                         reject(new errors_js_1.TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
@@ -446,14 +481,25 @@ class TurbineClient {
             return result;
         }
         catch (err) {
-            await client.query('ROLLBACK');
+            // If the timeout fired we already destroyed the connection — issuing a
+            // ROLLBACK on a released client would throw "Client has already been
+            // released". Skip the rollback in that case (the backend rolled back
+            // when its socket was closed).
+            if (!timedOut && !released) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             if (this.logging) {
                 console.log('[turbine] Transaction rolled back');
             }
             throw err;
         }
         finally {
-            client.release();
+            releaseOnce();
         }
     }
     // -------------------------------------------------------------------------