Merge branch 'next' of github.com:devforth/adminforth into next

Author: yaroslav8765

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/documentation/docs/tutorial/08-Plugins/17-bulk-ai-flow.md

@@ -283,6 +283,31 @@ new BulkAiFlowPlugin({
 }),
 ```
 
+## Image generation quality
+
+`ImageGenerationAdapterOpenAI` accepts an `extraParams` object that is passed directly to the OpenAI API. The most useful option here is `quality`, which controls the fidelity and cost of each generated image:
+
+| Value | Description |
+|-------|-------------|
+| `'low'` | Fastest generation, lowest cost. Good for drafts or high-volume batch jobs where speed matters more than visual fidelity. |
+| `'medium'` | Balanced quality and speed. A sensible default for most use cases. |
+| `'high'` | Best image quality, slowest and most expensive. Use for final promotional assets or when visual detail is critical. |
+
+```ts
+new ImageGenerationAdapterOpenAI({
+  openAiApiKey: process.env.OPENAI_API_KEY as string,
+  model: 'gpt-image-1',
+  //diff-add
+  extraParams: {
+  //diff-add
+    quality: 'low', // 'low' | 'medium' | 'high'
+  //diff-add
+  },
+}),
+```
+
+> ☝️ `'low'` quality is a great starting point when processing large datasets — you can always re-run generation with `'high'` for selected records once you're happy with the prompts.
+
 ## Rate Limiting and Best Practices
 
 - Use `rateLimit` for individual image generation operations and for the bulk image generation
@@ -429,6 +454,21 @@ If you are processing large sets of data, you might want to limit the number of
 
 And there won't be more than 5 parallel requests being handled.
 
+## Controlling page size in the generation dialog
+
+When users trigger bulk generation, records are displayed as cards in a paginated dialog. By default, 6 cards are shown per page. Use `pageSize` to tune this — lower values help when cards contain large images or long text, keeping the dialog fast and reviewable:
+
+```ts
+new BulkAiFlowPlugin({
+  actionName: 'Generate description and Price',
+
+  //diff-add
+  pageSize: 10, // default is 6
+
+  // ...
+}),
+```
+
 ## Confirming long-running generations
 
 For very large datasets, you can pause generation at specific checkpoints so users can review results before continuing.

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 = {