@pineliner/odb-client 1.2.0 → 1.5.0

package/dist/index.js

@@ -2114,6 +2114,10 @@ function toBatch(steps) {
             }))
     };
 }
+const READ_ONLY_RE = /^\s*(?:SELECT|EXPLAIN|VALUES)\b/i;
+function mightReturnRows(sql) {
+    return READ_ONLY_RE.test(sql) || /\bRETURNING\b/i.test(sql);
+}
 class FrameWriter {
     socket;
     pending = Buffer.alloc(0);
@@ -2141,6 +2145,7 @@ class FrameWriter {
         }
     }
 }
+const MAX_FRAME = 1024 * (Number(globalThis.process?.env?.ODB_MAX_FRAME_MB) || 64) * 1024;
 class FrameReader {
     buf = Buffer.alloc(0);
     push(chunk) {
@@ -2151,6 +2156,7 @@ class FrameReader {
         const out = [];
         while(this.buf.length >= 4){
             const len = this.buf.readUInt32LE(0);
+            if (len > MAX_FRAME) throw new Error(`odblite reply frame too large: ${len} bytes (max ${MAX_FRAME})`);
             if (this.buf.length < 4 + len) break;
             out.push(this.buf.subarray(4, 4 + len));
             this.buf = this.buf.subarray(4 + len);
@@ -2158,6 +2164,10 @@ class FrameReader {
         return out;
     }
 }
+const REQUEST_TIMEOUT_MS = Number(globalThis.process?.env?.ODB_SOCKET_REQUEST_TIMEOUT_MS) || 30000;
+const RECONNECT_ATTEMPTS = Number(globalThis.process?.env?.ODB_SOCKET_RECONNECT_ATTEMPTS) || 6;
+const RECONNECT_BASE_MS = Number(globalThis.process?.env?.ODB_SOCKET_RECONNECT_BASE_MS) || 50;
+const sleep = (ms)=>new Promise((r)=>setTimeout(r, ms));
 class SocketClient {
     target;
     socket;
@@ -2165,12 +2175,20 @@ class SocketClient {
     writer;
     pending = new Map();
     nextId = 1;
+    nextStreamId = 1;
     ready;
     constructor(target){
         this.target = target;
         this.ready = this.connect();
         this.ready.catch(()=>{});
     }
+    failPending(err) {
+        for (const p of this.pending.values()){
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
     async connect() {
         const Bun = globalThis.Bun;
         if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)');
@@ -2183,43 +2201,93 @@ class SocketClient {
         this.socket = await Bun.connect({
             ...opts,
             socket: {
-                data: (_s, chunk)=>{
-                    for (const frame of this.reader.push(chunk)){
+                data: (s, chunk)=>{
+                    let frames;
+                    try {
+                        frames = this.reader.push(chunk);
+                    } catch (err) {
+                        this.socket = void 0;
+                        this.reader = new FrameReader();
+                        try {
+                            s.end?.();
+                        } catch  {}
+                        this.failPending(err instanceof Error ? err : new Error(`odblite framing error: ${err}`));
+                        return;
+                    }
+                    for (const frame of frames){
                         const msg = JSON.parse(frame.toString('utf8'));
-                        const resolve = this.pending.get(msg.id);
-                        if (resolve) {
+                        const p = this.pending.get(msg.id);
+                        if (p) {
                             this.pending.delete(msg.id);
-                            resolve(msg.results);
+                            clearTimeout(p.timer);
+                            p.resolve(msg.results);
                         }
                     }
                 },
                 drain: (_s)=>this.writer.flush(),
                 close: ()=>{
                     this.socket = void 0;
+                    this.reader = new FrameReader();
+                    this.failPending(new Error('odblite socket disconnected — request not completed'));
+                },
+                error: (_s, err)=>{
+                    this.socket = void 0;
+                    this.reader = new FrameReader();
+                    this.failPending(err instanceof Error ? err : new Error(`odblite socket error: ${err}`));
                 }
             }
         });
         this.writer = new FrameWriter(this.socket);
     }
-    async pipeline(tenant, requests) {
+    async connectWithRetry() {
+        let lastErr;
+        for(let attempt = 0; attempt < RECONNECT_ATTEMPTS; attempt++)try {
+            await this.connect();
+            return;
+        } catch (err) {
+            lastErr = err;
+            if (attempt < RECONNECT_ATTEMPTS - 1) await sleep(RECONNECT_BASE_MS * 2 ** attempt);
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(`odblite socket reconnect failed: ${lastErr}`);
+    }
+    allocStream() {
+        return this.nextStreamId++;
+    }
+    async pipeline(tenant, requests, stream) {
+        await this.ready.catch(()=>{});
         if (!this.socket) {
-            this.ready = this.connect();
+            this.ready = this.connectWithRetry();
             this.ready.catch(()=>{});
+            await this.ready;
         }
-        await this.ready;
         const id = this.nextId++;
-        return new Promise((resolve)=>{
-            this.pending.set(id, resolve);
-            this.writer.send(Buffer.from(JSON.stringify({
+        return new Promise((resolve, reject)=>{
+            const timer = setTimeout(()=>{
+                if (this.pending.delete(id)) reject(new Error(`odblite socket request ${id} timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            timer.unref?.();
+            this.pending.set(id, {
+                resolve,
+                reject,
+                timer
+            });
+            const payload = null != stream ? {
+                id,
+                tenant,
+                stream,
+                requests
+            } : {
                 id,
                 tenant,
                 requests
-            }), 'utf8'));
+            };
+            this.writer.send(Buffer.from(JSON.stringify(payload), 'utf8'));
         });
     }
     close() {
         this.socket?.end?.();
         this.socket = void 0;
+        this.failPending(new Error('odblite socket closed'));
     }
 }
 function toQueryResult(res) {
@@ -2243,21 +2311,22 @@ function toQueryResult(res) {
 class OdbliteSocketConnection {
     client;
     tenant;
+    streamId;
     databaseName;
     databaseHash;
     sql;
-    buffer;
-    constructor(client, tenant, buffer){
+    beginPending = false;
+    constructor(client, tenant, streamId){
         this.client = client;
         this.tenant = tenant;
+        this.streamId = streamId;
         this.databaseName = tenant;
         this.databaseHash = tenant;
-        this.buffer = buffer;
         const self = this;
         this.sql = function(strings, ...values) {
             if (strings && 'object' == typeof strings && 'raw' in strings) {
                 const text = strings.reduce((a, s, i)=>a + s + (i < values.length ? '?' : ''), '');
-                const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text);
+                const returns = mightReturnRows(text);
                 return (returns ? self.query(text, values) : self.execute(text, values)).then((r)=>r.rows);
             }
             throw new Error('sql() fragment helper not implemented in odblite-socket');
@@ -2268,7 +2337,32 @@ class OdbliteSocketConnection {
         if (!res) throw new Error('odblite-socket: empty pipeline response');
         return res;
     }
+    async streamExec(sql, params = []) {
+        const reqs = [];
+        if (this.beginPending) {
+            reqs.push({
+                type: 'execute',
+                stmt: {
+                    sql: 'BEGIN'
+                }
+            });
+            this.beginPending = false;
+        }
+        reqs.push({
+            type: 'execute',
+            stmt: {
+                sql,
+                args: params.map(toHrana)
+            }
+        });
+        const results = await this.client.pipeline(this.tenant, reqs, this.streamId);
+        if (reqs.length > 1 && results[0]?.type === 'error') throw new Error(results[0].error.message);
+        const res = results[results.length - 1];
+        if (!res) throw new Error('odblite-socket: empty stream response');
+        return toQueryResult(res);
+    }
     async query(sql, params = []) {
+        if (null != this.streamId) return await this.streamExec(sql, params);
         return toQueryResult(await this.one([
             {
                 type: 'execute',
@@ -2282,16 +2376,7 @@ class OdbliteSocketConnection {
     async execute(sql, params = []) {
         const s = 'string' == typeof sql ? sql : sql.sql;
         const p = 'string' == typeof sql ? params : sql.args ?? [];
-        if (this.buffer) {
-            this.buffer.push({
-                sql: s,
-                params: p
-            });
-            return {
-                rows: [],
-                rowsAffected: 0
-            };
-        }
+        if (null != this.streamId) return this.streamExec(s, p);
         return toQueryResult(await this.one([
             {
                 type: 'execute',
@@ -2320,24 +2405,33 @@ class OdbliteSocketConnection {
         };
     }
     async transaction(fn) {
-        if (this.buffer) return fn(this);
-        const buffer = [];
-        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}`);
+        if (null != this.streamId) return fn(this);
+        const tx = new OdbliteSocketConnection(this.client, this.tenant, this.client.allocStream());
+        tx.beginPending = true;
+        try {
+            const out = await fn(tx);
+            if (!tx.beginPending) await tx.streamExec('COMMIT');
+            return out;
+        } catch (e) {
+            if (!tx.beginPending) await tx.streamExec('ROLLBACK').catch(()=>{});
+            throw e;
         }
-        return out;
     }
     begin(fn) {
         return this.transaction(fn);
     }
-    savepoint(fn) {
-        return this.transaction(fn);
+    async savepoint(fn) {
+        if (null == this.streamId) return this.transaction(fn);
+        const name = `sp_${this.client.allocStream()}`;
+        await this.streamExec(`SAVEPOINT ${name}`);
+        try {
+            const out = await fn(this);
+            await this.streamExec(`RELEASE SAVEPOINT ${name}`);
+            return out;
+        } catch (e) {
+            await this.streamExec(`ROLLBACK TO SAVEPOINT ${name}`).catch(()=>{});
+            throw e;
+        }
     }
     async ensureNamespaces(namespaces) {
         return {
@@ -2375,20 +2469,26 @@ class OdbliteSocketAdapter {
     }
     async isHealthy() {
         try {
-            await Promise.race([
+            const res = await Promise.race([
                 this.client.pipeline('_health', [
                     {
-                        type: 'get_autocommit'
+                        type: 'get_version'
                     }
                 ]),
                 new Promise((_, rej)=>setTimeout(()=>rej(new Error('probe timeout')), 1500))
             ]);
+            const proto = res?.[0]?.response?.protocol;
+            if (proto !== CLIENT_SOCKET_PROTOCOL) {
+                console.warn(`[odb-client] socket protocol mismatch (server=${proto ?? 'none'}, client=${CLIENT_SOCKET_PROTOCOL}) → using HTTP`);
+                return false;
+            }
             return true;
         } catch  {
             return false;
         }
     }
 }
+const CLIENT_SOCKET_PROTOCOL = 2;
 const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock';
 function parseSocketTarget(s) {
     const v = (s ?? '').trim();
@@ -2409,13 +2509,26 @@ function parseSocketTarget(s) {
 }
 class OdbliteAutoAdapter {
     type = 'odblite';
+    opts;
     chosen;
+    onHttp = false;
+    nextRetryAt = 0;
     constructor(opts){
-        this.chosen = this.pick(opts);
+        this.opts = opts;
+        this.chosen = this.pick();
     }
-    async pick(opts) {
+    async pick() {
         const hasBun = void 0 !== globalThis.Bun && !!globalThis.Bun.connect;
-        if (hasBun) for (const target of this.candidates(opts))try {
+        if (hasBun) {
+            const socket = await this.trySocket();
+            if (socket) return socket;
+        }
+        this.onHttp = true;
+        console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)');
+        return new ODBLiteAdapter(this.opts.http);
+    }
+    async trySocket() {
+        for (const target of this.candidates())try {
             const socket = new OdbliteSocketAdapter(target);
             if (await socket.isHealthy()) {
                 console.log(`[odb-client] transport → SOCKET (router_v2 @ ${target.unix ?? `${target.hostname}:${target.port}`})`);
@@ -2423,12 +2536,23 @@ class OdbliteAutoAdapter {
             }
             await socket.disconnect();
         } catch  {}
-        console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)');
-        return new ODBLiteAdapter(opts.http);
-    }
-    candidates(opts) {
-        if (opts.socket?.unix || opts.socket?.port) return [
-            opts.socket
+        return null;
+    }
+    async maybeUpgrade() {
+        if (!this.onHttp) return;
+        const now = Date.now();
+        if (now < this.nextRetryAt) return;
+        this.nextRetryAt = now + 15000;
+        const socket = await this.trySocket();
+        if (socket) {
+            this.chosen = Promise.resolve(socket);
+            this.onHttp = false;
+        }
+    }
+    candidates() {
+        const { socket, http } = this.opts;
+        if (socket?.unix || socket?.port) return [
+            socket
         ];
         const env = globalThis.process?.env?.ODB_SOCKET;
         if (env) return [
@@ -2440,7 +2564,7 @@ class OdbliteAutoAdapter {
             }
         ];
         try {
-            const host = new URL(opts.http?.serviceUrl).hostname;
+            const host = new URL(http?.serviceUrl).hostname;
             const port = Number(globalThis.process?.env?.ODB_SOCKET_PORT ?? 8787);
             if (host) out.push({
                 hostname: host,
@@ -2450,6 +2574,7 @@ class OdbliteAutoAdapter {
         return out;
     }
     async connect(config) {
+        await this.maybeUpgrade();
         return (await this.chosen).connect(config);
     }
     async disconnect(tenantId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pineliner/odb-client",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Isomorphic client for ODB-Lite with postgres.js-like template string SQL support",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

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

@@ -5,6 +5,7 @@ import {
   toHrana,
   fromHrana,
   toBatch,
+  mightReturnRows,
   type AtomicStep,
   type BatchResult,
   type StmtResult,
@@ -43,21 +44,24 @@ class OdbliteSocketConnection implements Connection {
   databaseName?: string
   databaseHash?: string
   public sql: any
-  private readonly buffer?: { sql: string; params: any[] }[]
+  /** A fresh stream tx whose BEGIN hasn't been flushed yet — it's folded into the first statement's
+   *  frame to save a round-trip (and an empty tx that issues no statements sends nothing at all). */
+  private beginPending = false
 
   constructor(
     private readonly client: SocketClient,
     private readonly tenant: string,
-    buffer?: { sql: string; params: any[] }[],
+    /** Set → this connection is scoped to an interactive transaction STREAM: every query/execute runs
+     *  on the server's PINNED connection (read-your-own-writes), not autocommit. */
+    private readonly streamId?: number,
   ) {
     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)
+        const returns = mightReturnRows(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')
@@ -71,17 +75,31 @@ class OdbliteSocketConnection implements Connection {
     return res
   }
 
+  /** Run one statement on this connection's interactive STREAM — the server's pinned connection, so a
+   *  read sees this tx's own uncommitted writes. Throws on error (incl. a poisoned COMMIT). */
+  private async streamExec(sql: string, params: any[] = []): Promise<QueryResult> {
+    const reqs: StreamRequest[] = []
+    if (this.beginPending) {
+      reqs.push({ type: 'execute', stmt: { sql: 'BEGIN' } }) // fold BEGIN into this first statement's frame
+      this.beginPending = false
+    }
+    reqs.push({ type: 'execute', stmt: { sql, args: params.map(toHrana) } })
+    const results = await this.client.pipeline(this.tenant, reqs, this.streamId)
+    if (reqs.length > 1 && results[0]?.type === 'error') throw new Error(results[0].error.message) // the folded BEGIN failed
+    const res = results[results.length - 1]
+    if (!res) throw new Error('odblite-socket: empty stream response')
+    return toQueryResult(res)
+  }
+
   async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
+    if (this.streamId != null) return (await this.streamExec(sql, params)) as 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 }
-    }
+    if (this.streamId != null) return this.streamExec(s, p) // on the pinned stream — runs immediately, NOT buffered
     return toQueryResult(await this.one([{ type: 'execute', stmt: { sql: s, args: p.map(toHrana) } }]))
   }
 
@@ -100,22 +118,42 @@ class OdbliteSocketConnection implements Connection {
     }
   }
 
+  /**
+   * Interactive transaction over a STREAM (one pinned server connection): BEGIN → fn's reads+writes →
+   * COMMIT, all on the same connection. Reads see their own writes, and the engine enforces atomicity
+   * (a failed statement poisons the tx → a later COMMIT is forced to ROLLBACK). Replaces the old
+   * buffered model, which couldn't read its own writes and only flushed at commit.
+   */
   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}`)
+    if (this.streamId != null) return fn(this) // nested → join the already-open stream
+    const tx = new OdbliteSocketConnection(this.client, this.tenant, this.client.allocStream())
+    tx.beginPending = true // BEGIN folds into the first statement's frame (one fewer round-trip)
+    try {
+      const out = await fn(tx)
+      if (!tx.beginPending) await tx.streamExec('COMMIT') // a statement ran → BEGIN was sent → COMMIT it
+      return out // else fn issued no statements → empty tx, BEGIN never sent, zero round-trips
+    } catch (e) {
+      if (!tx.beginPending) await tx.streamExec('ROLLBACK').catch(() => {}) // best-effort; server also reaps
+      throw e
     }
-    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)
+  /** Nested partial-rollback scope. Inside a stream → a real SAVEPOINT (a ROLLBACK TO SAVEPOINT clears
+   *  the engine's poison); at top level → a full transaction. */
+  async savepoint<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    if (this.streamId == null) return this.transaction(fn)
+    const name = `sp_${this.client.allocStream()}`
+    await this.streamExec(`SAVEPOINT ${name}`)
+    try {
+      const out = await fn(this)
+      await this.streamExec(`RELEASE SAVEPOINT ${name}`)
+      return out
+    } catch (e) {
+      await this.streamExec(`ROLLBACK TO SAVEPOINT ${name}`).catch(() => {})
+      throw e
+    }
   }
 
   // router_v2 auto-ATTACHes a tenant's namespaces on open → these are no-ops.
@@ -154,10 +192,18 @@ export class OdbliteSocketAdapter implements DatabaseAdapter {
 
   async isHealthy(): Promise<boolean> {
     try {
-      await Promise.race([
-        this.client.pipeline('_health', [{ type: 'get_autocommit' }]),
+      const res: any = await Promise.race([
+        this.client.pipeline('_health', [{ type: 'get_version' }]),
         new Promise((_, rej) => setTimeout(() => rej(new Error('probe timeout')), 1500)),
       ])
+      // Connect-time HANDSHAKE: adopt the socket only if the server speaks our wire protocol. A different
+      // generation — or a server too old to answer get_version — falls back to HTTP instead of letting a
+      // mismatched client mis-speak the binary port (the 1.2.0 ↔ rebuilt-server skew).
+      const proto = res?.[0]?.response?.protocol
+      if (proto !== CLIENT_SOCKET_PROTOCOL) {
+        console.warn(`[odb-client] socket protocol mismatch (server=${proto ?? 'none'}, client=${CLIENT_SOCKET_PROTOCOL}) → using HTTP`)
+        return false
+      }
       return true
     } catch {
       return false
@@ -165,6 +211,11 @@ export class OdbliteSocketAdapter implements DatabaseAdapter {
   }
 }
 
+/** Socket wire-protocol version this client speaks. The connect-time handshake (isHealthy → get_version)
+ *  requires the server to match; on mismatch the auto-adapter falls back to HTTP. Keep in lockstep with
+ *  router_v2's SOCKET_PROTOCOL. */
+export const CLIENT_SOCKET_PROTOCOL = 2
+
 /** Default same-host unix socket (free — v1 only uses /tmp/odblite-internal.sock). */
 export const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock'
 
@@ -200,41 +251,69 @@ export function parseSocketTarget(s?: string): SocketTarget {
  */
 export class OdbliteAutoAdapter implements DatabaseAdapter {
   readonly type: BackendType = 'odblite'
-  private readonly chosen: Promise<DatabaseAdapter>
+  private readonly opts: { socket?: OdbliteSocketConfig; http: any }
+  private chosen: Promise<DatabaseAdapter>
+  private onHttp = false
+  private nextRetryAt = 0
 
   constructor(opts: { socket?: OdbliteSocketConfig; http: any }) {
-    this.chosen = this.pick(opts)
+    this.opts = opts
+    this.chosen = this.pick()
   }
 
-  private async pick(opts: { socket?: OdbliteSocketConfig; http: any }): Promise<DatabaseAdapter> {
+  private async pick(): 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 */
+      const socket = await this.trySocket()
+      if (socket) return socket
+    }
+    this.onHttp = true
+    console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)')
+    return new ODBLiteAdapter(this.opts.http)
+  }
+
+  /** Probe the cascade once; return a live socket adapter or null. */
+  private async trySocket(): Promise<DatabaseAdapter | null> {
+    for (const target of this.candidates()) {
+      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)
+    return null
+  }
+
+  /** When we fell back to HTTP, re-probe the socket on a cooldown so a socket that
+   *  comes up LATER (server started after the app) is picked up without a restart —
+   *  subsequent connections then use it. */
+  private async maybeUpgrade(): Promise<void> {
+    if (!this.onHttp) return
+    const now = Date.now()
+    if (now < this.nextRetryAt) return
+    this.nextRetryAt = now + 15_000
+    const socket = await this.trySocket()
+    if (socket) {
+      this.chosen = Promise.resolve(socket)
+      this.onHttp = false
+    }
   }
 
   /** 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]
+  private candidates(): SocketTarget[] {
+    const { socket, http } = this.opts
+    if (socket?.unix || socket?.port) return [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 host = new URL(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 {
@@ -244,6 +323,7 @@ export class OdbliteAutoAdapter implements DatabaseAdapter {
   }
 
   async connect(config: any): Promise<Connection> {
+    await this.maybeUpgrade()
     return (await this.chosen).connect(config)
   }
   async disconnect(tenantId?: string): Promise<void> {