@pineliner/odb-client 1.1.4 → 1.2.0

package/src/core/client.ts

@@ -1,5 +1,5 @@
 import type { ODBLiteConfig, ODBLiteConnection, QueryResult, Transaction, TransactionCallback, TransactionMode, SQLFragment } from '../types.ts';
-import { HTTPClient } from './http-client.ts';
+import { HTTPClient, type QueryRequestOptions } from './http-client.ts';
 import { SQLParser } from './sql-parser.ts';
 import { createBatchTransaction, createSimpleTransaction, SimpleTransaction } from './transaction.ts';
 import { ConnectionError } from '../types.ts';
@@ -22,10 +22,10 @@ interface SQLFunction {
   identifier(name: string): string;
 
   // Additional postgres.js-like methods
-  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+  query<T = any>(sql: string, params?: any[], opts?: QueryRequestOptions): Promise<QueryResult<T>>;
 
   // libsql-compatible execute method (for backward compatibility)
-  execute<T = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<T>>;
+  execute<T = any>(sql: string | { sql: string; args?: any[] }, args?: any[], opts?: QueryRequestOptions): Promise<QueryResult<T>>;
 
   // Batch execution - runs multiple statements on same connection (for transactions)
   batch<T = any>(statements: Array<{ sql: string; params?: any[] }>): Promise<BatchResult<T>>;
@@ -59,6 +59,12 @@ export class ODBLiteClient implements ODBLiteConnection {
       // Handle template string queries (returns Promise)
       if (Array.isArray(sql) && (('raw' in sql) || (typeof sql[0] === 'string' && values.length >= 0))) {
         const parsed = SQLParser.parse(sql, values);
+        // NOTE: this raw template path sends NO transaction token. The router pins
+        // a transaction's statements by txId, so do NOT use `client.sql`...`` (or
+        // ODBLiteClient.query) for statements inside a router-pinned transaction —
+        // they'd be sent tokenless and treated as foreign work (deadlock-until-
+        // watchdog). The DB adapter (ODBLiteConnection) goes through sql.execute()
+        // with opts, which carries the token; use the connection, not the raw client.
         return this.httpClient.query<T>(parsed.sql, parsed.params);
       }
 
@@ -75,16 +81,16 @@ export class ODBLiteClient implements ODBLiteConnection {
     sqlFunction.identifier = (name: string): string => SQLParser.identifier(name);
 
     // Attach client methods to the function
-    sqlFunction.query = async <T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> => {
-      return await this.httpClient.query<T>(sql, params);
+    sqlFunction.query = async <T = any>(sql: string, params: any[] = [], opts?: QueryRequestOptions): Promise<QueryResult<T>> => {
+      return await this.httpClient.query<T>(sql, params, opts);
     };
 
     // libsql-compatible execute method (for backward compatibility)
-    sqlFunction.execute = async <T = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<T>> => {
+    sqlFunction.execute = async <T = any>(sql: string | { sql: string; args?: any[] }, args?: any[], opts?: QueryRequestOptions): Promise<QueryResult<T>> => {
       if (typeof sql === 'string') {
-        return await this.httpClient.query<T>(sql, args || []);
+        return await this.httpClient.query<T>(sql, args || [], opts);
       } else {
-        return await this.httpClient.query<T>(sql.sql, sql.args || []);
+        return await this.httpClient.query<T>(sql.sql, sql.args || [], opts);
       }
     };
 

package/src/core/http-client.ts

@@ -1,6 +1,14 @@
 import type { ODBLiteConfig, ODBLiteResponse, QueryResult } from '../types.ts'
 import { ConnectionError, QueryError } from '../types.ts'
 
+/** Per-request options for a single query. */
+export interface QueryRequestOptions {
+  /** Transaction/session token tying this statement to a server-pinned connection. */
+  txId?: string
+  /** Override the client's retry count (transaction statements pass 1 = no retry). */
+  maxRetries?: number
+}
+
 /**
  * HTTP client for communicating with ODBLite service
  */
@@ -23,7 +31,7 @@ export class HTTPClient {
   /**
    * Execute a query against the ODBLite service
    */
-  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
+  async query<T = any>(sql: string, params: any[] = [], opts?: QueryRequestOptions): Promise<QueryResult<T>> {
     if (!this.config.databaseId) {
       throw new ConnectionError('No database ID configured. Use setDatabase() first.')
     }
@@ -31,7 +39,10 @@ export class HTTPClient {
     const url = `${this.config.baseUrl}/query/${this.config.databaseId}`
     const body = {
       sql,
-      params
+      params,
+      // Transaction/session token — present for every statement inside a
+      // connection.transaction() so the router pins them to one connection.
+      ...(opts?.txId ? { txId: opts.txId } : {})
     }
 
     try {
@@ -42,7 +53,7 @@ export class HTTPClient {
           Authorization: `Bearer ${this.config.apiKey}`
         },
         body: JSON.stringify(body)
-      })
+      }, opts?.maxRetries)
 
       const data: ODBLiteResponse<T> = await response.json()
 
@@ -186,10 +197,14 @@ export class HTTPClient {
   /**
    * Make HTTP request with retry logic
    */
-  private async makeRequest(url: string, options: RequestInit): Promise<Response> {
+  private async makeRequest(url: string, options: RequestInit, maxRetries?: number): Promise<Response> {
     let lastError: Error | undefined
+    // Transaction-control and in-transaction statements pass maxRetries=1: they
+    // are NOT idempotent (a retried COMMIT/INSERT could double-apply or hit a
+    // closed transaction), so they must never be auto-retried.
+    const retries = maxRetries ?? this.config.retries ?? 3
 
-    for (let attempt = 1; attempt <= (this.config.retries || 3); attempt++) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
       try {
         const controller = new AbortController()
         const timeoutId = setTimeout(() => controller.abort(), this.config.timeout)
@@ -224,14 +239,14 @@ export class HTTPClient {
         }
 
         // Wait before retry (exponential backoff)
-        if (attempt < (this.config.retries || 3)) {
+        if (attempt < retries) {
           const delay = Math.min(1000 * 2 ** (attempt - 1), 10000)
           await new Promise((resolve) => setTimeout(resolve, delay))
         }
       }
     }
 
-    throw new ConnectionError(`Failed after ${this.config.retries} attempts: ${lastError?.message}`, lastError)
+    throw new ConnectionError(`Failed after ${retries} attempts: ${lastError?.message}`, lastError)
   }
 
   /**

package/src/database/adapters/odblite-socket.ts

@@ -0,0 +1,255 @@
+import type { BackendType, Connection, DatabaseAdapter, PreparedStatement, QueryResult } from '../types'
+import { ODBLiteAdapter } from './odblite'
+import { SocketClient, type SocketTarget } from './socket/client'
+import {
+  toHrana,
+  fromHrana,
+  toBatch,
+  type AtomicStep,
+  type BatchResult,
+  type StmtResult,
+  type StreamRequest,
+  type StreamResult,
+} from './socket/protocol'
+
+/**
+ * odblite-socket — the FAST cross-process backend: raw socket + JSON framing to
+ * router_v2 (bun:sqlite engine). REPLACES the HTTP `odblite` backend (one hop, no
+ * HTTP parse) — it does NOT layer on it. Same `Connection` interface, so it's a
+ * drop-in: app-router flips `backend: 'odblite'` → `'odblite-socket'`.
+ *
+ * Write discipline (the separate-process model forces it): a unit of write work
+ * is ONE batch in ONE round-trip — the server runs BEGIN…COMMIT on its side, the
+ * client never holds the write slot across the wire. So `atomic(steps)` is the
+ * write primitive; `transaction(fn)` BUFFERS writes and flushes them as one
+ * atomic batch on commit (no read-your-own-uncommitted-writes mid-tx — that would
+ * re-create the slot-starvation the design avoids). Read-compute-write → read
+ * first, compute, write one atomic().
+ */
+function toQueryResult(res: StreamResult): QueryResult {
+  if (res.type === 'error') throw new Error(res.error.message)
+  const r = (res as any).response.result as StmtResult
+  const rows = r.rows.map((row) => {
+    const obj: Record<string, any> = {}
+    r.cols.forEach((c, i) => {
+      obj[c.name ?? `c${i}`] = fromHrana(row[i] ?? { type: 'null' })
+    })
+    return obj
+  })
+  return { rows, rowsAffected: r.affected_row_count, lastInsertRowid: r.last_insert_rowid ? Number(r.last_insert_rowid) : undefined }
+}
+
+class OdbliteSocketConnection implements Connection {
+  databaseName?: string
+  databaseHash?: string
+  public sql: any
+  private readonly buffer?: { sql: string; params: any[] }[]
+
+  constructor(
+    private readonly client: SocketClient,
+    private readonly tenant: string,
+    buffer?: { sql: string; params: any[] }[],
+  ) {
+    this.databaseName = tenant
+    this.databaseHash = tenant
+    this.buffer = buffer
+    const self = this
+    this.sql = function (strings: any, ...values: any[]): any {
+      if (strings && typeof strings === 'object' && 'raw' in strings) {
+        const text = (strings as string[]).reduce((a, s, i) => a + s + (i < values.length ? '?' : ''), '')
+        const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text)
+        return (returns ? self.query(text, values) : self.execute(text, values)).then((r: any) => r.rows)
+      }
+      throw new Error('sql() fragment helper not implemented in odblite-socket')
+    }
+  }
+
+  /** One request → its single result, failing loud on an empty response. */
+  private async one(requests: StreamRequest[]): Promise<StreamResult> {
+    const [res] = await this.client.pipeline(this.tenant, requests)
+    if (!res) throw new Error('odblite-socket: empty pipeline response')
+    return res
+  }
+
+  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql, args: params.map(toHrana) } }])) as QueryResult<T>
+  }
+
+  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = []): Promise<QueryResult> {
+    const s = typeof sql === 'string' ? sql : sql.sql
+    const p = typeof sql === 'string' ? params : (sql.args ?? [])
+    if (this.buffer) {
+      this.buffer.push({ sql: s, params: p }) // deferred → flushed as one batch on commit
+      return { rows: [], rowsAffected: 0 }
+    }
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql: s, args: p.map(toHrana) } }]))
+  }
+
+  /** Guarded atomic batch — the primary remote write primitive (one round-trip). */
+  async atomic(steps: AtomicStep[]): Promise<BatchResult> {
+    const res = await this.one([{ type: 'batch', batch: toBatch(steps) }])
+    if (res.type === 'error') throw new Error(res.error.message)
+    return (res as any).response.result as BatchResult
+  }
+
+  prepare(sql: string): PreparedStatement {
+    return {
+      execute: async (params = []) => this.execute(sql, params),
+      all: async (params = []) => (await this.query(sql, params)).rows,
+      get: async (params = []) => (await this.query(sql, params)).rows[0] ?? null,
+    }
+  }
+
+  async transaction<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    if (this.buffer) return fn(this) // nested → same buffer
+    const buffer: { sql: string; params: any[] }[] = []
+    const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer))
+    if (buffer.length) {
+      const res = await this.atomic(buffer.map((b) => ({ sql: b.sql, params: b.params })))
+      const err = res.step_errors?.find((e) => e)
+      if (err) throw new Error(`transaction batch failed: ${err.message}`)
+    }
+    return out
+  }
+  begin<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    return this.transaction(fn)
+  }
+  savepoint<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    return this.transaction(fn)
+  }
+
+  // router_v2 auto-ATTACHes a tenant's namespaces on open → these are no-ops.
+  async ensureNamespaces(namespaces: string[]) {
+    return { success: true, databaseName: this.tenant, namespaces }
+  }
+  async getNamespaces() {
+    const ns = (await this.query("SELECT name FROM pragma_database_list WHERE name != 'main'")).rows.map((r: any) => r.name)
+    return { success: true, databaseName: this.tenant, exists: true, namespaces: ns, registered: true, registeredNamespaces: ns }
+  }
+
+  async close(): Promise<void> {
+    /* the SocketClient is shared + owned by the adapter; per-connection close is a no-op */
+  }
+}
+
+export interface OdbliteSocketConfig extends SocketTarget {}
+
+export class OdbliteSocketAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite-socket'
+  private readonly client: SocketClient
+
+  constructor(config: OdbliteSocketConfig) {
+    this.client = new SocketClient(config)
+  }
+
+  async connect(config: any): Promise<Connection> {
+    const tenant = config?.databaseHash ?? config?.databaseName
+    if (!tenant) throw new Error('odblite-socket: databaseHash (or databaseName) required')
+    return new OdbliteSocketConnection(this.client, String(tenant))
+  }
+
+  async disconnect(): Promise<void> {
+    this.client.close()
+  }
+
+  async isHealthy(): Promise<boolean> {
+    try {
+      await Promise.race([
+        this.client.pipeline('_health', [{ type: 'get_autocommit' }]),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('probe timeout')), 1500)),
+      ])
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Default same-host unix socket (free — v1 only uses /tmp/odblite-internal.sock). */
+export const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock'
+
+/**
+ * Resolve the odblite-socket target from a string. `ODB_SOCKET` may be:
+ *   - a UNIX path  (`/tmp/odblite.sock`)        — same host, or a SHARED VOLUME mount
+ *   - `host:port`  (`odblite:8787`)             — TCP, the CROSS-CONTAINER Docker case
+ *   - `:port` / `port`                          — TCP on localhost
+ * A /tmp unix socket does NOT cross Docker containers, so container-to-container
+ * deployments set `ODB_SOCKET=odblite:8787` (TCP over the Docker network).
+ */
+export function parseSocketTarget(s?: string): SocketTarget {
+  const v = (s ?? '').trim()
+  if (!v) return { unix: DEFAULT_UNIX_SOCKET }
+  if (v.includes('/')) return { unix: v } // a path → unix socket
+  const m = v.match(/^(?:([^:]+):)?(\d+)$/) // host:port | :port | port → TCP
+  if (m) return { hostname: m[1] || '127.0.0.1', port: Number(m[2]) }
+  return { unix: v }
+}
+
+/**
+ * OdbliteAutoAdapter — the default for the `odblite` backend: ZERO config change,
+ * autodetected as a cascade  unix socket → TCP socket → HTTP. At startup it probes
+ * each in order and uses the FIRST that answers:
+ *   1. unix socket  /tmp/odblite.sock        — same host (fastest)
+ *   2. TCP socket   <ODB_LITE_URL host>:8787 — cross-container Docker; host is
+ *      DERIVED from the existing ODB_LITE_URL, so Docker needs no new config
+ *   3. HTTP         ODB_LITE_URL              — the universal fallback
+ * Explicit `ODB_SOCKET` (unix path or host:port) or an `odbliteSocket` config
+ * pins a single socket target instead of the cascade. So same-host dev and
+ * cross-container prod both "just work", and a missing/down socket → HTTP.
+ * (Browser / non-Bun → straight to HTTP.)
+ */
+export class OdbliteAutoAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite'
+  private readonly chosen: Promise<DatabaseAdapter>
+
+  constructor(opts: { socket?: OdbliteSocketConfig; http: any }) {
+    this.chosen = this.pick(opts)
+  }
+
+  private async pick(opts: { socket?: OdbliteSocketConfig; http: any }): Promise<DatabaseAdapter> {
+    const hasBun = typeof (globalThis as any).Bun !== 'undefined' && !!(globalThis as any).Bun.connect
+    if (hasBun) {
+      for (const target of this.candidates(opts)) {
+        try {
+          const socket = new OdbliteSocketAdapter(target)
+          if (await socket.isHealthy()) {
+            console.log(`[odb-client] transport → SOCKET (router_v2 @ ${target.unix ?? `${target.hostname}:${target.port}`})`)
+            return socket
+          }
+          await socket.disconnect()
+        } catch {
+          /* try the next candidate */
+        }
+      }
+    }
+    console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)')
+    return new ODBLiteAdapter(opts.http)
+  }
+
+  /** Ordered socket targets to probe. Explicit override → a single target; else the
+   *  zero-config cascade unix (same host) → TCP (host derived from ODB_LITE_URL). */
+  private candidates(opts: { socket?: OdbliteSocketConfig; http: any }): SocketTarget[] {
+    if (opts.socket?.unix || opts.socket?.port) return [opts.socket]
+    const env = (globalThis as any).process?.env?.ODB_SOCKET
+    if (env) return [parseSocketTarget(env)]
+    const out: SocketTarget[] = [{ unix: DEFAULT_UNIX_SOCKET }]
+    try {
+      const host = new URL(opts.http?.serviceUrl).hostname // e.g. odb-lite from http://odb-lite:8671
+      const port = Number((globalThis as any).process?.env?.ODB_SOCKET_PORT ?? 8787)
+      if (host) out.push({ hostname: host, port })
+    } catch {
+      /* serviceUrl unparseable → no TCP candidate, HTTP will catch it */
+    }
+    return out
+  }
+
+  async connect(config: any): Promise<Connection> {
+    return (await this.chosen).connect(config)
+  }
+  async disconnect(tenantId?: string): Promise<void> {
+    return (await this.chosen).disconnect(tenantId)
+  }
+  async isHealthy(): Promise<boolean> {
+    return (await this.chosen).isHealthy()
+  }
+}

