@bkmj/node-red-contrib-odbcmj 2.4.1 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Node-RED Contrib ODBC MJ
 
-A powerful and robust Node-RED node to connect to any ODBC data source. It features connection pooling, advanced retry logic, secure credential management, dynamic query sources, and result set streaming.
+A powerful and robust Node-RED node to connect to any ODBC data source. It features connection pooling, advanced retry logic, secure credential management, dynamic query sources, result set streaming, and configurable timeouts.
 
 This node is a fork with significant enhancements to provide stability and advanced features for enterprise use cases.
 
@@ -11,10 +11,11 @@ This node is a fork with significant enhancements to provide stability and advan
 -   **Secure Credential Storage**: Passwords are saved using Node-RED's built-in credential system.
 -   **Connection Tester**: Instantly validate your connection settings from the configuration panel.
 -   **Dynamic Inputs**: Source your SQL query and parameters from message properties, flow/global context, or environment variables.
--   **Advanced Retry Logic**: Automatically handles connection errors with configurable delays and retries to ensure flow resilience.
--   **Result Streaming**: Process queries with millions of rows without exhausting memory by streaming results as chunks.
+-   **Intelligent Error Handling & Retry Logic**: Differentiates between SQL errors and actual connection problems. Automatically handles connection errors with configurable delays and retries to ensure flow resilience.
+-   **Result Streaming**: Process queries with millions of rows without exhausting memory by streaming results as chunks, with a clear completion signal.
+-   **Configurable Timeouts**: Set timeouts for login, query execution, and internal close operations to prevent hangs.
+-   **Optional Fast Shutdown**: Provides a "fire-and-forget" option for pool closing to handle problematic drivers during Node-RED shutdown/deploy.
 -   **Syntax Checker**: Optionally parse the SQL query to validate its structure.
--   **Query Timeout**: Configure a timeout for query execution to prevent indefinite hangs.
 
 ---
 
@@ -26,8 +27,6 @@ A configuration node that manages the connection to your database.
 
 #### Connection Modes
 
-Version 2.0 introduces two ways to configure your connection:
-
 ##### 1. Structured Fields Mode (Recommended)
 
 This is the easiest and most secure way to set up a connection for common databases.
@@ -55,15 +54,25 @@ A **Test Connection** button in the configuration panel allows you to instantly
 -   **`Increment Pool Size`** `<number>` (optional): The number of connections to create when the pool is exhausted. Default: 5.
 -   **`Max Pool Size`** `<number>` (optional): The maximum number of connections allowed in the pool. Default: 15.
 -   **`Shrink Pool`** `<boolean>` (optional): If checked, reduces the number of connections to `Initial Pool Size` when they are returned to the pool if the pool has grown. Default: true.
