Merge pull request #636 from devforth/feature/AdminForth/1673/create-db_recover-option

fix: add option to recover Postgres connection pool after DB drops wi…

Author: SerVitasik

adminforth/dataConnectors/baseConnector.ts

@@ -44,7 +44,7 @@ export default class AdminForthBaseConnector implements IAdminForthDataSourceCon
     return this.client;
   }
 
-  setupClient(url: string): Promise<void> {
+  setupClient(url: string, options?: { recovery?: boolean }): Promise<void> {
     throw new Error('Method not implemented.');
   }
 

adminforth/dataConnectors/postgres.ts

@@ -16,20 +16,35 @@ types.setTypeParser(1082, (val) => val); // DATE
 
 class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDataSourceConnector {
 
-    async setupClient(url: string): Promise<void> {
+    async setupClient(url: string, options?: { recovery?: boolean }): Promise<void> {
         this.client = new Pool({
             connectionString: url
         });
-        try {
-            await this.client.connect();
-            this.client.on('error', async (err) => {
-                afLogger.error(`Postgres error: ${err.message} ${err.stack}`);
-                this.client.end();
-                await new Promise((resolve) => { setTimeout(resolve, 1000) });
-                this.setupClient(url);
+
+        const selfHeal = options?.recovery !== false;
+
+        if (selfHeal) {
+            this.client.on('error', (err) => {
+                afLogger.error(`Postgres pool idle client error (pool self-heals on next query): ${err.message} ${err.stack}`);
             });
-        } catch (e) {
-            afLogger.error(`Failed to connect to Postgres ${e}`);
+            try {
+                const client = await this.client.connect();
+                client.release();
+            } catch (e) {
+                afLogger.error(`Failed to connect to Postgres ${e}`);
+            }
+        } else {
+            try {
+                await this.client.connect();
+                this.client.on('error', async (err) => {
+                    afLogger.error(`Postgres error: ${err.message} ${err.stack}`);
+                    this.client.end();
+                    await new Promise((resolve) => { setTimeout(resolve, 1000) });
+                    this.setupClient(url, options);
+                });
+            } catch (e) {
+                afLogger.error(`Failed to connect to Postgres ${e}`);
+            }
         }
     }
 

adminforth/documentation/docs/tutorial/02-glossary.md

@@ -15,6 +15,25 @@ It used to:
 
 There might be several datasources in the system for various databases e.g. One datasource to Mongo DBs and one to Postgres DB. 
 
+### connectionRecovery
+
+For PostgreSQL datasources AdminForth keeps a connection pool. The optional `connectionRecovery` flag controls how the connector reacts when that connection drops (DB restart, failover, network blip, etc.):
+
+```ts
+dataSources: [
+  {
+    id: 'maindb',
+    url: `${process.env.DATABASE_URL}`,
+    connectionRecovery: true, // default
+  },
+],
+```
+
+- `true` (default, recommended) — **self-heal mode.** The pool recovers automatically: a dead idle connection is dropped and a fresh one is transparently opened on the next query, so the app keeps working without a manual restart. Queries that were in-flight at the moment of the outage will fail, but subsequent queries succeed once the database is back.
+- `false` — **legacy mode.** On a connection error the pool is destroyed and recreated after 1 second. If the outage outlasts that retry, the app can be left with a permanently dead pool and require a manual restart. Kept only for backward compatibility.
+
+This flag is currently honored by the PostgreSQL connector; other connectors rely on their driver's built-in recovery.
+
 ## resource
 
 A [Resource](/docs/api/Back/interfaces/AdminForthResource.md) is a AdminForth representation of a table or collection in database. One resource is one table in the database. Resource has `table` property which should be equal to the name of the table in the database.

adminforth/index.ts

@@ -513,7 +513,10 @@ class AdminForth implements IAdminForth {
 
     await Promise.all(Object.keys(this.connectors).map(async (dataSourceId) => {
       try {
-        await this.connectors[dataSourceId].setupClient(this.config.dataSources.find((ds) => ds.id === dataSourceId).url);
+        await this.connectors[dataSourceId].setupClient(
+          this.config.dataSources.find((ds) => ds.id === dataSourceId).url,
+          { recovery: this.config.dataSources.find((ds) => ds.id === dataSourceId).connectionRecovery !== false }
+        );
       } catch (e) {
         afLogger.error(`Error while connecting to datasource '${dataSourceId}': ${e}`);
       }

adminforth/types/Back.ts

@@ -273,8 +273,10 @@ export interface IAdminForthDataSourceConnector {
   /**
    * Function to setup client connection to database.
    * @param url URL to database. Examples: clickhouse://demo:demo@localhost:8125/demo
+   * @param options Optional connection options. `recovery` mirrors the dataSource
+   *   `connectionRecovery` flag (defaults to true when omitted).
    */
-  setupClient(url: string): Promise<void>;
+  setupClient(url: string, options?: { recovery?: boolean }): Promise<void>;
 
   /**
    * Function to get all tables from database.
@@ -1245,6 +1247,19 @@ export type AdminForthDataSource = {
     * - SQLite: `sqlite://<path>`
     */
   url: string,
+
+  /**
+   * Controls how the connector reacts to a dropped database connection.
+   * Currently honored by the PostgreSQL connector.
+   *
+   * - `true` (default): self-heal mode. The connection pool recovers automatically — when an
+   *   idle connection dies (DB restart, failover, network blip, etc.) it is dropped and a fresh
+   *   one is opened on the next query, so the app keeps working without a manual restart.
+   * - `false`: legacy mode. On a connection error the pool is destroyed and recreated after 1s.
+   *   If the outage outlasts that retry the app can be left with a permanently dead pool and
+   *   require a manual restart. Kept only for backward compatibility.
+   */
+  connectionRecovery?: boolean,
 }
 
 type AdminForthPageDeclaration = {