@dotdo/postgres 0.1.0

package/dist/worker/do.js

@@ -0,0 +1,1441 @@
+/**
+ * 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';
+/** DO storage key for migration state */
+const MIGRATION_STATE_KEY = '__postgres_migration_state__';
+import { PostgresRpcApi, TransactionRpcApi, } from './rpc';
+import { preserveCase } from './sql-transform';
+import { NotInitializedError, ShutdownError } from './errors';
+import { MigrationManager } from './migration-manager';
+import { DOWALFacade, } from './wal-facade';
+import { createMemoryPressureManager } from './memory-pressure';
+// Import modular managers
+import { ShutdownManager, } from './shutdown-manager';
+import { PluginManager } from './plugin-manager';
+import { DOAuthManager } from './do-auth-manager';
+import { QueryStatsManager } from './query-stats-manager';
+import { PGLiteManager } 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';
+/**
+ * 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 {
+    // Note: ctx and env are inherited from DurableObject<Env>
+    _authEnv = null;
+    config;
+    // Modular managers
+    shutdownManager;
+    pluginManager;
+    authManager;
+    statsManager;
+    pgliteManager;
+    // Injected concerns for dependency injection and testing
+    injectedAuthConcern = null;
+    injectedQueryExecutionConcern = null;
+    injectedCDCConcern = null;
+    // @ts-expect-error - Kept for future use in storage orchestration
+    injectedStorageOrchestrationConcern = null;
+    // Migration manager for schema migrations
+    migrationManager = null;
+    migrated = false;
+    migratePromise = null;
+    // PGLite initialization promise for deduplication
+    initPGlitePromise = null;
+    // WAL facade for change capture
+    walFacade = null;
+    walConfig = {};
+    walInitPromise = null;
+    // Memory pressure manager for OOM protection
+    memoryPressureManager = null;
+    memoryPressureConfig = {};
+    constructor(ctx, env, config, authConfig, walConfig, memoryPressureConfig) {
+        super(ctx, env);
+        this._authEnv = env;
+        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.OAUTH_ENABLED === 'true',
+            oauthUrl: env.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, concern) {
+        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() {
+        return this.ctx;
+    }
+    /**
+     * Get the environment
+     */
+    getEnv() {
+        return this.env;
+    }
+    /**
+     * Get the environment as AuthEnv (for OAuth-related properties)
+     */
+    getAuthEnv() {
+        return this._authEnv ?? this.env;
+    }
+    /**
+     * Check if PGlite is initialized
+     */
+    isInitialized() {
+        return this.pgliteManager.isInitialized();
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get query statistics
+     */
+    getStats() {
+        return this.statsManager.getStats();
+    }
+    /**
+     * Get uptime in milliseconds
+     */
+    getUptime() {
+        return this.statsManager.getUptime();
+    }
+    // ============================================================
+    // Authentication Methods (delegated to DOAuthManager or injected concern)
+    // ============================================================
+    /**
+     * Get authentication configuration
+     */
+    getAuthConfig() {
+        // Use injected auth concern if available
+        if (this.injectedAuthConcern &&
+            typeof this.injectedAuthConcern.getConfig ===
+                'function') {
+            return this.injectedAuthConcern.getConfig();
+        }
+        return this.authManager.getConfig();
+    }
+    /**
+     * Set the user ID for this DO instance (for user-scoped access)
+     */
+    setUserId(userId) {
+        // Use injected auth concern if available
+        if (this.injectedAuthConcern &&
+            typeof this.injectedAuthConcern.setUserId ===
+                'function') {
+            ;
+            this.injectedAuthConcern.setUserId(userId);
+            return;
+        }
+        this.authManager.setUserId(userId);
+    }
+    /**
+     * Get the user ID for this DO instance
+     */
+    getUserId() {
+        // Use injected auth concern if available
+        if (this.injectedAuthConcern &&
+            typeof this.injectedAuthConcern.getUserId ===
+                'function') {
+            return this.injectedAuthConcern.getUserId();
+        }
+        return this.authManager.getUserId();
+    }
+    /**
+     * Validate a bearer token using oauth.do
+     */
+    async validateToken(token) {
+        // Use injected auth concern if available
+        if (this.injectedAuthConcern &&
+            typeof this.injectedAuthConcern.validateToken === 'function') {
+            return this.injectedAuthConcern.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) {
+        // Use injected auth concern if available
+        if (this.injectedAuthConcern &&
+            typeof this.injectedAuthConcern.authenticateRequest === 'function') {
+            return this.injectedAuthConcern.authenticateRequest(request);
+        }
+        return this.authManager.authenticateRequest(request);
+    }
+    // ============================================================
+    // WAL (Write-Ahead Log) Methods (delegated to DOWALFacade)
+    // ============================================================
+    /**
+     * Get the WAL facade instance
+     */
+    getWALFacade() {
+        if (!this.walFacade) {
+            this.walFacade = new DOWALFacade(this.ctx, this.walConfig);
+        }
+        return this.walFacade;
+    }
+    /**
+     * Initialize the WAL manager (restores LSN from storage)
+     */
+    async initWAL() {
+        if (this.walInitPromise)
+            return this.walInitPromise;
+        this.walInitPromise = this.getWALFacade().initialize();
+        return this.walInitPromise;
+    }
+    /**
+     * Check if WAL capture is enabled
+     */
+    isWALEnabled() {
+        // Use injected CDC concern if available
+        if (this.injectedCDCConcern &&
+            typeof this.injectedCDCConcern.isEnabled === 'function') {
+            return this.injectedCDCConcern.isEnabled();
+        }
+        return this.getWALFacade().isEnabled();
+    }
+    /**
+     * Enable or disable WAL capture
+     */
+    setWALEnabled(enabled) {
+        this.getWALFacade().setEnabled(enabled);
+    }
+    /**
+     * Get WAL configuration
+     */
+    getWALConfig() {
+        return this.getWALFacade().getConfig();
+    }
+    /**
+     * Update WAL configuration
+     */
+    setWALConfig(config) {
+        this.getWALFacade().setConfig(config);
+    }
+    /**
+     * Get WAL buffer statistics
+     */
+    getWALStats() {
+        return this.getWALFacade().getStats();
+    }
+    /**
+     * Get current WAL LSN (Log Sequence Number)
+     */
+    getWALCurrentLsn() {
+        return this.getWALFacade().getCurrentLsn();
+    }
+    /**
+     * Add a listener for WAL entries
+     */
+    onWALEntry(listener) {
+        return this.getWALFacade().onEntry(listener);
+    }
+    /**
+     * Add a listener for WAL flush events
+     */
+    onWALFlush(listener) {
+        return this.getWALFacade().onFlush(listener);
+    }
+    /**
+     * Flush WAL buffer to storage
+     */
+    async flushWAL() {
+        return this.getWALFacade().flush();
+    }
+    /**
+     * Get buffered WAL entries (without flushing)
+     */
+    getWALBuffer() {
+        return this.getWALFacade().getBufferedEntries();
+    }
+    /**
+     * Read WAL entries from storage
+     */
+    async readWALFromStorage(fromLsn, limit) {
+        return this.getWALFacade().readFromStorage(fromLsn, limit);
+    }
+    /**
+     * Capture a write operation to WAL
+     */
+    captureWAL(sql, result) {
+        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() {
+        if (!this.memoryPressureManager) {
+            this.memoryPressureManager = createMemoryPressureManager(this.memoryPressureConfig);
+        }
+        return this.memoryPressureManager;
+    }
+    /**
+     * Get current memory statistics
+     */
+    getMemoryStats() {
+        return this.getMemoryPressureManager().getMemoryStats();
+    }
+    /**
+     * Get current memory pressure level
+     */
+    getMemoryPressureLevel() {
+        return this.getMemoryPressureManager().getPressureLevel();
+    }
+    /**
+     * Check if memory pressure is at or above a certain level
+     */
+    isMemoryPressureAtOrAbove(level) {
+        return this.getMemoryPressureManager().isPressureAtOrAbove(level);
+    }
+    /**
+     * Get memory pressure configuration
+     */
+    getMemoryPressureConfig() {
+        return this.getMemoryPressureManager().getConfig();
+    }
+    /**
+     * Update memory pressure configuration
+     */
+    setMemoryPressureConfig(config) {
+        this.getMemoryPressureManager().setConfig(config);
+    }
+    /**
+     * Add a listener for memory pressure events
+     */
+    onMemoryPressure(listener) {
+        return this.getMemoryPressureManager().onPressureChange(listener);
+    }
+    /**
+     * Get the number of memory pressure listeners
+     */
+    getMemoryPressureListenerCount() {
+        return this.getMemoryPressureManager().getListenerCount();
+    }
+    /**
+     * Start periodic memory pressure monitoring
+     */
+    startMemoryMonitoring() {
+        const manager = this.getMemoryPressureManager();
+        const pglite = this.pgliteManager.getInstanceOrNull();
+        if (pglite) {
+            manager.setPGlite(pglite);
+        }
+        manager.startMonitoring();
+    }
+    /**
+     * Stop periodic memory pressure monitoring
+     */
+    stopMemoryMonitoring() {
+        this.getMemoryPressureManager().stopMonitoring();
+    }
+    /**
+     * Manually check memory pressure and take action if needed
+     */
+    async checkMemoryPressure() {
+        return this.getMemoryPressureManager().checkMemoryPressure();
+    }
+    /**
+     * Manually unload the least important extension to free memory
+     */
+    async unloadExtensionForMemory() {
+        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() {
+        return this.getMemoryPressureManager().getUnloadedExtensions();
+    }
+    /**
+     * Check if an extension was unloaded due to memory pressure
+     */
+    wasExtensionUnloaded(extensionName) {
+        return this.getMemoryPressureManager().wasExtensionUnloaded(extensionName);
+    }
+    // ============================================================
+    // Shutdown Methods (delegated to ShutdownManager)
+    // ============================================================
+    /**
+     * Check if PGLite is responsive by running a simple query
+     */
+    async checkLiveness() {
+        return this.pgliteManager.checkLiveness();
+    }
+    /**
+     * Get current shutdown status
+     */
+    getShutdownStatus() {
+        return this.shutdownManager.getStatus();
+    }
+    /**
+     * Check if the DO is shutting down (draining or shutdown)
+     */
+    isShuttingDown() {
+        return this.shutdownManager.isShuttingDown();
+    }
+    /**
+     * Get the number of active queries
+     */
+    getActiveQueryCount() {
+        return this.shutdownManager.getActiveQueryCount();
+    }
+    /**
+     * Get active query info (for monitoring)
+     */
+    getActiveQueries() {
+        return this.shutdownManager.getActiveQueries();
+    }
+    /**
+     * Configure shutdown behavior
+     */
+    setShutdownConfig(config) {
+        this.shutdownManager.setConfig(config);
+    }
+    /**
+     * Get shutdown configuration
+     */
+    getShutdownConfig() {
+        return this.shutdownManager.getConfig();
+    }
+    /**
+     * Get the current number of shutdown event listeners
+     */
+    getShutdownListenerCount() {
+        return this.shutdownManager.getListenerCount();
+    }
+    /**
+     * Add a shutdown event listener
+     */
+    onShutdownEvent(listener) {
+        return this.shutdownManager.onShutdownEvent(listener);
+    }
+    /**
+     * Initiate graceful shutdown
+     */
+    async shutdown(config) {
+        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() {
+        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() {
+        return this.getMigrationManager().getSchemaVersion();
+    }
+    /**
+     * Check if this is a fresh database (no schema version set)
+     */
+    async isFreshDatabase() {
+        return this.getMigrationManager().isFreshDatabase();
+    }
+    /**
+     * Check if migrations have been applied this session
+     */
+    isMigrated() {
+        return this.migrated;
+    }
+    /**
+     * Get the schema version manager
+     */
+    getSchemaVersionManager() {
+        return this.getMigrationManager().getSchemaVersionManager();
+    }
+    /**
+     * Get full schema version details including migration history
+     */
+    async getSchemaVersionDetails() {
+        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) {
+        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) {
+        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) {
+        const manager = this.getSchemaVersionManager();
+        if (manager) {
+            return manager.onMigrationEvent(listener);
+        }
+        return () => { };
+    }
+    /**
+     * Run a single migration
+     * @internal
+     */
+    async runSingleMigration(migration, index, total, onProgress) {
+        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, onProgress) {
+        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 = [];
+        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() {
+        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
+     */
+    async performMigrations() {
+        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() {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        return this.pluginManager.listPlugins(this.pgliteManager.getInstance());
+    }
+    /**
+     * Get the status of a specific plugin
+     */
+    async getPluginStatus(name) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        return this.pluginManager.getPluginStatus(name, this.pgliteManager.getInstance());
+    }
+    /**
+     * Enable a plugin for this DO instance
+     */
+    async enablePlugin(name, autoCreate = false) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        // Update config
+        if (!this.config.plugins) {
+            this.config.plugins = {};
+        }
+        ;
+        this.config.plugins[name] = { enabled: true, autoCreate };
+        return this.pluginManager.enablePlugin(name, this.pgliteManager.getInstance(), autoCreate);
+    }
+    /**
+     * Disable a plugin for this DO instance
+     */
+    async disablePlugin(name) {
+        if (this.config.plugins) {
+            ;
+            this.config.plugins[name] = false;
+        }
+        return this.pluginManager.disablePlugin(name);
+    }
+    /**
+     * Create an extension in the database
+     */
+    async createExtension(name) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        return this.pluginManager.createExtension(name, this.pgliteManager.getInstance());
+    }
+    /**
+     * Drop an extension from the database
+     */
+    async dropExtension(name, cascade = false) {
+        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() {
+        return this.config.migrations?.strategy ?? 'on-create';
+    }
+    /**
+     * Get the current migration state from DO storage
+     */
+    async getMigrationState() {
+        return (await this.ctx.storage.get(MIGRATION_STATE_KEY)) ?? null;
+    }
+    /**
+     * Update the migration state in DO storage
+     */
+    async setMigrationState(state) {
+        await this.ctx.storage.put(MIGRATION_STATE_KEY, state);
+    }
+    /**
+     * Check if migrations need to run (for lazy migration strategy)
+     */
+    async needsLazyMigration() {
+        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)
+     */
+    async runLazyMigrations() {
+        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() {
+        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
+     */
+    async getEnabledPluginExtensions() {
+        return this.pluginManager.loadEnabledExtensions();
+    }
+    /**
+     * Get the PGLite manager (for testing)
+     */
+    getPGLiteManager() {
+        return this.pgliteManager;
+    }
+    /**
+     * Create a PGlite instance (overridable for testing)
+     * When mocked in tests, this should return the mock PGlite instance
+     */
+    async createPGliteInstance() {
+        await this.pgliteManager.initialize();
+        return this.pgliteManager.getInstance();
+    }
+    /**
+     * Run auto-create SQL for plugins that have autoCreate enabled
+     */
+    async runPluginAutoCreate() {
+        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() {
+        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(request) {
+        if (this.shutdownManager.getStatus() === 'shutdown') {
+            throw new ShutdownError();
+        }
+        // Use injected query execution concern if available
+        if (this.injectedQueryExecutionConcern &&
+            typeof this.injectedQueryExecutionConcern.executeQuery === 'function') {
+            const result = await this.injectedQueryExecutionConcern.executeQuery(request);
+            return {
+                rows: result.rows,
+                fields: result.fields,
+                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(sql, request.params);
+            const durationMs = performance.now() - startTime;
+            this.captureWAL(sql, {
+                rows: result.rows,
+                ...(result.affectedRows !== undefined && { affectedRows: result.affectedRows }),
+            });
+            this.statsManager.recordQuery(durationMs, true);
+            return {
+                rows: result.rows,
+                fields: result.fields,
+                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) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        const startTime = performance.now();
+        const results = [];
+        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
+     */
+    async fetch(request) {
+        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(sql, params) {
+        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(finalSql, params);
+        const durationMs = performance.now() - startTime;
+        this.statsManager.recordQuery(durationMs, true);
+        return {
+            rows: result.rows,
+            fields: result.fields,
+            rowCount: result.affectedRows ?? result.rows.length,
+            durationMs,
+        };
+    }
+    /**
+     * RPC: Execute a SQL query and return only the first row
+     */
+    async rpcQueryOne(sql, params) {
+        const result = await this.rpcQuery(sql, params);
+        return result.rows[0] ?? null;
+    }
+    /**
+     * RPC: Execute a query and return a scalar value
+     */
+    async rpcQueryScalar(sql, params) {
+        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);
+    }
+    /**
+     * RPC: Execute a batch of queries
+     */
+    async rpcBatch(queries) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        const startTime = performance.now();
+        const results = [];
+        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) {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        const startTime = performance.now();
+        const results = [];
+        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) {
+        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, params) {
+        const result = await this.rpcQuery(sql, params);
+        return {
+            rowCount: result.rowCount,
+            durationMs: result.durationMs,
+        };
+    }
+    /**
+     * RPC: Get the PostgresRpcApi instance
+     */
+    async getRpcApi() {
+        if (!this.isInitialized()) {
+            await this.initPGlite();
+        }
+        return new PostgresRpcApi(this.pgliteManager.getInstance(), this.config.database);
+    }
+    /**
+     * RPC: Health check
+     */
+    async rpcPing() {
+        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() {
+        const result = await this.rpcQueryScalar('SELECT version()');
+        return result ?? 'unknown';
+    }
+    /**
+     * RPC: List all tables in the public schema
+     */
+    async rpcListTables() {
+        const result = await this.rpcQuery(`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) {
+        const result = await this.rpcQuery(`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() {
+        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, authConfig, walConfig, memoryPressureConfig) {
+    return class extends PostgresDO {
+        constructor(state, env) {
+            super(state, env, config, authConfig, walConfig, memoryPressureConfig);
+        }
+    };
+}
+/**
+ * Factory function to create an authenticated PostgresDO for user-scoped databases
+ */
+export function createAuthenticatedPostgresDO(config, authConfig = {}, walConfig, memoryPressureConfig) {
+    return createPostgresDO(config, {
+        ...authConfig,
+        enabled: true,
+    }, walConfig, memoryPressureConfig);
+}
+/**
+ * Factory function to create PostgresDO with WAL capture enabled
+ */
+export function createPostgresDOWithWAL(config, walConfig = { enabled: true }, authConfig, memoryPressureConfig) {
+    return createPostgresDO(config, authConfig, { enabled: true, ...walConfig }, memoryPressureConfig);
+}
+/**
+ * Factory function to create PostgresDO with memory pressure protection enabled
+ */
+export function createPostgresDOWithMemoryProtection(config, memoryPressureConfig = { enabled: true, autoUnloadExtensions: true }, authConfig, walConfig) {
+    return createPostgresDO(config, authConfig, walConfig, { enabled: true, ...memoryPressureConfig });
+}
+//# sourceMappingURL=do.js.map