--   **`Idle Timeout`** `<number>` (optional): The number of seconds for a connection in the pool to remain idle before closing. Default: 3 seconds. (Refers to the `connectionTimeout` property of the `odbc` library's pool options).
+-   **`Idle Timeout`** `<number>` (optional): The number of seconds for a connection in the pool to remain idle before closing. Default: 3 seconds. (Refers to the `connectionTimeout` property of the `odbc` library's pool options, converted to seconds).
 -   **`Login Timeout`** `<number>` (optional): The number of seconds for an attempt to establish a new connection to succeed. Default: 5 seconds.
 -   **`Query Timeout`** `<number>` (optional): The number of seconds for a query to execute before timing out. A value of **0** means infinite or uses the driver/database default. Default: 0 seconds.
 
 #### Error Handling & Retry
 
--   **`Retry with fresh connection`** `<boolean>` (optional): If a query fails using a connection from the pool, the node will try once more with a brand new, direct connection. If this succeeds, the entire connection pool is reset to clear any potentially stale connections. Default: false.
--   **`Retry Delay`** `<number>` (optional): If all immediate attempts (pooled and, if enabled, fresh connection) fail, this sets a delay in seconds before another retry is attempted for the incoming message. A value of **0** disables this timed retry mechanism. Default: 5.
--   **`Retry on new message`** `<boolean>` (optional): If the node is waiting for a timed retry (due to `Retry Delay`), a new incoming message can, if this is checked, override the timer and trigger an immediate retry of the *original* message that failed. Default: true.
+The node attempts to distinguish between errors related to the SQL query itself (syntax, permissions) and actual connection problems. Connection retry mechanisms are primarily invoked for suspected connection issues.
+
+-   **`Retry with fresh connection`** `<boolean>` (optional): If a query fails and a basic connectivity test (e.g., `SELECT 1`) also suggests a problem with the current pooled connection, the node will try once more with a brand new, direct connection. If this second attempt (including its own successful basic connectivity test followed by the user's query) succeeds, the entire connection pool is reset to clear any potentially stale connections. Default: false.
+-   **`Retry Delay`** `<number>` (optional): If all immediate attempts fail and the problem is diagnosed as a *connection issue* (e.g., the `SELECT 1` test fails on both pooled and fresh connections), this sets a delay in seconds before another attempt to process the incoming message is made (using the pool again). A value of **0** disables this timed retry mechanism for connection issues. Default: 5.
+-   **`Retry on new message`** `<boolean>` (optional): If the node is waiting for a timed retry (due to `Retry Delay` for a connection issue), a new incoming message can, if this is checked, override the timer and trigger an immediate retry of the *original* message that failed. Default: true.
+
+#### Shutdown Options
+
+-   **`Fast close (Fire-and-forget)`** `<boolean>` (optional):
+    -   **Warning:** When checked, Node-RED will not wait for the connection pool to properly close during a deploy or shutdown.
+    -   This option can prevent Node-RED from hanging if specific ODBC drivers have issues closing connections quickly.
+    -   However, enabling this may result in orphaned connections on the database server, potentially consuming server resources.
+    -   It is recommended to leave this unchecked unless you are experiencing hangs during Node-RED deploys or shutdowns related to this config node. Default: false.
 
 #### Advanced
 
@@ -98,8 +107,8 @@ To make the node highly flexible, the SQL query and its parameters can be source
 
 For queries that return a large number of rows, streaming prevents high memory usage.
 
--   **`Stream Results`** `<boolean>`: Enables or disables streaming mode. When enabled, the node will output multiple messages, one for each chunk of rows. Default: false.
--   **`Chunk Size`** `<number>`: The number of rows to include in each output message. A value of `1` means one message will be sent for every single row. Default: 1.
+-   **`Stream Results`** `<boolean>`: Enables or disables streaming mode. When enabled, the node will output multiple messages. Default: false.
+-   **`Chunk Size`** `<number>`: When streaming, this is the number of rows to include in each data message. A value of `1` means one message will be sent for every single row. Default: 1.
 
 ##### Streaming Output Format
 

package/odbc.html

@@ -17,12 +17,13 @@
             incrementSize: { value: 5, validate: RED.validators.number(true) },
             maxSize: { value: 15, validate: RED.validators.number(true) },
             shrink: { value: true },
-            connectionTimeout: { value: 3, validate: RED.validators.number(true) }, // Idle timeout for connections in pool (odbc lib specific)
-            loginTimeout: { value: 5, validate: RED.validators.number(true) },      // Login timeout for new connections
-            queryTimeoutSeconds: { value: 0, validate: RED.validators.number(true) }, // NOUVEAU: Timeout pour les requêtes
+            connectionTimeout: { value: 3, validate: RED.validators.number(true) }, 
+            loginTimeout: { value: 5, validate: RED.validators.number(true) },      
+            queryTimeoutSeconds: { value: 0, validate: RED.validators.number(true) }, 
             retryFreshConnection: { value: false },
             retryDelay: { value: 5, validate: RED.validators.number(true) },
             retryOnMsg: { value: true },
+            fireAndForgetOnClose: { value: false }, // NOUVELLE OPTION
             syntaxtick: { value: false },
             syntax: { value: "mysql" },
         },
@@ -32,6 +33,11 @@
         oneditprepare: function () {
             var node = this;
 
+            // Initialiser tous les accordéons comme repliés par défaut
+            $('.form-section-content').hide();
+            $('.form-section-header').removeClass('expanded');
+
+
             $('.form-section-header').on('click', function() {
                 $(this).toggleClass('expanded');
                 $(this).next('.form-section-content').slideToggle();
@@ -80,9 +86,8 @@
                         RED.notify("Le champ 'Server' est requis pour le test.", {type: "warning", timeout: 3000});
                         return;
                     }
-                    if ($("#node-config-input-password").val() === "" && $("#node-config-input-user").val().trim() !== "") {
-                        RED.notify("Note: Pour tester une connexion structurée avec mot de passe, veuillez le (re)saisir.", {type: "info", timeout: 4500});
-                        // On ne bloque pas, l'utilisateur peut vouloir tester une connexion sans mot de passe si le user est optionnel
+                    if ($("#node-config-input-user").val().trim() !== "" && $("#node-config-input-password").val() === "") {
+                        RED.notify("Test avec utilisateur et mot de passe vide. Si un mot de passe est habituellement requis, veuillez le (re)saisir.", {type: "info", timeout: 4500});
                     }
                 } else { // Mode 'string'
                     var connStr = $("#node-config-input-connectionString").val().trim();
@@ -140,9 +145,10 @@
 
 <style>
     .form-section-header { cursor: pointer; padding: 5px; border-bottom: 1px solid #ddd; margin-bottom: 10px; user-select: none; }
-    .form-section-header i.fa-caret-right { transition: transform 0.2s ease-in-out; }
+    .form-section-header i.fa-caret-right { transition: transform 0.2s ease-in-out; margin-right: 5px; }
     .form-section-header.expanded i.fa-caret-right { transform: rotate(90deg); }
-    .form-section-content { padding-left: 20px; }
+    .form-section-content { padding-left: 20px; /* Sera géré par slideToggle, display:none initialement */ }
+    .form-tips { font-size: smaller; color: #777; display: block; margin-top: 2px; }
 </style>
 
 <script type="text/html" data-template-name="odbc config">
@@ -206,7 +212,7 @@
     <hr/>
     
     <div class="form-section-header"><h4><i class="fa fa-caret-right"></i> <i class="fa fa-sitemap"></i> Pool & Connection Options</h4></div>
-    <div class="form-section-content" style="display: none;">
+    <div class="form-section-content">
         <div class="form-row">
             <label for="node-config-input-initialSize"><i class="fa fa-play"></i> Initial Pool Size</label>
             <input type="number" id="node-config-input-initialSize" placeholder="5" />
@@ -222,19 +228,19 @@
         <div class="form-row">
             <label for="node-config-input-shrink"><i class="fa fa-compress"></i> Shrink Pool</label>
             <input type="checkbox" id="node-config-input-shrink" style="margin-left:0px; vertical-align:top; width:auto !important;" />
-            <span class="form-tips" style="font-size: smaller;">Reduce pool to initial size when connections are returned.</span>
+            <span class="form-tips">Reduce pool to initial size when connections are returned.</span>
         </div>
         <div class="form-row">
             <label for="node-config-input-connectionTimeout"><i class="fa fa-clock-o"></i> Idle Timeout</label>
             <input type="number" id="node-config-input-connectionTimeout" placeholder="3" style="width: 80px;"/>
             <span style="margin-left: 5px;">seconds</span>
-            <span class="form-tips" style="font-size: smaller;">For connections in pool.</span>
+            <span class="form-tips">For connections in pool.</span>
         </div>
         <div class="form-row">
             <label for="node-config-input-loginTimeout"><i class="fa fa-sign-in"></i> Login Timeout</label>
             <input type="number" id="node-config-input-loginTimeout" placeholder="5" style="width: 80px;" />
             <span style="margin-left: 5px;">seconds</span>
-            <span class="form-tips" style="font-size: smaller;">For establishing new connections.</span>
+            <span class="form-tips">For establishing new connections.</span>
         </div>
         <div class="form-row">
             <label for="node-config-input-queryTimeoutSeconds"><i class="fa fa-hourglass-half"></i> Query Timeout</label>
@@ -244,11 +250,11 @@
     </div>
     
     <div class="form-section-header"><h4><i class="fa fa-caret-right"></i> <i class="fa fa-exclamation-triangle"></i> Error Handling & Retry</h4></div>
-    <div class="form-section-content" style="display: none;">
+    <div class="form-section-content">
         <div class="form-row">
             <label for="node-config-input-retryFreshConnection" style="width: auto;"><i class="fa fa-refresh"></i> Retry with fresh connection</label>
             <input type="checkbox" id="node-config-input-retryFreshConnection" style="display: inline-block; width: auto; vertical-align: top;" />
-            <span class="form-tips" style="font-size: smaller;">If a pooled connection fails, try once with a new one.</span>
+            <span class="form-tips">If a pooled connection fails, try once with a new one.</span>
         </div>
         <div class="retry-options" style="padding-left: 20px;">
             <div class="form-row">
@@ -259,13 +265,27 @@
             <div class="form-row">
                 <label for="node-config-input-retryOnMsg" style="width: auto;"><i class="fa fa-envelope-o"></i> Retry on new message</label>
                 <input type="checkbox" id="node-config-input-retryOnMsg" style="display: inline-block; width: auto; vertical-align: top;" />
-                <span class="form-tips" style="font-size: smaller;">If waiting, a new message triggers immediate retry.</span>
+                <span class="form-tips">If waiting, a new message triggers immediate retry.</span>
             </div>
         </div>
     </div>
 
+    <div class="form-section-header"><h4><i class="fa fa-caret-right"></i> <i class="fa fa-power-off"></i> Shutdown Options</h4></div>
+    <div class="form-section-content">
+        <div class="form-row">
+            <label for="node-config-input-fireAndForgetOnClose" style="width: auto;">
+                <i class="fa fa-rocket"></i> Fast close (Fire-and-forget)
+            </label>
+            <input type="checkbox" id="node-config-input-fireAndForgetOnClose" style="display: inline-block; width: auto; vertical-align: top;">
+            <span class="form-tips">
+                <b>Warning:</b> If checked, Node-RED will not wait for the pool to close during deploy/shutdown.
+                This can prevent hangs with problematic drivers but may leave orphaned connections on the DB server. Use with caution.
+            </span>
+        </div>
+    </div>
+
     <div class="form-section-header"><h4><i class="fa fa-caret-right"></i> <i class="fa fa-wrench"></i> Advanced</h4></div>
-    <div class="form-section-content" style="display: none;">
+    <div class="form-section-content">
          <div class="form-row">
             <label for="node-config-input-syntaxtick" style="width: auto;"><i class="fa fa-check-square-o"></i> Syntax Checker</label>
             <input type="checkbox" id="node-config-input-syntaxtick" style="display: inline-block; width: auto; vertical-align: top;" />
@@ -341,7 +361,7 @@ A **Test Connection** button in the configuration panel allows you to instantly
 - **`Increment Pool Size`**: The number of connections to create when the pool is exhausted. Default: 5.
 - **`Max Pool Size`**: The maximum number of connections allowed in the pool. Default: 15.
 - **`Shrink Pool`**: If checked, reduces the number of connections to `Initial Pool Size` when they are returned to the pool if the pool has grown. Default: true.
-- **`Idle Timeout`**: The number of seconds for a connection in the pool to remain idle before closing. Default: 3 seconds.
+- **`Idle Timeout`**: The number of seconds for a connection in the pool to remain idle before closing. Default: 3 seconds. (Refers to the `connectionTimeout` property of the `odbc` library's pool options).
 - **`Login Timeout`**: The number of seconds for an attempt to establish a new connection to succeed. Default: 5 seconds.
 - **`Query Timeout`**: The number of seconds for a query to execute before timing out. A value of **0** means infinite or uses the driver/database default. Default: 0 seconds.
 
@@ -350,6 +370,13 @@ A **Test Connection** button in the configuration panel allows you to instantly
 - **`Retry Delay`**: If all immediate attempts (pooled and, if enabled, fresh connection) fail, this sets a delay in seconds before another retry is attempted for the incoming message. A value of **0** disables this timed retry mechanism.
 - **`Retry on new message`**: If the node is waiting for a timed retry (due to `Retry Delay`), a new incoming message can, if this is checked, override the timer and trigger an immediate retry of the *original* message that failed.
 
+### Shutdown Options
+- **`Fast close (Fire-and-forget)`**: 
+    - **Warning:** When checked, Node-RED will not wait for the connection pool to properly close during a deploy or shutdown. 
+    - This option can prevent Node-RED from hanging if specific ODBC drivers have issues closing connections quickly. 
+    - However, enabling this may result in orphaned connections on the database server, potentially consuming server resources. 
+    - It is recommended to leave this unchecked unless you are experiencing hangs during Node-RED deploys or shutdowns related to this config node. Default: Unchecked.
+
 ### Advanced
 - **`syntaxChecker`**: If activated, the query string will be parsed and appended to the output message at `msg.parsedQuery`.
 - **`Syntax`**: The SQL dialect to use for the syntax checker (e.g., mysql, postgresql, etc.).

package/odbc.js

@@ -17,6 +17,9 @@ module.exports = function (RED) {
         }
         this.closeOperationTimeout = 10000; // 10 secondes
 
+        // NOUVEAU: Récupérer et s'assurer que l'option fireAndForgetOnClose est un booléen
+        this.config.fireAndForgetOnClose = config.fireAndForgetOnClose === true;
+
         this._buildConnectionString = function() {
             if (this.config.connectionMode === 'structured') {
                 if (!this.config.dbType || !this.config.server) {
@@ -33,8 +36,13 @@ module.exports = function (RED) {
                 if(driver) parts.unshift(`DRIVER={${driver}}`);
                 parts.push(`SERVER=${this.config.server}`);
                 if (this.config.database) parts.push(`DATABASE=${this.config.database}`);
-                if (this.config.user) parts.push(`UID=${this.config.user}`);
-                if (this.credentials && this.credentials.password) parts.push(`PWD=${this.credentials.password}`);
+                
+                if (this.config.user) { 
+                    parts.push(`UID=${this.config.user}`);
+                    if (this.credentials && typeof this.credentials.password === 'string') {
+                        parts.push(`PWD=${this.credentials.password}`);
+                    }
+                }
                 return parts.join(';');
             } else {
                 return this.config.connectionString || "";
@@ -110,22 +118,49 @@ module.exports = function (RED) {
             }
         };
 
+        // MODIFIÉ pour inclure l'option fireAndForgetOnClose
         this.on("close", async (removed, done) => {
-            this.log("Closing ODBC config node. Attempting to close pool.");
+            const nodeName = this.name || this.id;
+            this.log(`[${nodeName}] Closing ODBC config node. Pool present: ${!!this.pool}. Fire-and-forget: ${this.config.fireAndForgetOnClose}`);
+    
             if (this.pool) {
-                try {
-                    await Promise.race([
-                        this.pool.close(),
-                        new Promise((_, reject) => setTimeout(() => reject(new Error('Pool close timeout on node close')), this.closeOperationTimeout))
-                    ]);
-                    this.log("Connection pool closed successfully on node close.");
-                } catch (error) {
-                    this.error(`Error or timeout closing connection pool on node close: ${error.message}`, error);
-                } finally {
-                    this.pool = null; 
+                const currentPool = this.pool; 
+                this.pool = null; 
+                this.connecting = false;
+    
+                const closePromise = Promise.race([
+                    currentPool.close(),
+                    new Promise((_, reject) => 
+                        setTimeout(() => reject(new Error('Pool close timeout')), this.closeOperationTimeout)
+                    )
+                ]);
+    
+                if (this.config.fireAndForgetOnClose) {
+                    this.log(`[${nodeName}] Initiating fire-and-forget pool close. Calling done() immediately.`);
+                    done(); 
+    
+                    closePromise
+                        .then(() => {
+                            this.log(`[${nodeName}] Background fire-and-forget pool close for ${nodeName} completed successfully.`);
+                        })
+                        .catch(error => {
+                            this.error(`[${nodeName}] Background fire-and-forget pool close for ${nodeName} failed or timed out: ${error.message}`, error);
+                        });
+                } else { 
+                    this.log(`[${nodeName}] Awaiting pool close operation...`);
+                    try {
+                        await closePromise;
+                        this.log(`[${nodeName}] Pool close operation completed successfully for ${nodeName}.`);
+                    } catch (error) {
+                        this.error(`[${nodeName}] Pool close operation for ${nodeName} failed or timed out: ${error.message}`, error);
+                    }
+                    this.log(`[${nodeName}] Calling done() after awaiting pool close for ${nodeName}.`);
+                    done();
                 }
+            } else { 
+                this.log(`[${nodeName}] No pool to close. Calling done().`);
+                done();
             }
-            done();
         });
     }
     RED.nodes.registerType("odbc config", poolConfig, { credentials: { password: { type: "password" } } });
@@ -146,8 +181,12 @@ module.exports = function (RED) {
                 if(driver) parts.unshift(`DRIVER={${driver}}`);
                 parts.push(`SERVER=${tempConfig.server}`);
                 if (tempConfig.database) parts.push(`DATABASE=${tempConfig.database}`);
-                if (tempConfig.user) parts.push(`UID=${tempConfig.user}`);
-                if (tempConfig.password) parts.push(`PWD=${tempConfig.password}`);
+                if (tempConfig.user) { 
+                    parts.push(`UID=${tempConfig.user}`);
+                    if (typeof tempConfig.password === 'string') { 
+                        parts.push(`PWD=${tempConfig.password}`);
+                    }
+                }
                 return parts.join(';');
             } else {
                 let connStr = tempConfig.connectionString || "";
@@ -406,9 +445,6 @@ module.exports = function (RED) {
 
             } catch (initialDbError) {
                 this.warn(`Initial DB attempt failed: ${initialDbError.message}`);
-                // Garder la requête originale pour le contexte d'erreur, même si une erreur de connexion se produit
-                // this.currentQueryForErrorContext et this.currentParamsForErrorContext sont déjà settés par getRenderedQueryAndParams
-
                 if (activeConnection) { 
                     const connStillGood = await this.testBasicConnectivity(activeConnection);
                     try { await activeConnection.close(); activeConnection = null; } 
@@ -451,7 +487,7 @@ module.exports = function (RED) {
                         if (activeConnection) { try { await activeConnection.close(); activeConnection = null; } catch(e){this.warn("Error closing fresh conn after error: "+e.message);} }
                         
                         if (shouldProceedToTimedRetry) { 
-                            // errorForUser a été setté par l'échec du SELECT 1 sur la connexion fraîche
+                            // errorForUser est déjà l'erreur de test de connectivité et sera utilisé ci-dessous
                         } else { 
                             this.status({ fill: "red", shape: "ring", text: "SQL error (on retry)" });
                             return done(this.enhanceError(freshErrorOrConnectivityFail));
@@ -463,7 +499,7 @@ module.exports = function (RED) {
                 }
             }
             
-            if (activeConnection) { // Sécurité supplémentaire pour fermer une connexion si elle est restée active
+            if (activeConnection) {
                 try { await activeConnection.close(); } catch(e) { this.warn("Final cleanup: Error closing activeConnection: " + e.message); }
                 activeConnection = null;
             }
@@ -486,10 +522,9 @@ module.exports = function (RED) {
                 }
             } else if (errorForUser) { 
                  this.status({ fill: "red", shape: "ring", text: "Error (No Timed Retry)" });
-                 return done(errorForUser); // Cas où c'est une erreur SQL identifiée, pas de retry temporisé.
+                 return done(errorForUser);
             } else {
-                 // Ce chemin ne devrait pas être atteint si done() a été appelé dans un chemin de succès.
-                 this.log("[ODBC Node] DEBUG: Reached unexpected end of on('input') path. Calling done().");
+                 this.log("[ODBC Node] DEBUG: Reached end of on('input') path. Calling done().");
                  return done();
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bkmj/node-red-contrib-odbcmj",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "A powerful Node-RED node to connect to any ODBC data source, with connection pooling, advanced retry logic, and result streaming.",
   "keywords": [
     "node-red",