@dotdo/postgres 0.1.0

package/src/worker/do.ts

@@ -0,0 +1,1878 @@
+/**
+ * PostgresDO - Durable Object for PostgreSQL with PGlite
+ *
+ * A Cloudflare Durable Object providing a complete PostgreSQL database running
+ * in WebAssembly via PGlite. Each DO instance maintains isolated persistent storage.
+ *
+ * ## Architecture
+ *
+ * PostgresDO orchestrates specialized managers for separation of concerns:
+ *
+ * | Manager | Responsibility |
+ * |---------|---------------|
+ * | ShutdownManager | Graceful shutdown, query tracking, connection draining |
+ * | PluginManager | Plugin/extension lifecycle (vector, postgis, etc.) |
+ * | DOAuthManager | Authentication via oauth.do integration |
+ * | QueryStatsManager | Query execution statistics and metrics |
+ * | PGLiteManager | PGlite instance lifecycle and initialization |
+ * | MigrationManager | Schema migrations with version tracking |
+ * | DOWALFacade | Write-Ahead Log capture for CDC/replication |
+ * | MemoryPressureManager | OOM protection and memory monitoring |
+ *
+ * ## Key Features
+ *
+ * - Native RPC support (extends cloudflare:workers DurableObject)
+ * - Promise pipelining for N+1 query elimination
+ * - Lazy initialization - PGlite created on first use
+ * - Auto-migrations on startup or on-demand
+ * - Graceful shutdown with configurable timeout
+ * - Memory protection - auto-unload extensions under pressure
+ *
+ * ## WASM Requirements
+ *
+ * In Cloudflare Workers, PGLite requires pre-compiled WASM modules via static imports.
+ * Uses @dotdo/pglite fork with trampoline-enabled build for Workers compatibility.
+ *
+ * @module worker/do
+ */
+import { DurableObject } from 'cloudflare:workers'
+import type {
+  Env,
+  QueryRequest,
+  QueryResponse,
+  QueryResultRow,
+  PostgresConfig,
+  BatchRequest,
+  BatchResponse,
+  QueryField,
+  MigrationInput,
+  MigrationResult,
+  MigrationProgressEvent,
+  BatchMigrationResult,
+  MigrationState,
+  MigrationStrategy,
+  SchemaVersion,
+  VersionComparison,
+  PluginValue,
+  MemoryPressureConfig,
+  MemoryPressureLevel,
+  MemoryPressureEvent,
+  MemoryPressureListener,
+  MemoryStats,
+  MemoryPressureActionResult,
+} from './types'
+
+/** DO storage key for migration state */
+const MIGRATION_STATE_KEY = '__postgres_migration_state__'
+
+import {
+  PostgresRpcApi,
+  TransactionRpcApi,
+  type RpcQueryResult,
+  type RpcBatchQuery,
+  type RpcBatchResult,
+  type RpcTransactionOptions,
+} from './rpc'
+import { preserveCase } from './sql-transform'
+import type { AuthenticatedUser, TokenValidationResult } from './auth'
+import { NotInitializedError, ShutdownError } from './errors'
+import { SchemaVersionManager, type MigrationEventListener } from './schema-version'
+import { MigrationManager } from './migration-manager'
+import {
+  DOWALFacade,
+  type WALConfig,
+  type WALEntry,
+  type WALBufferStats,
+  type WALEventListener,
+  type WALFlushListener,
+  type WALFlushResult,
+} from './wal-facade'
+import {
+  type PluginName,
+} from '../extensions/plugins'
+import { MemoryPressureManager, createMemoryPressureManager } from './memory-pressure'
+
+// Import modular managers
+import {
+  ShutdownManager,
+  type ShutdownStatus,
+  type ShutdownConfig,
+  type ShutdownEventType,
+  type ShutdownEvent,
+  type ShutdownEventListener,
+} from './shutdown-manager'
+import { PluginManager } from './plugin-manager'
+import { DOAuthManager, type DOAuthConfig } from './do-auth-manager'
+import { QueryStatsManager, type QueryStats } from './query-stats-manager'
+import { PGLiteManager, type PGliteLike } from './do-pglite-manager'
+
+// Re-export manager classes for external use
+export { MigrationManager } from './migration-manager'
+export { DOWALFacade } from './wal-facade'
+
+// Re-export WorkersPGLite for external use
+export { WorkersPGLite, createWorkersPGLite } from '../pglite/workers-pglite'
+export type { WorkersPGLiteLike, WorkersPGLiteOptions } from '../pglite/workers-pglite'
+
+// Re-export types from shutdown-manager (backward compatibility)
+export type {
+  ShutdownStatus,
+  ShutdownEventType,
+  ShutdownEvent,
+  ShutdownEventListener,
+  ShutdownConfig,
+}
+
+/**
+ * Authentication configuration for PostgresDO
+ * Re-exported for backward compatibility
+ */
+export type PostgresDOAuthConfig = DOAuthConfig
+
+/**
+ * Extended Env with auth configuration
+ */
+interface AuthEnv extends Env {
+  OAUTH_URL?: string
+  OAUTH_ENABLED?: string
+}
+
+/**
+ * PostgresDO Durable Object
+ *
+ * Extends DurableObject from cloudflare:workers to enable native RPC support.
+ * All public methods are automatically exposed as RPC endpoints, enabling:
+ *
+ * - Magic map support for N+1 query elimination
+ * - Promise pipelining for efficient RPC
+ * - Direct Worker-to-DO communication without HTTP overhead
+ *
+ * ## Native RPC Usage (Worker-to-DO)
+ * ```typescript
+ * // In your Worker
+ * const id = env.POSTGRES_DO.idFromName('my-db')
+ * const stub = env.POSTGRES_DO.get(id)
+ *
+ * // Call RPC methods directly on the stub
+ * const result = await stub.rpcQuery('SELECT * FROM users')
+ * const tx = await stub.rpcTransaction()
+ * await tx.query('INSERT INTO users (name) VALUES ($1)', ['Alice'])
+ * await tx.commit()
+ * ```
+ *
+ * ## Promise Pipelining
+ * ```typescript
+ * const user = stub.rpcQueryOne('SELECT * FROM users WHERE id = $1', [1])
+ * const orders = stub.rpcQuery('SELECT * FROM orders WHERE user_id = $1', [user.id])
+ * const [userData, orderData] = await Promise.all([user, orders])
+ * ```
+ */
+export class PostgresDO extends DurableObject<Env> {
+  // Note: ctx and env are inherited from DurableObject<Env>
+  private _authEnv: AuthEnv | null = null
+  private config: PostgresConfig
+
+  // Modular managers
+  private shutdownManager: ShutdownManager
+  private pluginManager: PluginManager
+  private authManager: DOAuthManager
+  private statsManager: QueryStatsManager
+  private pgliteManager: PGLiteManager
+
+  // Injected concerns for dependency injection and testing
+  private injectedAuthConcern: unknown = null
+  private injectedQueryExecutionConcern: unknown = null
+  private injectedCDCConcern: unknown = null
+  // @ts-expect-error - Kept for future use in storage orchestration
+  private injectedStorageOrchestrationConcern: unknown = null
+
+  // Migration manager for schema migrations
+  private migrationManager: MigrationManager | null = null
+  private migrated = false
+  private migratePromise: Promise<BatchMigrationResult | null> | null = null
+
+  // PGLite initialization promise for deduplication
+  private initPGlitePromise: Promise<void> | null = null
+
+  // WAL facade for change capture
+  private walFacade: DOWALFacade | null = null
+  private walConfig: WALConfig = {}
+  private walInitPromise: Promise<void> | null = null
+
+  // Memory pressure manager for OOM protection
+  private memoryPressureManager: MemoryPressureManager | null = null
+  private memoryPressureConfig: MemoryPressureConfig = {}
+
+  constructor(
+    ctx: DurableObjectState,
+    env: Env,
+    config?: PostgresConfig,
+    authConfig?: PostgresDOAuthConfig,
+    walConfig?: WALConfig,
+    memoryPressureConfig?: MemoryPressureConfig
+  ) {
+    super(ctx, env)
+    this._authEnv = env as AuthEnv
+    this.config = config ?? {
+      database: env.POSTGRES_DEFAULT_DB ?? 'postgres',
+      preserveCase: false,
+    }
+
+    // Initialize modular managers
+    this.shutdownManager = new ShutdownManager({
+      gracePeriodMs: 30000,
+      drainCheckIntervalMs: 100,
+      closeTimeoutMs: 5000,
+      maxListeners: 100,
+    })
+
+    this.pluginManager = new PluginManager({
+      ...(this.config.plugins !== undefined && { plugins: this.config.plugins }),
+      ...(this.config.debug !== undefined && { debug: this.config.debug }),
+    })
+
+    this.authManager = new DOAuthManager(
+      authConfig ?? {
+        enabled: (env as AuthEnv).OAUTH_ENABLED === 'true',
+        oauthUrl: (env as AuthEnv).OAUTH_URL || 'https://oauth.do',
+        tokenCacheTTL: 60000,
+        allowAnonymous: false,
+      }
+    )
+
+    this.statsManager = new QueryStatsManager()
+
+    this.pgliteManager = new PGLiteManager({
+      database: this.config.database,
+      ...(this.config.debug !== undefined && { debug: this.config.debug }),
+      ...(this.config.plugins !== undefined && { plugins: this.config.plugins }),
+    })
+
+    this.walConfig = walConfig ?? {}
+    this.memoryPressureConfig = memoryPressureConfig ?? {}
+
+    // Initialize migration manager (executor set later after PGlite init)
+    this.migrationManager = new MigrationManager(ctx.storage, null, {
+      ...(this.config.migrations !== undefined && { migrations: this.config.migrations }),
+      ...(this.config.debug !== undefined && { debug: this.config.debug }),
+    })
+
+    // Initialize WAL facade
+    this.walFacade = new DOWALFacade(ctx, this.walConfig)
+
+    // Initialize memory pressure manager
+    this.memoryPressureManager = createMemoryPressureManager(this.memoryPressureConfig)
+
+    // Handle injected concerns from config
+    if (this.config.concerns) {
+      this.injectedAuthConcern = this.config.concerns.auth ?? null
+      this.injectedQueryExecutionConcern = this.config.concerns.queryExecution ?? null
+      this.injectedCDCConcern = this.config.concerns.cdc ?? null
+      this.injectedStorageOrchestrationConcern = this.config.concerns.storageOrchestration ?? null
+    }
+  }
+
+  // ============================================================
+  // Concern Injection Methods
+  // ============================================================
+
+  /**
+   * Set or replace a concern at runtime
+   * Used for testing and dynamic concern injection
+   */
+  setConcern(
+    name: 'auth' | 'queryExecution' | 'cdc' | 'storageOrchestration',
+    concern: unknown
+  ): void {
+    switch (name) {
+      case 'auth':
+        this.injectedAuthConcern = concern
+        break
+      case 'queryExecution':
+        this.injectedQueryExecutionConcern = concern
+        break
+      case 'cdc':
+        this.injectedCDCConcern = concern
+        break
+      case 'storageOrchestration':
+        this.injectedStorageOrchestrationConcern = concern
+        break
+    }
+  }
+
+  // ============================================================
+  // State and Configuration Methods
+  // ============================================================
+
+  /**
+   * Get the DurableObject state
+   */
+  getState(): DurableObjectState {
+    return this.ctx
+  }
+
+  /**
+   * Get the environment
+   */
+  getEnv(): Env {
+    return this.env
+  }
+
+  /**
+   * Get the environment as AuthEnv (for OAuth-related properties)
+   */
+  getAuthEnv(): AuthEnv {
+    return this._authEnv ?? (this.env as AuthEnv)
+  }
+
+  /**
+   * Check if PGlite is initialized
+   */
+  isInitialized(): boolean {
+    return this.pgliteManager.isInitialized()
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): PostgresConfig {
+    return { ...this.config }
+  }
+
+  /**
+   * Get query statistics
+   */
+  getStats(): QueryStats {
+    return this.statsManager.getStats()
+  }
+
+  /**
+   * Get uptime in milliseconds
+   */
+  getUptime(): number {
+    return this.statsManager.getUptime()
+  }
+
+  // ============================================================
+  // Authentication Methods (delegated to DOAuthManager or injected concern)
+  // ============================================================
+
+  /**
+   * Get authentication configuration
+   */
+  getAuthConfig(): PostgresDOAuthConfig {
+    // Use injected auth concern if available
+    if (
+      this.injectedAuthConcern &&
+      typeof (this.injectedAuthConcern as { getConfig?: () => PostgresDOAuthConfig }).getConfig ===
+        'function'
+    ) {
+      return (this.injectedAuthConcern as { getConfig: () => PostgresDOAuthConfig }).getConfig()
+    }
+    return this.authManager.getConfig()
+  }
+
+  /**
+   * Set the user ID for this DO instance (for user-scoped access)
+   */
+  setUserId(userId: string): void {
+    // Use injected auth concern if available
+    if (
+      this.injectedAuthConcern &&
+      typeof (this.injectedAuthConcern as { setUserId?: (id: string) => void }).setUserId ===
+        'function'
+    ) {
+      ;(this.injectedAuthConcern as { setUserId: (id: string) => void }).setUserId(userId)
+      return
+    }
+    this.authManager.setUserId(userId)
+  }
+
+  /**
+   * Get the user ID for this DO instance
+   */
+  getUserId(): string | undefined {
+    // Use injected auth concern if available
+    if (
+      this.injectedAuthConcern &&
+      typeof (this.injectedAuthConcern as { getUserId?: () => string | undefined }).getUserId ===
+        'function'
+    ) {
+      return (this.injectedAuthConcern as { getUserId: () => string | undefined }).getUserId()
+    }
+    return this.authManager.getUserId()
+  }
+
+  /**
+   * Validate a bearer token using oauth.do
+   */
+  async validateToken(token: string): Promise<TokenValidationResult> {
+    // Use injected auth concern if available
+    if (
+      this.injectedAuthConcern &&
+      typeof (
+        this.injectedAuthConcern as { validateToken?: (t: string) => Promise<TokenValidationResult> }
+      ).validateToken === 'function'
+    ) {
+      return (
+        this.injectedAuthConcern as { validateToken: (t: string) => Promise<TokenValidationResult> }
+      ).validateToken(token)
+    }
+    return this.authManager.validateToken(token)
+  }
+
+  /**
+   * Authenticate a request and return the user
+   * Returns null if authentication fails or is not required
+   */
+  async authenticateRequest(request: Request): Promise<AuthenticatedUser | null> {
+    // Use injected auth concern if available
+    if (
+      this.injectedAuthConcern &&
+      typeof (
+        this.injectedAuthConcern as {
+          authenticateRequest?: (r: Request) => Promise<AuthenticatedUser | null>
+        }
+      ).authenticateRequest === 'function'
+    ) {
+      return (
+        this.injectedAuthConcern as {
+          authenticateRequest: (r: Request) => Promise<AuthenticatedUser | null>
+        }
+      ).authenticateRequest(request)
+    }
+    return this.authManager.authenticateRequest(request)
+  }
+
+  // ============================================================
+  // WAL (Write-Ahead Log) Methods (delegated to DOWALFacade)
+  // ============================================================
+
+  /**
+   * Get the WAL facade instance
+   */
+  getWALFacade(): DOWALFacade {
+    if (!this.walFacade) {
+      this.walFacade = new DOWALFacade(this.ctx, this.walConfig)
+    }
+    return this.walFacade
+  }
+
+  /**
+   * Initialize the WAL manager (restores LSN from storage)
+   */
+  async initWAL(): Promise<void> {
+    if (this.walInitPromise) return this.walInitPromise
+    this.walInitPromise = this.getWALFacade().initialize()
+    return this.walInitPromise
+  }
+
+  /**
+   * Check if WAL capture is enabled
+   */
+  isWALEnabled(): boolean {
+    // Use injected CDC concern if available
+    if (
+      this.injectedCDCConcern &&
+      typeof (this.injectedCDCConcern as { isEnabled?: () => boolean }).isEnabled === 'function'
+    ) {
+      return (this.injectedCDCConcern as { isEnabled: () => boolean }).isEnabled()
+    }
+    return this.getWALFacade().isEnabled()
+  }
+
+  /**
+   * Enable or disable WAL capture
+   */
+  setWALEnabled(enabled: boolean): void {
+    this.getWALFacade().setEnabled(enabled)
+  }
+
+  /**
+   * Get WAL configuration
+   */
+  getWALConfig(): WALConfig {
+    return this.getWALFacade().getConfig()
+  }
+
+  /**
+   * Update WAL configuration
+   */
+  setWALConfig(config: Partial<WALConfig>): void {
+    this.getWALFacade().setConfig(config)
+  }
+
+  /**
+   * Get WAL buffer statistics
+   */
+  getWALStats(): WALBufferStats {
+    return this.getWALFacade().getStats()
+  }
+
+  /**
+   * Get current WAL LSN (Log Sequence Number)
+   */
+  getWALCurrentLsn(): bigint {
+    return this.getWALFacade().getCurrentLsn()
+  }
+
+  /**
+   * Add a listener for WAL entries
+   */
+  onWALEntry(listener: WALEventListener): () => void {
+    return this.getWALFacade().onEntry(listener)
+  }
+
+  /**
+   * Add a listener for WAL flush events
+   */
+  onWALFlush(listener: WALFlushListener): () => void {
+    return this.getWALFacade().onFlush(listener)
+  }
+
+  /**
+   * Flush WAL buffer to storage
+   */
+  async flushWAL(): Promise<WALFlushResult> {
+    return this.getWALFacade().flush()
+  }
+
+  /**
+   * Get buffered WAL entries (without flushing)
+   */
+  getWALBuffer(): WALEntry[] {
+    return this.getWALFacade().getBufferedEntries()
+  }
+
+  /**
+   * Read WAL entries from storage
+   */
+  async readWALFromStorage(fromLsn: bigint, limit?: number): Promise<WALEntry[]> {
+    return this.getWALFacade().readFromStorage(fromLsn, limit)
+  }
+
+  /**
+   * Capture a write operation to WAL
+   */
+  private captureWAL(
+    sql: string,
+    result: {
+      rows?: Record<string, unknown>[]
+      affectedRows?: number
+    }
+  ): WALEntry | null {
+    const walFacade = this.getWALFacade()
+    if (!walFacade.isEnabled()) {
+      return null
+    }
+    return walFacade.capture(sql, result)
+  }
+
+  // ============================================================
+  // Memory Pressure Methods (delegated to MemoryPressureManager)
+  // ============================================================
+
+  /**
+   * Get the memory pressure manager instance
+   */
+  getMemoryPressureManager(): MemoryPressureManager {
+    if (!this.memoryPressureManager) {
+      this.memoryPressureManager = createMemoryPressureManager(this.memoryPressureConfig)
+    }
+    return this.memoryPressureManager
+  }
+
+  /**
+   * Get current memory statistics
+   */
+  getMemoryStats(): MemoryStats {
+    return this.getMemoryPressureManager().getMemoryStats()
+  }
+
+  /**
+   * Get current memory pressure level
+   */
+  getMemoryPressureLevel(): MemoryPressureLevel {
+    return this.getMemoryPressureManager().getPressureLevel()
+  }
+
+  /**
+   * Check if memory pressure is at or above a certain level
+   */
+  isMemoryPressureAtOrAbove(level: MemoryPressureLevel): boolean {
+    return this.getMemoryPressureManager().isPressureAtOrAbove(level)
+  }
+
+  /**
+   * Get memory pressure configuration
+   */
+  getMemoryPressureConfig(): MemoryPressureConfig {
+    return this.getMemoryPressureManager().getConfig()
+  }
+
+  /**
+   * Update memory pressure configuration
+   */
+  setMemoryPressureConfig(config: Partial<MemoryPressureConfig>): void {
+    this.getMemoryPressureManager().setConfig(config)
+  }
+
+  /**
+   * Add a listener for memory pressure events
+   */
+  onMemoryPressure(listener: MemoryPressureListener): () => void {
+    return this.getMemoryPressureManager().onPressureChange(listener)
+  }
+
+  /**
+   * Get the number of memory pressure listeners
+   */
+  getMemoryPressureListenerCount(): number {
+    return this.getMemoryPressureManager().getListenerCount()
+  }
+
+  /**
+   * Start periodic memory pressure monitoring
+   */
+  startMemoryMonitoring(): void {
+    const manager = this.getMemoryPressureManager()
+    const pglite = this.pgliteManager.getInstanceOrNull()
+    if (pglite) {
+      manager.setPGlite(pglite)
+    }
+    manager.startMonitoring()
+  }
+
+  /**
+   * Stop periodic memory pressure monitoring
+   */
+  stopMemoryMonitoring(): void {
+    this.getMemoryPressureManager().stopMonitoring()
+  }
+
+  /**
+   * Manually check memory pressure and take action if needed
+   */
+  async checkMemoryPressure(): Promise<MemoryPressureEvent | null> {
+    return this.getMemoryPressureManager().checkMemoryPressure()
+  }
+
+  /**
+   * Manually unload the least important extension to free memory
+   */
+  async unloadExtensionForMemory(): Promise<MemoryPressureActionResult> {
+    const manager = this.getMemoryPressureManager()
+    const pglite = this.pgliteManager.getInstanceOrNull()
+    if (pglite) {
+      manager.setPGlite(pglite)
+    }
+    return manager.unloadLeastImportantExtension()
+  }
+
+  /**
+   * Get list of extensions that have been unloaded due to memory pressure
+   */
+  getUnloadedExtensions(): string[] {
+    return this.getMemoryPressureManager().getUnloadedExtensions()
+  }
+
+  /**
+   * Check if an extension was unloaded due to memory pressure
+   */
+  wasExtensionUnloaded(extensionName: string): boolean {
+    return this.getMemoryPressureManager().wasExtensionUnloaded(extensionName)
+  }
+
+  // ============================================================
+  // Shutdown Methods (delegated to ShutdownManager)
+  // ============================================================
+
+  /**
+   * Check if PGLite is responsive by running a simple query
+   */
+  async checkLiveness(): Promise<boolean> {
+    return this.pgliteManager.checkLiveness()
+  }
+
+  /**
+   * Get current shutdown status
+   */
+  getShutdownStatus(): ShutdownStatus {
+    return this.shutdownManager.getStatus()
+  }
+
+  /**
+   * Check if the DO is shutting down (draining or shutdown)
+   */
+  isShuttingDown(): boolean {
+    return this.shutdownManager.isShuttingDown()
+  }
+
+  /**
+   * Get the number of active queries
+   */
+  getActiveQueryCount(): number {
+    return this.shutdownManager.getActiveQueryCount()
+  }
+
+  /**
+   * Get active query info (for monitoring)
+   */
+  getActiveQueries(): Array<{ id: string; sql: string; durationMs: number }> {
+    return this.shutdownManager.getActiveQueries()
+  }
+
+  /**
+   * Configure shutdown behavior
+   */
+  setShutdownConfig(config: Partial<ShutdownConfig>): void {
+    this.shutdownManager.setConfig(config)
+  }
+
+  /**
+   * Get shutdown configuration
+   */
+  getShutdownConfig(): ShutdownConfig {
+    return this.shutdownManager.getConfig()
+  }
+
+  /**
+   * Get the current number of shutdown event listeners
+   */
+  getShutdownListenerCount(): number {
+    return this.shutdownManager.getListenerCount()
+  }
+
+  /**
+   * Add a shutdown event listener
+   */
+  onShutdownEvent(listener: ShutdownEventListener): () => void {
+    return this.shutdownManager.onShutdownEvent(listener)
+  }
+
+  /**
+   * Initiate graceful shutdown
+   */
+  async shutdown(config?: Partial<ShutdownConfig>): Promise<void> {
+    const pglite = this.pgliteManager.getInstanceOrNull()
+
+    // Create a WebSocket state adapter for the shutdown manager
+    const wsState = {
+      getWebSockets: () => {
+        try {
+          return this.ctx.getWebSockets()
+        } catch {
+          return []
+        }
+      },
+    }
+
+    await this.shutdownManager.shutdown(pglite, wsState, config)
+
+    // Stop memory monitoring
+    if (this.memoryPressureManager) {
+      this.memoryPressureManager.dispose()
+      this.memoryPressureManager = null
+    }
+
+    // Reset PGLite manager
+    this.pgliteManager.reset()
+  }
+
+  // ============================================================
+  // Migration Methods (delegated to MigrationManager)
+  // ============================================================
+
+  /**
+   * Get the migration manager instance
+   */
+  getMigrationManager(): MigrationManager {
+    if (!this.migrationManager) {
+      this.migrationManager = new MigrationManager(
+        this.ctx.storage,
+        this.pgliteManager.getInstanceOrNull(),
+        {
+          ...(this.config.migrations !== undefined && { migrations: this.config.migrations }),
+          ...(this.config.debug !== undefined && { debug: this.config.debug }),
+        }
+      )
+    }
+    return this.migrationManager
+  }
+
+  /**
+   * Get the current schema version from DO storage
+   */
+  async getSchemaVersion(): Promise<number> {
+    return this.getMigrationManager().getSchemaVersion()
+  }
+
+  /**
+   * Check if this is a fresh database (no schema version set)
+   */
+  async isFreshDatabase(): Promise<boolean> {
+    return this.getMigrationManager().isFreshDatabase()
+  }
+
+  /**
+   * Check if migrations have been applied this session
+   */
+  isMigrated(): boolean {
+    return this.migrated
+  }
+
+  /**
+   * Get the schema version manager
+   */
+  getSchemaVersionManager(): SchemaVersionManager | null {
+    return this.getMigrationManager().getSchemaVersionManager()
+  }
+
+  /**
+   * Get full schema version details including migration history
+   */
+  async getSchemaVersionDetails(): Promise<SchemaVersion> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const manager = this.getSchemaVersionManager()
+    if (!manager) {
+      throw new NotInitializedError('getting schema version details')
+    }
+
+    return manager.getSchemaVersion()
+  }
+
+  /**
+   * Compare current schema version against a target version
+   */
+  async compareSchemaVersion(targetVersion: number): Promise<VersionComparison> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const manager = this.getSchemaVersionManager()
+    if (!manager) {
+      throw new NotInitializedError('comparing schema version')
+    }
+
+    return manager.compareVersion(targetVersion)
+  }
+
+  /**
+   * Check if a specific migration has been applied
+   */
+  async isMigrationApplied(migrationId: string): Promise<boolean> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const manager = this.getSchemaVersionManager()
+    if (!manager) {
+      throw new NotInitializedError('checking migration status')
+    }
+
+    return manager.isMigrationApplied(migrationId)
+  }
+
+  /**
+   * Add a listener for migration events
+   */
+  onMigrationEvent(listener: MigrationEventListener): () => void {
+    const manager = this.getSchemaVersionManager()
+    if (manager) {
+      return manager.onMigrationEvent(listener)
+    }
+    return () => {}
+  }
+
+  /**
+   * Run a single migration
+   * @internal
+   */
+  private async runSingleMigration(
+    migration: MigrationInput,
+    index: number,
+    total: number,
+    onProgress?: (event: MigrationProgressEvent) => void
+  ): Promise<MigrationResult> {
+    const startTime = performance.now()
+    const pglite = this.pgliteManager.getInstance()
+
+    onProgress?.({
+      migration,
+      index,
+      total,
+      phase: 'starting',
+    })
+
+    try {
+      const currentVersion = await this.getSchemaVersion()
+      if (migration.version <= currentVersion) {
+        return {
+          success: true,
+          id: migration.id,
+          executionTimeMs: 0,
+          skipped: true,
+        }
+      }
+
+      onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'executing',
+      })
+
+      await pglite.query('BEGIN')
+      try {
+        if (pglite.exec) {
+          await pglite.exec(migration.sql)
+        } else {
+          const statements = migration.sql
+            .split(';')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+          for (const stmt of statements) {
+            await pglite.query(stmt)
+          }
+        }
+
+        await this.getMigrationManager().setSchemaVersion(migration.version)
+        await pglite.query('COMMIT')
+      } catch (error) {
+        await pglite.query('ROLLBACK')
+        throw error
+      }
+
+      const executionTimeMs = performance.now() - startTime
+
+      onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'completed',
+        durationMs: executionTimeMs,
+      })
+
+      return {
+        success: true,
+        id: migration.id,
+        executionTimeMs,
+      }
+    } catch (error) {
+      const executionTimeMs = performance.now() - startTime
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+
+      onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'failed',
+        durationMs: executionTimeMs,
+        error: errorMessage,
+      })
+
+      return {
+        success: false,
+        id: migration.id,
+        executionTimeMs,
+        error: errorMessage,
+      }
+    }
+  }
+
+  /**
+   * Run all pending migrations in sequence
+   */
+  async runMigrations(
+    migrations: MigrationInput[],
+    onProgress?: (event: MigrationProgressEvent) => void
+  ): Promise<BatchMigrationResult> {
+    const startTime = performance.now()
+    const fromVersion = await this.getSchemaVersion()
+
+    const sortedMigrations = [...migrations].sort((a, b) => a.version - b.version)
+    const pendingMigrations = sortedMigrations.filter((m) => m.version > fromVersion)
+
+    if (pendingMigrations.length === 0) {
+      return {
+        success: true,
+        fromVersion,
+        toVersion: fromVersion,
+        durationMs: 0,
+        results: [],
+        migrationsRun: 0,
+        migrationsSkipped: sortedMigrations.length,
+      }
+    }
+
+    const results: MigrationResult[] = []
+    let migrationsRun = 0
+    let migrationsSkipped = sortedMigrations.length - pendingMigrations.length
+
+    for (let i = 0; i < pendingMigrations.length; i++) {
+      const migration = pendingMigrations[i]
+      if (!migration) continue
+      const result = await this.runSingleMigration(migration, i, pendingMigrations.length, onProgress)
+      results.push(result)
+
+      if (result.skipped) {
+        migrationsSkipped++
+      } else if (result.success) {
+        migrationsRun++
+      } else {
+        const durationMs = performance.now() - startTime
+        const toVersion = await this.getSchemaVersion()
+
+        return {
+          success: false,
+          fromVersion,
+          toVersion,
+          durationMs,
+          results,
+          migrationsRun,
+          migrationsSkipped,
+        }
+      }
+    }
+
+    const durationMs = performance.now() - startTime
+    const toVersion = await this.getSchemaVersion()
+
+    return {
+      success: true,
+      fromVersion,
+      toVersion,
+      durationMs,
+      results,
+      migrationsRun,
+      migrationsSkipped,
+    }
+  }
+
+  /**
+   * Ensure database is migrated to latest version
+   */
+  async ensureMigrated(): Promise<BatchMigrationResult | null> {
+    if (this.migrated) {
+      return null
+    }
+
+    const migrations = this.config.migrations?.migrations
+    if (!migrations || migrations.length === 0) {
+      this.migrated = true
+      return null
+    }
+
+    if (this.migratePromise) {
+      return this.migratePromise
+    }
+
+    if (!this.pgliteManager.getInstanceOrNull()) {
+      throw new NotInitializedError('running migrations')
+    }
+
+    this.migratePromise = this.performMigrations()
+
+    try {
+      const result = await this.migratePromise
+      this.migrated = result!.success
+      return result!
+    } finally {
+      this.migratePromise = null
+    }
+  }
+
+  /**
+   * Internal migration implementation
+   */
+  private async performMigrations(): Promise<BatchMigrationResult> {
+    const migrationConfig = this.config.migrations!
+    const migrations = migrationConfig.migrations
+    const onProgress = migrationConfig.onProgress
+
+    return this.runMigrations(migrations, onProgress)
+  }
+
+  // ============================================================
+  // Plugin Management Methods (delegated to PluginManager)
+  // ============================================================
+
+  /**
+   * Get the last plugin load result (for diagnostics)
+   */
+  getLastPluginLoadResult() {
+    return this.pluginManager.getLastLoadResult()
+  }
+
+  /**
+   * List all available plugins with their status
+   */
+  async listPlugins(): Promise<import('./types').PluginStatus[]> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+    return this.pluginManager.listPlugins(this.pgliteManager.getInstance())
+  }
+
+  /**
+   * Get the status of a specific plugin
+   */
+  async getPluginStatus(name: PluginName): Promise<import('./types').PluginStatus | null> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+    return this.pluginManager.getPluginStatus(name, this.pgliteManager.getInstance())
+  }
+
+  /**
+   * Enable a plugin for this DO instance
+   */
+  async enablePlugin(
+    name: PluginName,
+    autoCreate: boolean = false
+  ): Promise<import('./types').PluginToggleResponse> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    // Update config
+    if (!this.config.plugins) {
+      this.config.plugins = {}
+    }
+    ;(this.config.plugins as Record<string, PluginValue>)[name] = { enabled: true, autoCreate }
+
+    return this.pluginManager.enablePlugin(name, this.pgliteManager.getInstance(), autoCreate)
+  }
+
+  /**
+   * Disable a plugin for this DO instance
+   */
+  async disablePlugin(name: PluginName): Promise<import('./types').PluginToggleResponse> {
+    if (this.config.plugins) {
+      ;(this.config.plugins as Record<string, PluginValue>)[name] = false
+    }
+    return this.pluginManager.disablePlugin(name)
+  }
+
+  /**
+   * Create an extension in the database
+   */
+  async createExtension(name: PluginName): Promise<import('./types').PluginToggleResponse> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+    return this.pluginManager.createExtension(name, this.pgliteManager.getInstance())
+  }
+
+  /**
+   * Drop an extension from the database
+   */
+  async dropExtension(
+    name: PluginName,
+    cascade: boolean = false
+  ): Promise<import('./types').PluginToggleResponse> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+    return this.pluginManager.dropExtension(name, this.pgliteManager.getInstance(), cascade)
+  }
+
+  // ============================================================
+  // Migration Strategy Methods
+  // ============================================================
+
+  /**
+   * Get the migration strategy from configuration
+   */
+  getMigrationStrategy(): MigrationStrategy {
+    return this.config.migrations?.strategy ?? 'on-create'
+  }
+
+  /**
+   * Get the current migration state from DO storage
+   */
+  async getMigrationState(): Promise<MigrationState | null> {
+    return (await this.ctx.storage.get<MigrationState>(MIGRATION_STATE_KEY)) ?? null
+  }
+
+  /**
+   * Update the migration state in DO storage
+   */
+  private async setMigrationState(state: MigrationState): Promise<void> {
+    await this.ctx.storage.put(MIGRATION_STATE_KEY, state)
+  }
+
+  /**
+   * Check if migrations need to run (for lazy migration strategy)
+   */
+  async needsLazyMigration(): Promise<boolean> {
+    const strategy = this.getMigrationStrategy()
+    if (strategy !== 'on-demand') {
+      return false
+    }
+
+    const migrations = this.config.migrations?.migrations
+    if (!migrations || migrations.length === 0) {
+      return false
+    }
+
+    if (this.migrated) {
+      return false
+    }
+
+    const migrationState = await this.getMigrationState()
+
+    if (!migrationState) {
+      return true
+    }
+
+    if (migrationState.status === 'completed') {
+      const highestVersion = Math.max(...migrations.map((m) => m.version))
+      return migrationState.version < highestVersion
+    }
+
+    return migrationState.status !== 'in-progress'
+  }
+
+  /**
+   * Run lazy migrations (on-demand strategy)
+   */
+  private async runLazyMigrations(): Promise<BatchMigrationResult | null> {
+    if (this.migrated) {
+      return null
+    }
+
+    const migrations = this.config.migrations?.migrations
+    if (!migrations || migrations.length === 0) {
+      this.migrated = true
+      return null
+    }
+
+    await this.setMigrationState({
+      status: 'in-progress',
+      version: await this.getSchemaVersion(),
+      lastAttemptAt: new Date().toISOString(),
+    })
+
+    const startTime = performance.now()
+
+    try {
+      const result = await this.runMigrations(migrations, this.config.migrations?.onProgress)
+
+      const durationMs = Math.round(performance.now() - startTime)
+
+      if (result.success) {
+        this.migrated = true
+        await this.setMigrationState({
+          status: 'completed',
+          version: result.toVersion,
+          lastAttemptAt: new Date().toISOString(),
+          durationMs,
+        })
+      } else {
+        const failedMigration = result.results.find((r) => !r.success)
+        await this.setMigrationState({
+          status: 'failed',
+          version: result.toVersion,
+          lastAttemptAt: new Date().toISOString(),
+          error: failedMigration?.error ?? 'Unknown error',
+          durationMs,
+        })
+      }
+
+      return result
+    } catch (error) {
+      const durationMs = Math.round(performance.now() - startTime)
+      await this.setMigrationState({
+        status: 'failed',
+        version: await this.getSchemaVersion(),
+        lastAttemptAt: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Unknown error',
+        durationMs,
+      })
+      throw error
+    }
+  }
+
+  /**
+   * Ensure migrations have run (for on-demand strategy)
+   */
+  async ensureMigratedForQuery(): Promise<BatchMigrationResult | null> {
+    if (!(await this.needsLazyMigration())) {
+      return null
+    }
+
+    if (this.migratePromise) {
+      return this.migratePromise
+    }
+
+    this.migratePromise = this.runLazyMigrations()
+
+    try {
+      return await this.migratePromise
+    } finally {
+      this.migratePromise = null
+    }
+  }
+
+  // ============================================================
+  // PGLite Initialization
+  // ============================================================
+
+  /**
+   * Get enabled plugins from configuration
+   */
+  protected async getEnabledPluginExtensions(): Promise<Record<string, unknown>> {
+    return this.pluginManager.loadEnabledExtensions()
+  }
+
+  /**
+   * Get the PGLite manager (for testing)
+   */
+  getPGLiteManager(): PGLiteManager {
+    return this.pgliteManager
+  }
+
+  /**
+   * Create a PGlite instance (overridable for testing)
+   * When mocked in tests, this should return the mock PGlite instance
+   */
+  protected async createPGliteInstance(): Promise<PGliteLike> {
+    await this.pgliteManager.initialize()
+    return this.pgliteManager.getInstance()
+  }
+
+  /**
+   * Run auto-create SQL for plugins that have autoCreate enabled
+   */
+  protected async runPluginAutoCreate(): Promise<void> {
+    const pglite = this.pgliteManager.getInstanceOrNull()
+    if (!pglite) return
+    await this.pluginManager.runAutoCreate(pglite)
+  }
+
+  /**
+   * Initialize PGlite and run auto-migrations if configured
+   * Safe to call multiple times - concurrent calls return the same promise
+   */
+  async initPGlite(): Promise<void> {
+    if (this.isInitialized()) {
+      return
+    }
+
+    // Return existing promise if initialization is already in progress
+    if (this.initPGlitePromise) {
+      return this.initPGlitePromise
+    }
+
+    // Create and store the initialization promise
+    this.initPGlitePromise = this.ctx.blockConcurrencyWhile(async () => {
+      if (this.isInitialized()) {
+        return
+      }
+
+      // Use createPGliteInstance which can be mocked in tests
+      const pglite = await this.createPGliteInstance()
+      // Inject the instance into the manager if it was created externally (e.g., by a mock)
+      if (!this.pgliteManager.isInitialized()) {
+        this.pgliteManager.injectInstance(pglite)
+      }
+
+      // Run auto-create for plugins
+      await this.runPluginAutoCreate()
+
+      // Determine migration strategy
+      const strategy = this.getMigrationStrategy()
+
+      // Only run migrations on init if strategy is 'on-create' (default)
+      if (strategy === 'on-create') {
+        const shouldAutoMigrate = this.config.migrations?.autoMigrate !== false
+        if (shouldAutoMigrate && this.config.migrations?.migrations?.length) {
+          const result = await this.ensureMigrated()
+          if (result && !result.success) {
+            console.error(
+              `[PostgresDO] Auto-migration failed: ${result.results.find((r) => !r.success)?.error}`
+            )
+          }
+        }
+      }
+
+      // Set PGlite reference on memory pressure manager for extension unloading
+      const pgliteForMemory = this.pgliteManager.getInstanceOrNull()
+      if (this.memoryPressureManager && pgliteForMemory) {
+        this.memoryPressureManager.setPGlite(pgliteForMemory)
+      }
+
+      // Start memory monitoring if enabled (default: enabled)
+      if (this.memoryPressureConfig.enabled !== false) {
+        this.getMemoryPressureManager().startMonitoring()
+      }
+    })
+
+    await this.initPGlitePromise
+  }
+
+  // ============================================================
+  // Query Execution
+  // ============================================================
+
+  /**
+   * Execute a single query
+   */
+  async executeQuery<T extends QueryResultRow = QueryResultRow>(
+    request: QueryRequest
+  ): Promise<QueryResponse<T>> {
+    if (this.shutdownManager.getStatus() === 'shutdown') {
+      throw new ShutdownError()
+    }
+
+    // Use injected query execution concern if available
+    if (
+      this.injectedQueryExecutionConcern &&
+      typeof (
+        this.injectedQueryExecutionConcern as {
+          executeQuery?: (
+            r: QueryRequest
+          ) => Promise<{
+            rows: T[]
+            fields: { name: string; dataTypeID: number }[]
+            rowCount: number
+            durationMs: number
+          }>
+        }
+      ).executeQuery === 'function'
+    ) {
+      const result = await (
+        this.injectedQueryExecutionConcern as {
+          executeQuery: (
+            r: QueryRequest
+          ) => Promise<{
+            rows: T[]
+            fields: { name: string; dataTypeID: number }[]
+            rowCount: number
+            durationMs: number
+          }>
+        }
+      ).executeQuery(request)
+      return {
+        rows: result.rows,
+        fields: result.fields as QueryField[],
+        rowCount: result.rowCount,
+        durationMs: result.durationMs,
+      }
+    }
+
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    await this.ensureMigratedForQuery()
+
+    const queryId = this.shutdownManager.trackQuery(request.sql)
+    const startTime = performance.now()
+
+    try {
+      let sql = request.sql
+      if (request.preserveCase ?? this.config.preserveCase) {
+        sql = preserveCase(sql)
+      }
+
+      const pglite = this.pgliteManager.getInstance()
+      const result = await pglite.query<T>(sql, request.params)
+      const durationMs = performance.now() - startTime
+
+      this.captureWAL(sql, {
+        rows: result.rows as Record<string, unknown>[],
+        ...(result.affectedRows !== undefined && { affectedRows: result.affectedRows }),
+      })
+
+      this.statsManager.recordQuery(durationMs, true)
+
+      return {
+        rows: result.rows,
+        fields: result.fields as QueryField[],
+        rowCount: result.affectedRows ?? result.rows.length,
+        durationMs,
+      }
+    } catch (error) {
+      const durationMs = performance.now() - startTime
+      this.statsManager.recordQuery(durationMs, false)
+      throw error
+    } finally {
+      this.shutdownManager.untrackQuery(queryId)
+    }
+  }
+
+  /**
+   * Execute a batch of queries
+   */
+  async executeBatch(request: BatchRequest): Promise<BatchResponse> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const startTime = performance.now()
+    const results: QueryResponse[] = []
+    const pglite = this.pgliteManager.getInstance()
+
+    if (request.transaction) {
+      await pglite.query('BEGIN')
+      try {
+        for (const query of request.queries) {
+          const result = await this.executeQuery(query)
+          results.push(result)
+        }
+        await pglite.query('COMMIT')
+      } catch (error) {
+        await pglite.query('ROLLBACK')
+        throw error
+      }
+    } else {
+      for (const query of request.queries) {
+        const result = await this.executeQuery(query)
+        results.push(result)
+      }
+    }
+
+    const durationMs = performance.now() - startTime
+
+    return {
+      results,
+      durationMs,
+    }
+  }
+
+  /**
+   * Handle incoming fetch requests
+   */
+  override async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+
+    if (url.pathname === '/ping') {
+      return new Response('pong', { status: 200 })
+    }
+
+    return new Response('Not Found', { status: 404 })
+  }
+
+  // ============================================================
+  // RPC Methods
+  // ============================================================
+
+  /**
+   * RPC: Execute a SQL query
+   */
+  async rpcQuery<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<RpcQueryResult<T>> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    await this.ensureMigratedForQuery()
+
+    const startTime = performance.now()
+
+    let finalSql = sql
+    if (this.config.preserveCase) {
+      finalSql = preserveCase(sql)
+    }
+
+    const pglite = this.pgliteManager.getInstance()
+    const result = await pglite.query<T>(finalSql, params)
+    const durationMs = performance.now() - startTime
+
+    this.statsManager.recordQuery(durationMs, true)
+
+    return {
+      rows: result.rows,
+      fields: result.fields as QueryField[],
+      rowCount: result.affectedRows ?? result.rows.length,
+      durationMs,
+    }
+  }
+
+  /**
+   * RPC: Execute a SQL query and return only the first row
+   */
+  async rpcQueryOne<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<T | null> {
+    const result = await this.rpcQuery<T>(sql, params)
+    return result.rows[0] ?? null
+  }
+
+  /**
+   * RPC: Execute a query and return a scalar value
+   */
+  async rpcQueryScalar<T = unknown>(sql: string, params?: unknown[]): Promise<T | null> {
+    const result = await this.rpcQuery(sql, params)
+    const row = result.rows[0]
+    if (!row) return null
+
+    const firstKey = Object.keys(row)[0]
+    return (firstKey ? row[firstKey] : null) as T
+  }
+
+  /**
+   * RPC: Execute a batch of queries
+   */
+  async rpcBatch(queries: RpcBatchQuery[]): Promise<RpcBatchResult> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const startTime = performance.now()
+    const results: RpcQueryResult[] = []
+
+    for (const query of queries) {
+      const result = await this.rpcQuery(query.sql, query.params)
+      results.push(result)
+    }
+
+    return {
+      results,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * RPC: Execute a batch of queries within a transaction
+   */
+  async rpcBatchTransaction(queries: RpcBatchQuery[]): Promise<RpcBatchResult> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const startTime = performance.now()
+    const results: RpcQueryResult[] = []
+    const pglite = this.pgliteManager.getInstance()
+
+    await pglite.query('BEGIN')
+
+    try {
+      for (const query of queries) {
+        const result = await this.rpcQuery(query.sql, query.params)
+        results.push(result)
+      }
+
+      await pglite.query('COMMIT')
+    } catch (error) {
+      await pglite.query('ROLLBACK')
+      throw error
+    }
+
+    return {
+      results,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * RPC: Start a transaction and return a TransactionRpcApi
+   */
+  async rpcTransaction(options?: RpcTransactionOptions): Promise<TransactionRpcApi> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    let beginSql = 'BEGIN'
+
+    if (options?.isolationLevel) {
+      beginSql += ` ISOLATION LEVEL ${options.isolationLevel}`
+    }
+
+    if (options?.readOnly) {
+      beginSql += ' READ ONLY'
+    }
+
+    const pglite = this.pgliteManager.getInstance()
+    await pglite.query(beginSql)
+
+    return new TransactionRpcApi(pglite)
+  }
+
+  /**
+   * RPC: Execute a SQL statement that doesn't return rows
+   */
+  async rpcExecute(
+    sql: string,
+    params?: unknown[]
+  ): Promise<{ rowCount: number; durationMs: number }> {
+    const result = await this.rpcQuery(sql, params)
+    return {
+      rowCount: result.rowCount,
+      durationMs: result.durationMs,
+    }
+  }
+
+  /**
+   * RPC: Get the PostgresRpcApi instance
+   */
+  async getRpcApi(): Promise<PostgresRpcApi> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    return new PostgresRpcApi(this.pgliteManager.getInstance(), this.config.database)
+  }
+
+  /**
+   * RPC: Health check
+   */
+  async rpcPing(): Promise<{ ok: true; durationMs: number }> {
+    if (!this.isInitialized()) {
+      await this.initPGlite()
+    }
+
+    const startTime = performance.now()
+    const pglite = this.pgliteManager.getInstance()
+    await pglite.query('SELECT 1')
+
+    return {
+      ok: true,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * RPC: Get database version
+   */
+  async rpcVersion(): Promise<string> {
+    const result = await this.rpcQueryScalar<string>('SELECT version()')
+    return result ?? 'unknown'
+  }
+
+  /**
+   * RPC: List all tables in the public schema
+   */
+  async rpcListTables(): Promise<string[]> {
+    const result = await this.rpcQuery<{ tablename: string }>(
+      `SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename`
+    )
+    return result.rows.map((r) => r.tablename)
+  }
+
+  /**
+   * RPC: Get table schema information
+   */
+  async rpcDescribeTable(tableName: string): Promise<
+    Array<{
+      column_name: string
+      data_type: string
+      is_nullable: boolean
+      column_default: string | null
+    }>
+  > {
+    const result = await this.rpcQuery<{
+      column_name: string
+      data_type: string
+      is_nullable: string
+      column_default: string | null
+    }>(
+      `SELECT column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = $1
+       ORDER BY ordinal_position`,
+      [tableName]
+    )
+
+    return result.rows.map((r) => ({
+      column_name: r.column_name,
+      data_type: r.data_type,
+      is_nullable: r.is_nullable === 'YES',
+      column_default: r.column_default,
+    }))
+  }
+
+  /**
+   * RPC: Get database statistics
+   */
+  async rpcGetStats(): Promise<{
+    queryCount: number
+    totalDurationMs: number
+    avgDurationMs: number
+    lastQueryAt: Date | null
+    uptime: number
+    shutdownStatus: ShutdownStatus
+  }> {
+    const stats = this.statsManager.getStats()
+    return {
+      queryCount: stats.queryCount,
+      totalDurationMs: stats.totalDurationMs,
+      avgDurationMs: stats.avgDurationMs,
+      lastQueryAt: stats.lastQueryAt ?? null,
+      uptime: this.getUptime(),
+      shutdownStatus: this.shutdownManager.getStatus(),
+    }
+  }
+}
+
+// ============================================================
+// Factory Functions
+// ============================================================
+
+/**
+ * Factory function to create PostgresDO with custom configuration
+ */
+export function createPostgresDO(
+  config: PostgresConfig,
+  authConfig?: PostgresDOAuthConfig,
+  walConfig?: WALConfig,
+  memoryPressureConfig?: MemoryPressureConfig
+): typeof PostgresDO {
+  return class extends PostgresDO {
+    constructor(state: DurableObjectState, env: Env) {
+      super(state, env, config, authConfig, walConfig, memoryPressureConfig)
+    }
+  }
+}
+
+/**
+ * Factory function to create an authenticated PostgresDO for user-scoped databases
+ */
+export function createAuthenticatedPostgresDO(
+  config: PostgresConfig,
+  authConfig: Omit<PostgresDOAuthConfig, 'enabled'> = {},
+  walConfig?: WALConfig,
+  memoryPressureConfig?: MemoryPressureConfig
+): typeof PostgresDO {
+  return createPostgresDO(
+    config,
+    {
+      ...authConfig,
+      enabled: true,
+    },
+    walConfig,
+    memoryPressureConfig
+  )
+}
+
+/**
+ * Factory function to create PostgresDO with WAL capture enabled
+ */
+export function createPostgresDOWithWAL(
+  config: PostgresConfig,
+  walConfig: WALConfig = { enabled: true },
+  authConfig?: PostgresDOAuthConfig,
+  memoryPressureConfig?: MemoryPressureConfig
+): typeof PostgresDO {
+  return createPostgresDO(config, authConfig, { enabled: true, ...walConfig }, memoryPressureConfig)
+}
+
+/**
+ * Factory function to create PostgresDO with memory pressure protection enabled
+ */
+export function createPostgresDOWithMemoryProtection(
+  config: PostgresConfig,
+  memoryPressureConfig: MemoryPressureConfig = { enabled: true, autoUnloadExtensions: true },
+  authConfig?: PostgresDOAuthConfig,
+  walConfig?: WALConfig
+): typeof PostgresDO {
+  return createPostgresDO(config, authConfig, walConfig, { enabled: true, ...memoryPressureConfig })
+}