@dexto/core 1.4.0 → 1.5.1

package/dist/storage/database/postgres-store.cjs

@@ -34,20 +34,89 @@ class PostgresStore {
   logger;
   async connect() {
     if (this.connected) return;
+    const connectionString = this.config.connectionString || this.config.url;
+    if (connectionString?.startsWith("$")) {
+      throw import_errors.StorageError.connectionFailed(
+        `PostgreSQL: Connection string contains unexpanded environment variable: ${connectionString}. Ensure the environment variable is set in your .env file.`
+      );
+    }
+    if (!connectionString) {
+      throw import_errors.StorageError.connectionFailed(
+        "PostgreSQL: No connection string provided. Set url or connectionString in database config."
+      );
+    }
+    const { schema, ...pgOptions } = this.config.options || {};
+    this.logger.info("Connecting to PostgreSQL database...");
     this.pool = new import_pg.Pool({
-      connectionString: this.config.connectionString || this.config.url,
+      connectionString,
       max: this.config.maxConnections || 20,
-      idleTimeoutMillis: this.config.idleTimeoutMillis || 3e4,
-      connectionTimeoutMillis: this.config.connectionTimeoutMillis || 2e3,
-      ...this.config.options
+      // Shorter idle timeout for serverless DBs (Neon) - connections go stale quickly
+      idleTimeoutMillis: this.config.idleTimeoutMillis || 1e4,
+      connectionTimeoutMillis: this.config.connectionTimeoutMillis || 1e4,
+      // Enable TCP keepalive to detect dead connections
+      keepAlive: true,
+      keepAliveInitialDelayMillis: 1e4,
+      ...pgOptions
     });
-    const client = await this.pool.connect();
+    this.pool.on("error", (err) => {
+      this.logger.warn(`PostgreSQL pool error (will retry on next query): ${err.message}`);
+    });
+    if (schema) {
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) {
+        throw import_errors.StorageError.connectionFailed(
+          `PostgreSQL: Invalid schema name "${schema}". Schema names must start with a letter or underscore and contain only alphanumeric characters and underscores.`
+        );
+      }
+      this.pool.on("connect", async (client2) => {
+        try {
+          await client2.query(`SET search_path TO "${schema}", public`);
+        } catch (err) {
+          this.logger.error(`Failed to set search_path to "${schema}": ${err}`);
+        }
+      });
+      this.logger.info(`Using custom schema: "${schema}"`);
+    }
+    let client;
     try {
+      client = await this.pool.connect();
       await client.query("SELECT NOW()");
+      if (schema) {
+        await this.createSchema(client, schema);
+      }
       await this.createTables(client);
       this.connected = true;
+      this.logger.info("PostgreSQL database connected successfully");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`PostgreSQL connection failed: ${errorMessage}`);
+      if (this.pool) {
+        await this.pool.end().catch(() => {
+        });
+        this.pool = null;
+      }
+      throw import_errors.StorageError.connectionFailed(`PostgreSQL: ${errorMessage}`);
     } finally {
-      client.release();
+      if (client) {
+        client.release();
+      }
+    }
+  }
+  /**
+   * Creates a PostgreSQL schema if it doesn't exist.
+   */
+  async createSchema(client, schemaName) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schemaName)) {
+      throw import_errors.StorageError.connectionFailed(
+        `PostgreSQL: Invalid schema name "${schemaName}". Schema names must start with a letter or underscore and contain only alphanumeric characters and underscores.`
+      );
+    }
+    try {
+      await client.query(`CREATE SCHEMA IF NOT EXISTS "${schemaName}"`);
+      this.logger.debug(`Schema "${schemaName}" ready`);
+    } catch (error) {
+      this.logger.warn(
+        `Could not create schema "${schemaName}": ${error}. Assuming it exists.`
+      );
     }
   }
   async disconnect() {
@@ -63,61 +132,54 @@ class PostgresStore {
   getStoreType() {
     return "postgres";
   }
-  // Core operations
+  // Core operations - all use withRetry for serverless DB resilience
   async get(key) {
-    this.checkConnection();
-    const client = await this.pool.connect();
     try {
-      const result = await client.query("SELECT value FROM kv WHERE key = $1", [key]);
-      return result.rows[0] ? result.rows[0].value : void 0;
+      return await this.withRetry("get", async (client) => {
+        const result = await client.query("SELECT value FROM kv WHERE key = $1", [key]);
+        return result.rows[0] ? result.rows[0].value : void 0;
+      });
     } catch (error) {
       throw import_errors.StorageError.readFailed(
         "get",
         error instanceof Error ? error.message : String(error),
         { key }
       );
-    } finally {
-      client.release();
     }
   }
   async set(key, value) {
-    this.checkConnection();
-    const client = await this.pool.connect();
     try {
-      await client.query(
-        "INSERT INTO kv (key, value, updated_at) VALUES ($1, $2, $3) ON CONFLICT (key) DO UPDATE SET value = $2, updated_at = $3",
-        [key, value, /* @__PURE__ */ new Date()]
-      );
+      await this.withRetry("set", async (client) => {
+        const jsonValue = JSON.stringify(value);
+        await client.query(
+          "INSERT INTO kv (key, value, updated_at) VALUES ($1, $2::jsonb, $3) ON CONFLICT (key) DO UPDATE SET value = $2::jsonb, updated_at = $3",
+          [key, jsonValue, /* @__PURE__ */ new Date()]
+        );
+      });
     } catch (error) {
       throw import_errors.StorageError.writeFailed(
         "set",
         error instanceof Error ? error.message : String(error),
         { key }
       );
-    } finally {
-      client.release();
     }
   }
   async delete(key) {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    await this.withRetry("delete", async (client) => {
       await client.query("BEGIN");
-      await client.query("DELETE FROM kv WHERE key = $1", [key]);
-      await client.query("DELETE FROM lists WHERE key = $1", [key]);
-      await client.query("COMMIT");
-    } catch (error) {
-      await client.query("ROLLBACK");
-      throw error;
-    } finally {
-      client.release();
-    }
+      try {
+        await client.query("DELETE FROM kv WHERE key = $1", [key]);
+        await client.query("DELETE FROM lists WHERE key = $1", [key]);
+        await client.query("COMMIT");
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    });
   }
   // List operations
   async list(prefix) {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    return await this.withRetry("list", async (client) => {
       const kvResult = await client.query("SELECT key FROM kv WHERE key LIKE $1", [
         `${prefix}%`
       ]);
@@ -130,41 +192,33 @@ class PostgresStore {
         ...listResult.rows.map((row) => row.key)
       ]);
       return Array.from(allKeys).sort();
-    } finally {
-      client.release();
-    }
+    });
   }
   async append(key, item) {
-    this.checkConnection();
-    const client = await this.pool.connect();
     try {
-      await client.query("INSERT INTO lists (key, item, created_at) VALUES ($1, $2, $3)", [
-        key,
-        item,
-        /* @__PURE__ */ new Date()
-      ]);
+      await this.withRetry("append", async (client) => {
+        const jsonItem = JSON.stringify(item);
+        await client.query(
+          "INSERT INTO lists (key, item, created_at) VALUES ($1, $2::jsonb, $3)",
+          [key, jsonItem, /* @__PURE__ */ new Date()]
+        );
+      });
     } catch (error) {
       throw import_errors.StorageError.writeFailed(
         "append",
         error instanceof Error ? error.message : String(error),
         { key }
       );
-    } finally {
-      client.release();
     }
   }
   async getRange(key, start, count) {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    return await this.withRetry("getRange", async (client) => {
       const result = await client.query(
         "SELECT item FROM lists WHERE key = $1 ORDER BY created_at ASC LIMIT $2 OFFSET $3",
         [key, count, start]
       );
       return result.rows.map((row) => row.item);
-    } finally {
-      client.release();
-    }
+    });
   }
   // Schema management
   async createTables(client) {
@@ -194,26 +248,74 @@ class PostgresStore {
       throw import_errors.StorageError.notConnected("PostgresStore");
     }
   }
