@dotdo/postgres 0.1.1 → 0.1.3

package/src/worker/do-pglite-manager.ts

@@ -4,6 +4,18 @@
  * Handles PGLite instance creation, initialization, and lifecycle.
  * Extracted from PostgresDO to reduce class size and separate concerns.
  *
+ * ## WASM Hoisting Pattern
+ *
+ * This module implements WASM hoisting to reduce "warm start" time from ~1200ms to ~30ms.
+ *
+ * The problem: In Cloudflare Workers, when a DO class is recreated (but the isolate stays alive),
+ * the PGLite WASM needs to be reloaded. WASM initialization takes ~1200ms.
+ *
+ * The solution: Cache the PGLite instance at module level. The module loads once per isolate,
+ * so the PGLite instance survives DO class reinstantiation. This means:
+ * - Cold start: ~1200ms (full WASM initialization)
+ * - Warm start (isolate alive, DO recreated): ~30ms (reuse cached WASM)
+ *
  * @module worker/do-pglite-manager
  */
 
@@ -16,7 +28,131 @@ import pgliteWasm from '../pglite-assets/pglite.wasm'
 import pgliteData from '../pglite-assets/pglite.data'
 
 // Import Workers-compatible PGLite wrapper
-import { createWorkersPGLite } from '../pglite/workers-pglite'
+import { createWorkersPGLite, type WorkersPGLite } from '../pglite/workers-pglite'
+
+// =============================================================================
+// Module-Level WASM Hoisting (outside class)
+// =============================================================================
+// These persist as long as the isolate lives - helps reduce warm start time.
+// The module loads once per isolate, so the PGLite instance survives
+// across DO class reinstantiations within the same isolate.
+
+/**
+ * Hoisted PGLite instance - survives DO class reinstantiation within same isolate.
+ * This is the key to reducing warm start time from ~1200ms to ~30ms.
+ */
+let hoistedPglite: WorkersPGLite | null = null
+
+/**
+ * Promise for in-progress PGLite initialization.
+ * Prevents duplicate WASM loading when multiple DO instances initialize concurrently.
+ */
+let hoistedPglitePromise: Promise<WorkersPGLite> | null = null
+
+/**
+ * Module load time for diagnostics.
+ * Note: Date.now() at module evaluation time in Workers returns 0,
+ * so we capture the first access time instead.
+ */
+let MODULE_LOAD_TIME: number | null = null
+
+/**
+ * Unique identifier for this module instance (for debugging/diagnostics).
+ */
+const MODULE_INSTANCE_ID = Math.random().toString(36).slice(2, 10)
+
+/**
+ * Get the module load time (captures on first call since Date.now() is 0 at module load).
+ */
+function getModuleLoadTime(): number {
+  if (MODULE_LOAD_TIME === null) {
+    MODULE_LOAD_TIME = Date.now()
+  }
+  return MODULE_LOAD_TIME
+}
+
+/**
+ * Get or create the hoisted PGLite instance.
+ *
+ * This function implements the singleton pattern with promise deduplication:
+ * - If an instance exists, return it immediately
+ * - If initialization is in progress, return the existing promise
+ * - Otherwise, start initialization and cache both the promise and the result
+ *
+ * @param options - PGLite creation options (only used if creating new instance)
+ * @returns Promise resolving to the PGLite instance
+ */
+async function getOrCreateHoistedPglite(options: {
+  database?: string
+  debug?: 0 | 1
+}): Promise<WorkersPGLite> {
+  // Fast path: already initialized
+  if (hoistedPglite) {
+    return hoistedPglite
+  }
+
+  // Deduplication: return existing promise if initialization in progress
+  if (hoistedPglitePromise) {
+    return hoistedPglitePromise
+  }
+
+  // Start initialization
+  hoistedPglitePromise = createWorkersPGLite({
+    wasmModule: pgliteWasm,
+    fsBundle: pgliteData,
+    database: options.database ?? 'postgres',
+    debug: options.debug ?? 0,
+  })
+
+  try {
+    hoistedPglite = await hoistedPglitePromise
+    return hoistedPglite
+  } finally {
+    // Clear the promise after resolution (success or failure)
+    hoistedPglitePromise = null
+  }
+}
+
+/**
+ * Check if the hoisted PGLite instance exists.
+ * Useful for diagnostics and testing.
+ */
+export function hasHoistedPglite(): boolean {
+  return hoistedPglite !== null
+}
+
+/**
+ * Get diagnostics about the hoisted WASM state.
+ * Useful for debugging warm start performance.
+ */
+export function getHoistedPgliteDiagnostics(): {
+  hasInstance: boolean
+  hasPendingPromise: boolean
+  moduleInstanceId: string
+  moduleLoadTime: number
+  moduleAgeMs: number
+} {
+  const now = Date.now()
+  const loadTime = getModuleLoadTime()
+  return {
+    hasInstance: hoistedPglite !== null,
+    hasPendingPromise: hoistedPglitePromise !== null,
+    moduleInstanceId: MODULE_INSTANCE_ID,
+    moduleLoadTime: loadTime,
+    moduleAgeMs: now - loadTime,
+  }
+}
+
+/**
+ * Reset the hoisted PGLite instance.
+ * WARNING: This should only be used in tests. In production, the hoisted
+ * instance should persist for the lifetime of the isolate.
+ * @internal
+ */
+export function resetHoistedPglite(): void {
+  hoistedPglite = null
+  hoistedPglitePromise = null
+}
 
 /**
  * PGlite-like interface
@@ -50,6 +186,14 @@ export interface PGLiteManagerConfig {
   plugins?: PostgresConfig['plugins']
   /** Custom PGLite factory for testing */
   createPGLite?: () => Promise<PGliteLike>