package/src/database/adapters/odblite.ts

@@ -19,6 +19,45 @@ import {
   where
 } from '../sql-template'
 
+/**
+ * AsyncLocalStorage, loaded lazily so the client stays isomorphic. On the server
+ * (Node/Bun) it carries the active transaction token across awaits so every
+ * statement inside a transaction is tagged with — and only with — its own token,
+ * even when other transactions run concurrently on the same shared connection.
+ * In browsers/edge (no async_hooks) it's null and we fall back to a per-connection
+ * flag, which is sufficient there because that concurrency pattern doesn't occur.
+ */
+type TxStore = { txId: string }
+let AsyncLocalStorageCtor: (new () => AsyncLocalStorageLike<TxStore>) | null = null
+interface AsyncLocalStorageLike<T> {
+  getStore(): T | undefined
+  run<R>(store: T, fn: () => R): R
+}
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  AsyncLocalStorageCtor = require('node:async_hooks').AsyncLocalStorage
+} catch {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    AsyncLocalStorageCtor = require('async_hooks').AsyncLocalStorage
+  } catch {
+    AsyncLocalStorageCtor = null
+  }
+}
+
+let txCounter = 0
+/** Generate a process-unique transaction token. */
+function newTxId(): string {
+  try {
+    const c = (globalThis as any).crypto
+    if (c?.randomUUID) return `tx_${c.randomUUID()}`
+  } catch {
+    // fall through
+  }
+  txCounter = (txCounter + 1) % Number.MAX_SAFE_INTEGER
+  return `tx_${Date.now().toString(36)}_${txCounter.toString(36)}`
+}
+
 /**
  * Parse JSON columns in query results
  * Only parses if the value is a string (to avoid double-parsing)
@@ -139,7 +178,14 @@ export class ODBLiteAdapter implements DatabaseAdapter {
 class ODBLiteConnection implements Connection {
   private client: ODBLiteClient
   private serviceClient: ServiceClient
-  private inTransaction = false
+  // Carries the active transaction token across awaits (server only). Distinguishes
+  // a genuinely-nested transaction() call (same async context) from a concurrent
+  // top-level one on this shared connection — replacing the old shared
+  // `inTransaction` boolean, which leaked between concurrent requests.
+  private txStorage: AsyncLocalStorageLike<TxStore> | null =
+    AsyncLocalStorageCtor ? new AsyncLocalStorageCtor() : null
+  // Browser/edge fallback when AsyncLocalStorage is unavailable.
+  private fallbackTxId?: string
 
   // Public metadata fields
   public databaseName: string
@@ -209,6 +255,23 @@ class ODBLiteConnection implements Connection {
     return this.execute(sql, params, options) as Promise<QueryResult<T>>
   }
 
+  /** The token of the transaction this async context belongs to, if any. */
+  private activeTxId(): string | undefined {
+    return this.txStorage ? this.txStorage.getStore()?.txId : this.fallbackTxId
+  }
+
+  /**
+   * Per-request options for the underlying client. Inside a transaction every
+   * statement carries the transaction token (so the router pins it to the
+   * transaction's connection) and disables retries (transaction statements are
+   * not idempotent — a retried COMMIT/INSERT could double-apply or hit a closed
+   * transaction).
+   */
+  private requestOpts(): { txId?: string; maxRetries?: number } | undefined {
+    const txId = this.activeTxId()
+    return txId ? { txId, maxRetries: 1 } : undefined
+  }
+
   /**
    * Execute SQL with parameters
    */