+  /**
+   * Check if an error is a connection error that should trigger a retry.
+   * Common with serverless databases (Neon) where connections go stale.
+   */
+  isConnectionError(error) {
+    if (!(error instanceof Error)) return false;
+    const code = error.code;
+    return code === "ETIMEDOUT" || code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE" || code === "57P01" || // admin_shutdown
+    code === "57P02" || // crash_shutdown
+    code === "57P03" || // cannot_connect_now
+    error.message.includes("Connection terminated") || error.message.includes("connection lost");
+  }
+  /**
+   * Execute a database operation with automatic retry on connection errors.
+   * Handles serverless DB connection issues (Neon cold starts, stale connections).
+   */
+  async withRetry(operation, fn, maxRetries = 2) {
+    this.checkConnection();
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      let client;
+      try {
+        client = await this.pool.connect();
+        const result = await fn(client);
+        return result;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (client) {
+          client.release(true);
+          client = void 0;
+        }
+        if (this.isConnectionError(error) && attempt < maxRetries) {
+          this.logger.warn(
+            `PostgreSQL ${operation} failed with connection error (attempt ${attempt + 1}/${maxRetries + 1}): ${lastError.message}. Retrying...`
+          );
+          await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+          continue;
+        }
+        throw error;
+      } finally {
+        if (client) {
+          client.release();
+        }
+      }
+    }
+    throw lastError;
+  }
   // Advanced operations