+  /**
+   * Disable WASM hoisting optimization.
+   * When false (default), the PGLite WASM instance is cached at module level
+   * and survives DO class reinstantiation for optimal warm start performance.
+   * Set to true to create a new WASM instance for each PGLiteManager.
+   * @default false
+   */
+  disableHoisting?: boolean
 }
 
 /**
@@ -85,6 +229,9 @@ export class PGLiteManager {
   private config: PGLiteManagerConfig
   private pluginManager: PluginManager
 
+  /** Track whether this manager is using the hoisted instance */
+  private usingHoistedInstance = false
+
   constructor(config: PGLiteManagerConfig = {}) {
     // Build config without undefined values for exactOptionalPropertyTypes
     this.config = {
@@ -97,6 +244,9 @@ export class PGLiteManager {
     if (config.createPGLite !== undefined) {
       this.config.createPGLite = config.createPGLite
     }
+    if (config.disableHoisting !== undefined) {
+      this.config.disableHoisting = config.disableHoisting
+    }
 
     // Build plugin manager config without undefined values for exactOptionalPropertyTypes
     const pluginManagerConfig: PluginManagerConfig = {}
@@ -166,10 +316,15 @@ export class PGLiteManager {
   /**
    * Create the PGLite instance
    * Can be overridden for testing
+   *
+   * By default, uses the module-level hoisted PGLite instance for optimal
+   * warm start performance. The hoisted instance survives DO class
+   * reinstantiation within the same isolate.
    */
   protected async createPGLiteInstance(): Promise<PGliteLike> {
-    // Use custom factory if provided
+    // Use custom factory if provided (for testing)
     if (this.config.createPGLite) {
+      this.usingHoistedInstance = false
       return this.config.createPGLite()
     }
 
@@ -180,25 +335,37 @@ export class PGLiteManager {
     // as WorkersPGLite doesn't support extension loading yet
     void extensions // Mark as intentionally unused
 
-    // Build options without undefined values for exactOptionalPropertyTypes
-    const pgliteOptions: {
-      wasmModule: WebAssembly.Module
-      fsBundle: ArrayBuffer
-      database?: string
-      debug: 0 | 1
-    } = {
-      // Pre-compiled WASM module for Workers
-      wasmModule: pgliteWasm,
-      // Filesystem bundle with PostgreSQL data files
-      fsBundle: pgliteData,
-      // Database configuration
-      debug: this.config.debug ? 1 : 0,
-    }
-    if (this.config.database !== undefined) {
-      pgliteOptions.database = this.config.database
+    // If hoisting is disabled, create a new instance each time
+    if (this.config.disableHoisting) {
+      this.usingHoistedInstance = false
+      console.log(`[PGLiteManager] WASM hoisting disabled - creating new instance`)
+      return createWorkersPGLite({
+        wasmModule: pgliteWasm,
+        fsBundle: pgliteData,
+        database: this.config.database ?? 'postgres',
+        debug: this.config.debug ? 1 : 0,
+      })
     }
 
-    const pg = await createWorkersPGLite(pgliteOptions)
+    // Use the hoisted PGLite instance for optimal warm start performance.
+    // This is the key optimization: when the DO class is recreated but the
+    // isolate stays alive, we reuse the already-initialized WASM instance
+    // instead of loading it again (~1200ms -> ~30ms).
+    const wasmWasAlreadyLoaded = hoistedPglite !== null
+    const pg = await getOrCreateHoistedPglite({
+      database: this.config.database,
+      debug: this.config.debug ? 1 : 0,
+    })
+
+    this.usingHoistedInstance = true
+
+    // Log whether we reused the WASM instance (helpful for debugging warm starts)
+    if (wasmWasAlreadyLoaded) {
+      const diagnostics = getHoistedPgliteDiagnostics()
+      console.log(`[PGLiteManager] WASM REUSED - module age: ${diagnostics.moduleAgeMs}ms, instance: ${diagnostics.moduleInstanceId}`)
+    } else {
+      console.log(`[PGLiteManager] WASM LOADED (cold start) - instance: ${MODULE_INSTANCE_ID}`)
+    }
 
     return pg
   }
@@ -261,9 +428,28 @@ export class PGLiteManager {
   /**
    * Close PGLite instance
    *
+   * Note: When using the hoisted WASM instance (default), this method does NOT
+   * close the underlying PGLite instance, as it's shared across DO instances.
+   * It only clears the local reference. The hoisted instance persists for the
+   * lifetime of the isolate for optimal warm start performance.
+   *
+   * To actually close the hoisted instance, use resetHoistedPglite() followed
+   * by close() on the next manager that initializes. This should only be done
+   * in tests or when the isolate is shutting down.
+   *
    * @param timeoutMs - Maximum time to wait for close (default: 5000ms)
    */
   async close(timeoutMs: number = 5000): Promise<void> {
+    // If using hoisted instance, don't actually close it - just clear our reference
+    // The hoisted instance should survive for the lifetime of the isolate
+    if (this.usingHoistedInstance) {
+      console.log(`[PGLiteManager] Skipping close of hoisted WASM instance (will be reused)`)
+      this.pglite = null
+      this.initialized = false
+      this.usingHoistedInstance = false
+      return
+    }
+
     if (!this.pglite?.close) {
       this.pglite = null
       this.initialized = false
@@ -291,6 +477,36 @@ export class PGLiteManager {
   reset(): void {
     this.pglite = null
     this.initialized = false
+    this.usingHoistedInstance = false
+  }
+
+  /**
+   * Check if this manager is using the hoisted WASM instance
+   */
+  isUsingHoistedInstance(): boolean {
+    return this.usingHoistedInstance
+  }
+
+  /**
+   * Get diagnostics about WASM hoisting and initialization state.
+   * Useful for debugging warm start performance.
+   */
+  getDiagnostics(): {
+    initialized: boolean
+    usingHoistedInstance: boolean
+    hoisted: {
+      hasInstance: boolean
+      hasPendingPromise: boolean
+      moduleInstanceId: string
+      moduleLoadTime: number
+      moduleAgeMs: number
+    }
+  } {
+    return {
+      initialized: this.initialized,
+      usingHoistedInstance: this.usingHoistedInstance,
+      hoisted: getHoistedPgliteDiagnostics(),
+    }
   }
 }
 

package/src/worker/entry.ts

@@ -152,42 +152,44 @@ function createApp() {
   app.post('/query', async (c) => {
     const dbId = c.req.query('db') || 'default'
 
-    // Get the Durable Object stub
-    const doId = c.env.POSTGRES_DO.idFromName(dbId)
-    const stub = c.env.POSTGRES_DO.get(doId)
-
-    // Forward to DO's /query endpoint
-    const url = new URL(c.req.url)
-    url.pathname = '/query'
-    url.searchParams.delete('db')
-
-    const doRequest = new Request(url.toString(), {
-      method: 'POST',
-      headers: c.req.raw.headers,
-      body: c.req.raw.body,
-    })
+    try {
+      const body = await c.req.json<{ sql: string; params?: unknown[] }>()
+      if (!body.sql) {
+        return c.json({ error: true, code: 'INVALID_REQUEST', message: 'Missing sql field' }, 400)
+      }
 
-    return stub.fetch(doRequest)
+      // Get the Durable Object stub and call RPC method directly
+      const doId = c.env.POSTGRES_DO.idFromName(dbId)
+      const stub = c.env.POSTGRES_DO.get(doId) as DurableObjectStub<PostgresDO>
+      const result = await stub.rpcQuery(body.sql, body.params)
+      return c.json(result)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return c.json({ error: true, code: 'QUERY_ERROR', message }, 500)
+    }
   })
 
   // Batch queries
   app.post('/batch', async (c) => {
     const dbId = c.req.query('db') || 'default'
 
-    const doId = c.env.POSTGRES_DO.idFromName(dbId)
-    const stub = c.env.POSTGRES_DO.get(doId)
-
-    const url = new URL(c.req.url)
-    url.pathname = '/batch'
-    url.searchParams.delete('db')
-
-    const doRequest = new Request(url.toString(), {
-      method: 'POST',
-      headers: c.req.raw.headers,
-      body: c.req.raw.body,
-    })
+    try {
+      const body = await c.req.json<{ queries: Array<{ sql: string; params?: unknown[] }>; transaction?: boolean }>()
+      if (!body.queries || !Array.isArray(body.queries)) {
+        return c.json({ error: true, code: 'INVALID_REQUEST', message: 'Missing queries array' }, 400)
+      }
 
-    return stub.fetch(doRequest)
+      // Get the Durable Object stub and call RPC method directly
+      const doId = c.env.POSTGRES_DO.idFromName(dbId)
+      const stub = c.env.POSTGRES_DO.get(doId) as DurableObjectStub<PostgresDO>
+      const result = body.transaction
+        ? await stub.rpcBatchTransaction(body.queries)
+        : await stub.rpcBatch(body.queries)
+      return c.json(result)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return c.json({ error: true, code: 'BATCH_ERROR', message }, 500)
+    }
   })
 
   // ==========================================================================
@@ -383,8 +385,88 @@ function createApp() {
     }
   })
 
-  // 404 handler
-  app.notFound((c) => {
+  // ==========================================================================
+  // Dynamic database routes (for postgres.do client compatibility)
+  // ==========================================================================
+  // This handles URLs like https://db.example.com.ai/neon-example/query
+  // where the first path segment is the database ID
+  // We use notFound to handle these since Hono matches more specific routes first
+
+  const RESERVED_PATHS = new Set(['ping', 'health', 'user', 'db', 'rpc', 'query', 'batch'])
+
+  // 404 handler - also handles dynamic database routes
+  // Supports postgres.do client URLs like https://db.api.qa/mydb/query
+  app.notFound(async (c) => {
+    // Try to handle as dynamic database route: /:dbId/...
+    const pathParts = c.req.path.split('/').filter(Boolean)
+    if (pathParts.length >= 1) {
+      const dbId = pathParts[0]
+
+      // Skip if it's a reserved path
+      if (!RESERVED_PATHS.has(dbId)) {
+        const remainingPath = '/' + pathParts.slice(1).join('/')
+
+        // Get the Durable Object stub
+        const doId = c.env.POSTGRES_DO.idFromName(dbId)
+        const stub = c.env.POSTGRES_DO.get(doId) as DurableObjectStub<PostgresDO>
+
+        // Handle specific paths via RPC
+        if (remainingPath === '/query' && c.req.method === 'POST') {
+          try {
+            const body = await c.req.json<{ sql: string; params?: unknown[] }>()
+            if (!body.sql) {
+              return c.json({ error: true, code: 'INVALID_REQUEST', message: 'Missing sql field' }, 400)
+            }
+            const result = await stub.rpcQuery(body.sql, body.params)
+            return c.json(result)
+          } catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error'
+            return c.json({ error: true, code: 'QUERY_ERROR', message }, 500)
+          }
+        }
+
+        if (remainingPath === '/batch' && c.req.method === 'POST') {
+          try {
+            const body = await c.req.json<{ queries: Array<{ sql: string; params?: unknown[] }>; transaction?: boolean }>()
+            if (!body.queries || !Array.isArray(body.queries)) {
+              return c.json({ error: true, code: 'INVALID_REQUEST', message: 'Missing queries array' }, 400)
+            }
+            const result = body.transaction
+              ? await stub.rpcBatchTransaction(body.queries)
+              : await stub.rpcBatch(body.queries)
+            return c.json(result)
+          } catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error'
+            return c.json({ error: true, code: 'BATCH_ERROR', message }, 500)
+          }
+        }
+
+        if (remainingPath === '/transaction' && c.req.method === 'POST') {
+          try {
+            const body = await c.req.json<{ queries: Array<{ sql: string; params?: unknown[] }>; options?: unknown }>()
+            if (!body.queries || !Array.isArray(body.queries)) {
+              return c.json({ error: true, code: 'INVALID_REQUEST', message: 'Missing queries array' }, 400)
+            }
+            const result = await stub.rpcBatchTransaction(body.queries)
+            return c.json(result)
+          } catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error'
+            return c.json({ error: true, code: 'TRANSACTION_ERROR', message }, 500)
+          }
+        }
+
+        // For other paths, return database info
+        if (remainingPath === '/' || remainingPath === '') {
+          return c.json({
+            service: 'postgres.do',
+            database: dbId,
+            status: 'ready',
+            timestamp: new Date().toISOString(),
+          })
+        }
+      }
+    }
+
     return c.json({
       error: true,
       code: 'NOT_FOUND',

package/src/worker/index.ts

@@ -373,9 +373,45 @@ export { QueryStatsManager, createQueryStatsManager } from './query-stats-manage
 export type { QueryStats, ExtendedQueryStats, QueryStatsConfig } from './query-stats-manager'
 
 // PGLite Manager (extracted from PostgresDO for reuse)
-export { PGLiteManager, createPGLiteManager } from './do-pglite-manager'
+// Includes WASM hoisting for optimal warm start performance (~1200ms -> ~30ms)
+export {
+  PGLiteManager,
+  createPGLiteManager,
+  // WASM Hoisting utilities
+  hasHoistedPglite,
+  getHoistedPgliteDiagnostics,
+  resetHoistedPglite,
+} from './do-pglite-manager'
 export type { PGLiteManagerConfig } from './do-pglite-manager'
 
+// Lazy PGLite Manager (SPIKE: Lazy WASM loading experiment)
+// Defers WASM loading until first query for improved cold start perception
+export {
+  LazyPGLiteManager,
+  createLazyPGLiteManager,
+  // Lazy WASM Hoisting utilities
+  hasLazyHoistedPglite,
+  getLazyHoistedPgliteDiagnostics,
+  resetLazyHoistedPglite,
+} from './lazy-pglite-manager'
+export type { LazyPGLiteManagerConfig, WASMLoadingState } from './lazy-pglite-manager'
+
+// Background PGLite Manager (RECOMMENDED: Eager-but-non-blocking pattern)
+// Starts WASM loading immediately but doesn't block - best of both worlds:
+// - Non-query endpoints respond instantly
+// - WASM loads in background (uses ctx.waitUntil)
+// - First query only waits for remaining load time (often zero)
+export {
+  BackgroundPGLiteManager,
+  createBackgroundPGLiteManager,
+  // Background WASM Hoisting utilities
+  hasBgHoistedPglite,
+  isBgWasmLoading,
+  getBgHoistedPgliteDiagnostics,
+  resetBgHoistedPglite,
+} from './background-pglite-manager'
+export type { BackgroundPGLiteManagerConfig, BGWASMLoadingState } from './background-pglite-manager'
+
 // Query Execution Manager (extracted from PostgresDO for reuse - Task: postgres-an18)
 export { QueryExecutionManager, createQueryExecutionManager } from './query-execution-manager'
 export type { QueryExecutionDependencies, QueryExecutorPGlite } from './query-execution-manager'
@@ -387,3 +423,37 @@ export type { HealthCheckDependencies, HealthCheckPGlite, ColumnDescription, Dat
 // RPC Methods Manager (extracted from PostgresDO for reuse - Task: postgres-an18)
 export { RpcMethodsManager, createRpcMethodsManager } from './rpc-methods-manager'
 export type { RpcMethodsDependencies, RpcMethodsPGlite } from './rpc-methods-manager'
+
+// MCP Server (Model Context Protocol)
+export {
+  createMCPServer,
+  createMCPRoutes,
+  createPGBinding,
+  PG_BINDING_TYPES,
+  searchTool,
+  fetchTool,
+  doTool,
+  getToolDefinitions,
+  createToolHandlers,
+  createSearchHandler,
+  createFetchHandler,
+  createDoHandler,
+} from '../mcp'
+export type {
+  MCPServer,
+  MCPServerConfig,
+  MCPAuthContext,
+  QueryResult as MCPQueryResult,
+  TableInfo,
+  ColumnInfo,
+  MCPSearchResult,
+  MCPFetchResult,
+  PGBinding,
+  PGTransaction,
+  ToolResponse,
+  SearchInput,
+  FetchInput,
+  DoInput,
+  Tool as MCPTool,
+  QueryExecutor as MCPQueryExecutor,
+} from '../mcp'