@bkmj/node-red-contrib-odbcmj 1.6.6 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +18 -113
  2. package/odbc.html +226 -146
  3. package/odbc.js +623 -194
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,147 +1,52 @@
1
- # node-red-contrib-odbcmj
2
-
3
- A Node-RED implementation of odbc.js (https://www.npmjs.com/package/odbc). This node allows you to make queries to a database through an ODBC connection. Parameters can be passed to the SQL query using Mustache syntax, prepared statements, or directly in the query string.
4
-
5
- ---
6
- ## Acknowledgment
7
-
8
- This node is an unofficial fork of node-red-contrib-odbc by Mark Irish (https://github.com/markdirish/node-red-contrib-odbc) and is vastly inspired by it. It also takes ideas from node-red-contrib-odbc2 by AIS Automation (https://github.com/AISAutomation/node-red-contrib-odbc2).
9
-
10
- **Overall changes:**
11
-
12
- * Can use Mustache as well as a parameter array.
13
- * Warnings when Mustache will render an undefined variable.
14
- * Fixes the output field option so that nested objects can be used.
15
- * Fixes the checkbox for the pool shrink option.
16
- * Uses ace/mode/sql for the SQL input field.
17
- * Connection nodes can have individually defined names.
18
- * Selectable SQL syntax checker.
19
- * Allows parameters to be passed as an object, mapping values to named parameters in the query.
20
- * Automatically handles prepared statements based on the query and parameters.
21
-
22
- ## Installation
23
-
24
- This package is not available from within the Node-RED palette tool. Instead, in your Node-RED user directory (usually `~/.node-red/`), download through the `npm` utility:
25
- ```
26
- npm install node-red-contrib-odbcmj
27
- ```
28
-
29
- For the `odbc` connector requirements, please see [the documentation for that package](https://www.npmjs.com/package/odbc#requirements).
30
-
31
- ## Usage
32
-
33
- `node-red-contrib-odbcmj` provides two nodes:
34
-
35
- * **`odbc config`**: A configuration node for defining your connection string and managing your connection  
36
- parameters.
37
- * **`odbc`**: A node for running queries with or without parameters.
38
-
39
1
  ### `odbc config`
40
2
 
41
- A configuration node that manages connections in an `odbc.pool` object. [Can take any configuration property recognized by `odbc.pool()`](https://www.npmjs.com/package/odbc#constructor-odbcpoolconnectionstring). The connection pool will initialize the first time  
42
- an `odbc` node receives an input message.
3
+ A configuration node that manages connections in an `odbc.pool` object. [Can take any configuration property recognized by `odbc.pool()`](https://www.npmjs.com/package/odbc#constructor-odbcpoolconnectionstring). The connection pool will initialize the first time
4
+ an `odbc` node receives an input message.
43
5
 
44
6
  #### Properties
45
7
 
46
- * (**required**) **`connectionString`**: <`string`>
8
+ - (**required**) **`connectionString`**: <`string`>
47
9
 
48
- An ODBC connection string that defines your DSN and/or connection string options.  
49
- Check your ODBC driver documentation for more information about valid connection strings.
10
+ An ODBC connection string that defines your DSN and/or connection string options.
11
+ Check your ODBC driver documentation for more information about valid connection strings.
50
12
 
51
13
  Example:
14
+
52
15
  ```
53
16
  DSN=MyDSN;DFT=2;
54
17
  ```
55
18
 
56
- * (optional) **`initialSize`**: <`number`>
19
+ - (optional) **`initialSize`**: <`number`>
57
20
 
58
21
  The number of connections created in the pool when it is initialized. Default: 5.
59
22
 
60
- * (optional) **`incrementSize`**: <`number`>
23
+ - (optional) **`incrementSize`**: <`number`>
61
24
 
62
25
  The number of connections that are created when the pool is exhausted. Default: 5.
63
26
 
64
- * (optional) **`maxSize`**: <`number`>
27
+ - (optional) **`maxSize`**: <`number`>
65
28
 
66
29
  The maximum number of connections allowed in the pool before it won't create any more. Default: 15.
67
30
 
68
- * (optional) **`shrinkPool`**: <`boolean`>
31
+ - (optional) **`shrinkPool`**: <`boolean`>
69
32
 
70
33
  Whether the number of connections should be reduced to `initialSize` when they are returned to the pool. Default: true.
71
34
 
72
- * (optional) **`connectionTimeout`**: <`number`>
35
+ - (optional) **`connectionTimeout`**: <`number`>
73
36
 
74
37
  The number of seconds for a connection to remain idle before closing. Default: 3.
75
38
 
76
- * (optional) **`loginTimeout`**: <`number`>
39
+ - (optional) **`loginTimeout`**: <`number`>
40
+
41
+ The number of seconds for an attempt to create a connection before returning to the application.
42
+ Default: 3.
77
43
 
78
- The number of seconds for an attempt to create a connection before returning to the application.  
79
- Default: 3.
44
+ - (optional) **`retryFreshConnection`**: <`boolean`> If checked, in case of a query error when using a pooled connection, the node will attempt the query a second time using a brand new database connection (not from the pool). If this second attempt is successful, it indicates the original pooled connection or the pool itself might be problematic. Consequently, the entire connection pool will be closed and reset, forcing a new pool to be created on subsequent requests. This can help recover from stale or broken connections within the pool. Default: false.
80
45
 
81
- * (optional) **`syntaxChecker`**: <`boolean`>
46
+ - (optional) **`syntaxChecker`**: <`boolean`>
82
47
 
83
48
  Whether the syntax validator is activated or not. If activated, the query string will be [parsed](https://www.npmjs.com/package/node-sql-parser#create-ast-for-sql-statement) and appended as an object to the output message with a key named `parsedSql`. Default: false.
84
49
 
85
- * (optional) **`syntax`**: <`string`>
50
+ - (optional) **`syntax`**: <`string`>
86
51
 
87
52
  Dropdown list of the available [SQL flavors available](https://www.npmjs.com/package/node-sql-parser#supported-database-sql-syntax). Default: mysql.
88
-
89
-
90
- ### `odbc`
91
-
92
- A node that runs a query when input is received. Each instance of the node can define its own query string, as well as take a query and/or parameters as input. A query sent as an input message will override any query defined in the node properties.
93
-
94
- #### Properties
95
-
96
- * (**required**) **`connection`**: <`odbc config`>
97
-
98
- The ODBC pool node that defines the connection settings and manages the connection pool used by this node.
99
-
100
- * (optional) **`query`**: <`string`>
101
-
102
- A valid SQL query string.  
103
-
104
- * Can contain parameters inserted using Mustache syntax (e.g., `{{{payload}}}`).
105
- * Can use placeholders (`?`) for parameters.
106
- * Can embed parameters directly in the query string.
107
-
108
- * (**required**) **`result to`**: <`dot-notation string`>
109
-
110
- The JSON nested element structure that will contain the result output. The string must be a valid JSON object structure using dot-notation, minus the `msg.` (e.g., `payload.results`) and must not start or end with a period. Square bracket notation is not allowed. The node input object is carried out to the output, as long as the output object name does not conflict with it. If the targeted output JSON object was already present in the input, the result from the query will be appended to it  
111
- if it was itself an object (but not an array); otherwise, the original key/value pair will be overwritten.
112
-
113
- Example:
114
-
115
- * `input msg: {"payload": {"result": {"othervalue": 10} } };`
116
- * `result to: payload.results.values`
117
-
118
- In this case, `values` will be appended to `result` without overwriting `othervalue`. If `result` had been a string, then it would have been replaced by `values`.
119
-
120
- #### Inputs
121
-
122
- The `odbc` node accepts a message input that can contain:
123
-
124
- * **`query`**: <`string`> A valid SQL query string. This overrides the query defined in the node properties.
125
- * **`payload`**:
126
- * A JSON string containing a `query` property with the SQL string.
127
- * An object with a `query` property containing the SQL string.
128
- * **`parameters`**: <`array` or `object`>
129
- * Can be an array of values or an object mapping parameter names to values.
130
- * If the query contains placeholders (`?`) and `msg.parameters` is an object, the values will be automatically mapped to the placeholders based on the order of the parameters in the query.
131
-
132
- #### Outputs
133
-
134
- Returns a message containing:
135
-
136
- * **`output object`**: <`array`> The `odbc` result array returned from the query.
137
- * **`odbc`**: <`object`> Contains additional information returned by the `odbc` module.
138
- * **`parsedQuery`**: <`object`> (Optional) The parsed SQL query if the syntax checker is enabled.
139
-
140
- **Automatic Prepared Statement Handling**
141
-
142
- The node automatically determines whether to use a prepared statement or a regular query based on the following:
143
-
144
- * **Presence of Placeholders:** If the query string contains placeholders (`?`), the node will use a prepared statement.
145
- * **`msg.parameters` Object:** If the `msg.parameters` object is provided (either as an array or an object), the node will use a prepared statement.
146
-
147
- This automatic handling ensures that your queries are executed in the most secure way possible, minimizing the risk of SQL injection vulnerabilities.