+  /**
+   * Execute a callback within a database transaction.
+   * Note: On connection failure, the entire callback will be retried on a new connection.
+   * Ensure callback operations are idempotent or use this only for read operations.
+   */
   async transaction(callback) {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    return await this.withRetry("transaction", async (client) => {
       await client.query("BEGIN");
-      const result = await callback(client);
-      await client.query("COMMIT");
-      return result;
-    } catch (error) {
-      await client.query("ROLLBACK");
-      throw error;
-    } finally {
-      client.release();
-    }
+      try {
+        const result = await callback(client);
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    });
   }
   async getStats() {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    return await this.withRetry("getStats", async (client) => {
       const kvResult = await client.query("SELECT COUNT(*) as count FROM kv");
       const listResult = await client.query("SELECT COUNT(*) as count FROM lists");
       const sizeResult = await client.query(
@@ -225,19 +327,13 @@ class PostgresStore {
         listCount: parseInt(listResult.rows[0].count),
         totalSize: sizeResult.rows[0].size
       };
-    } finally {
-      client.release();
-    }
+    });
   }
   // Maintenance operations
   async vacuum() {
-    this.checkConnection();
-    const client = await this.pool.connect();
-    try {
+    await this.withRetry("vacuum", async (client) => {
       await client.query("VACUUM ANALYZE kv, lists");
-    } finally {
-      client.release();
-    }
+    });
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/storage/database/postgres-store.d.ts

@@ -14,6 +14,10 @@ export declare class PostgresStore implements Database {
     private logger;
     constructor(config: PostgresDatabaseConfig, logger: IDextoLogger);
     connect(): Promise<void>;
+    /**
+     * Creates a PostgreSQL schema if it doesn't exist.
+     */
+    private createSchema;
     disconnect(): Promise<void>;
     isConnected(): boolean;
     getStoreType(): string;
@@ -25,6 +29,21 @@ export declare class PostgresStore implements Database {
     getRange<T>(key: string, start: number, count: number): Promise<T[]>;
     private createTables;
     private checkConnection;
+    /**
+     * Check if an error is a connection error that should trigger a retry.
+     * Common with serverless databases (Neon) where connections go stale.
+     */
+    private isConnectionError;
+    /**
+     * Execute a database operation with automatic retry on connection errors.
+     * Handles serverless DB connection issues (Neon cold starts, stale connections).
+     */
+    private withRetry;
+    /**
+     * Execute a callback within a database transaction.
+     * Note: On connection failure, the entire callback will be retried on a new connection.
+     * Ensure callback operations are idempotent or use this only for read operations.
+     */
     transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>;
     getStats(): Promise<{
         kvCount: number;

package/dist/storage/database/postgres-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../../src/storage/database/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,MAAM,IAAI,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAMtC,OAAO,CAAC,MAAM;IALlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAe;gBAGjB,MAAM,EAAE,sBAAsB,EACtC,MAAM,EAAE,YAAY;IAKlB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAKhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAiB3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAe5D,YAAY;IA4B1B,OAAO,CAAC,eAAe;IAOjB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAgBxE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;IAsBI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAShC"}
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../../src/storage/database/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,MAAM,IAAI,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAMtC,OAAO,CAAC,MAAM;IALlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAe;gBAGjB,MAAM,EAAE,sBAAsB,EACtC,MAAM,EAAE,YAAY;IAKlB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+F9B;;OAEG;YACW,YAAY;IAmBpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAKhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAe3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAW5D,YAAY;IA4B1B,OAAO,CAAC,eAAe;IAMvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;;OAGG;YACW,SAAS;IA8CvB;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAcxE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;IAkBI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}