@@ -217,6 +280,7 @@ class ODBLiteConnection implements Connection {
       let rows: any[]
       let rowsAffected: number
       let lastInsertRowid: any
+      const reqOpts = this.requestOpts()
 
       // Handle object format { sql, args }
       if (typeof sql === 'object') {
@@ -230,7 +294,7 @@ class ODBLiteConnection implements Connection {
         if (options?.stringifyParams) {
           args = stringifyJsonParams(args, options.stringifyParams)
         }
-        const result = await this.client.sql.execute(sql.sql, args)
+        const result = await this.client.sql.execute(sql.sql, args, reqOpts)
         rows = result.rows
         rowsAffected = result.rowsAffected || 0
         lastInsertRowid = (result as any).lastInsertRowid
@@ -245,7 +309,7 @@ class ODBLiteConnection implements Connection {
         if (options?.stringifyParams) {
           args = stringifyJsonParams(args, options.stringifyParams)
         }
-        const result = await this.client.sql.execute(sql, args)
+        const result = await this.client.sql.execute(sql, args, reqOpts)
         rows = result.rows
         rowsAffected = result.rowsAffected || 0
         lastInsertRowid = (result as any).lastInsertRowid
@@ -300,35 +364,42 @@ class ODBLiteConnection implements Connection {
    * same connection without interleaving from other requests.
    */
   async transaction<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
-    if (this.inTransaction) {
-      // Already in transaction - join existing transaction (no savepoint overhead).
-      // This allows convenience functions that each wrap in db.transaction()
-      // to be freely composed inside an outer transaction.
+    if (this.activeTxId()) {
+      // Genuinely nested call: this async context already owns a transaction on
+      // this connection — join it (no nested BEGIN), exactly like the previous
+      // reentrancy behaviour. Convenience functions that each wrap in
+      // db.transaction() compose freely inside an outer transaction.
       return fn(this)
     }
 
-    this.inTransaction = true
-
-    try {
-      // Start transaction
-      await this.execute('BEGIN')
+    // New top-level transaction: mint a token so the router pins every one of
+    // this transaction's statements to a single connection and never lets a
+    // concurrent transaction's (or autocommit) statements interleave onto it.
+    const txId = newTxId()
 
+    const run = async (): Promise<T> => {
+      const prevFallback = this.fallbackTxId
+      if (!this.txStorage) this.fallbackTxId = txId
       try {
-        // Execute user function - each statement executes immediately
-        const result = await fn(this)
-
-        // Commit transaction
-        await this.execute('COMMIT')
-
-        return result
-      } catch (error) {
-        // Rollback on error
-        await this.execute('ROLLBACK').catch(() => {})
-        throw error
+        // Start transaction (tagged with txId + no-retry via requestOpts())
+        await this.execute('BEGIN')
+        try {
+          // Execute user function - each statement executes immediately
+          const result = await fn(this)
+          // Commit transaction
+          await this.execute('COMMIT')
+          return result
+        } catch (error) {
+          // Rollback on error
+          await this.execute('ROLLBACK').catch(() => {})
+          throw error
+        }
+      } finally {
+        if (!this.txStorage) this.fallbackTxId = prevFallback
       }
-    } finally {
-      this.inTransaction = false
     }
+
+    return this.txStorage ? this.txStorage.run({ txId }, run) : run()
   }
 
   /**
@@ -343,7 +414,7 @@ class ODBLiteConnection implements Connection {
    * If called outside a transaction, behaves like transaction().
    */
   async savepoint<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
-    if (!this.inTransaction) {
+    if (!this.activeTxId()) {
       return this.transaction(fn)
     }
 

package/src/database/adapters/socket/client.ts

@@ -0,0 +1,78 @@
+import { FrameReader, FrameWriter, type StreamRequest, type StreamResult } from './protocol'
+
+/**
+ * Persistent socket client for the odblite-socket transport. One connection,
+ * length-prefixed frames, replies correlated by id. Batch many statements into
+ * one `requests[]` so N statements cost one round-trip.
+ *
+ * Bun-only (uses `Bun.connect`). app-router runs on Bun; the HTTP `odblite`
+ * backend remains the universal fallback for non-Bun environments.
+ */
+export interface SocketTarget {
+  unix?: string
+  hostname?: string
+  port?: number
+}
+
+export class SocketClient {
+  private socket: any
+  private reader = new FrameReader()
+  private writer!: FrameWriter
+  private readonly pending = new Map<number, (r: StreamResult[]) => void>()
+  private nextId = 1
+  private ready: Promise<void>
+
+  constructor(private readonly target: SocketTarget) {
+    this.ready = this.connect()
+    // A failed initial connect (e.g. socket not up) surfaces via pipeline()'s
+    // await — don't let the orphaned promise become an unhandled rejection.
+    void this.ready.catch(() => {})
+  }
+
+  private async connect(): Promise<void> {
+    const Bun = (globalThis as any).Bun
+    if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)')
+    const opts: any = this.target.unix
+      ? { unix: this.target.unix }
+      : { hostname: this.target.hostname ?? '127.0.0.1', port: this.target.port ?? 8787 }
+    this.socket = await Bun.connect({
+      ...opts,
+      socket: {
+        data: (_s: any, chunk: Buffer) => {
+          for (const frame of this.reader.push(chunk)) {
+            const msg = JSON.parse(frame.toString('utf8')) as { id: number; results: StreamResult[] }
+            const resolve = this.pending.get(msg.id)
+            if (resolve) {
+              this.pending.delete(msg.id)
+              resolve(msg.results)
+            }
+          }
+        },
+        drain: (_s: any) => this.writer.flush(),
+        close: () => {
+          // reconnect lazily on next pipeline()
+          this.socket = undefined
+        },
+      },
+    })
+    this.writer = new FrameWriter(this.socket)
+  }
+
+  async pipeline(tenant: string, requests: StreamRequest[]): Promise<StreamResult[]> {
+    if (!this.socket) {
+      this.ready = this.connect()
+      void this.ready.catch(() => {})
+    }
+    await this.ready
+    const id = this.nextId++
+    return new Promise<StreamResult[]>((resolve) => {
+      this.pending.set(id, resolve)
+      this.writer.send(Buffer.from(JSON.stringify({ id, tenant, requests }), 'utf8'))
+    })
+  }
+
+  close(): void {
+    this.socket?.end?.()
+    this.socket = undefined
+  }
+}