Skip to content

Commit 37dd206

Browse files
sudarshan12ssudarshan somasudarshan somasudarshan soma
authored
Oracle Database SQL Node Documentation (#1) (#3627)
Co-authored-by: sudarshan soma <sudarshansoma@dhcp-10-120-180-201.wifi.oracle.com> Co-authored-by: sudarshan soma <sudarshansoma@sudarshans-MacBook-Pro.local> Co-authored-by: sudarshan soma <sudarshansoma@dhcp-10-120-172-230.wifi.oracle.com>
1 parent 30e23e9 commit 37dd206

File tree

3 files changed

+329
-0
lines changed

3 files changed

+329
-0
lines changed

‎docs/integrations/builtin/app-nodes/n8n-nodes-base.oracledb/index.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
title: Oracle Database node documentation
3+
description: Learn how to use the Oracle Database node in n8n. Follow technical documentation to integrate Oracle Database node into your workflows.
4+
contentType: [integration, reference]
5+
priority: critical
6+
---
7+
8+
# Oracle Database node
9+
10+
Use the Oracle Database node to automate work in Oracle Database, and integrate Oracle Database with other applications. n8n has built-in support for a wide range of Oracle Database features which includes executing an SQL statement, fetching, inserting, updating or deleting data from Oracle Database. This node uses the [node-oracledb driver](https://github.com/oracle/node-oracledb) internally.
11+
12+
On this page, you'll find a list of operations the Oracle Database node supports and links to more resources.
13+
14+
/// note
15+
Refer to [Oracle Database credentials](/integrations/builtin/credentials/oracledb.md) for guidance on setting up authentication.
16+
17+
Requires Oracle Database **19c or later**.
18+
For thick mode, use Oracle Client Libraries **19c or later**.
19+
///
20+
21+
--8<-- "/_snippets/integrations/builtin/app-nodes/ai-tools.md"
22+
23+
## Operations
24+
25+
* [**Delete**](#delete): Delete an entire table or rows in a table
26+
* [**Execute SQL**](#execute-sql): Execute an SQL statement
27+
* [**Insert**](#insert): Insert rows in a table
28+
* [**Insert or Update**](#insert-or-update): Insert or update rows in a table
29+
* [**Select**](#select): Select rows from a table
30+
* [**Update**](#update): Update rows in a table
31+
32+
### Delete
33+
34+
Use this operation to delete an entire table or rows in a table.
35+
36+
Enter these parameters:
37+
38+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
39+
- **Operation**: Select **Delete**.
40+
- **Schema**: Choose the schema that contains the table you want to work on. Select **From list** to choose the schema from the dropdown list or **By Name** to enter the schema name.
41+
- **Table**: Choose the table that you want to work on. Select **From list** to choose the table from the dropdown list, or select **By Name** to enter the table name.
42+
- **Command**: The deletion action to take:
43+
- **Truncate**: Removes the table's data but preserves the table's structure.
44+
- **Delete**: Delete the rows that match the "Select Rows" condition. If you don't select anything, Oracle Database deletes all rows.
45+
- **Select Rows**: Define a **Column**, **Operator**, and **Value** to match rows on. The value
46+
can be passed as JSON using expression or string.
47+
- **Combine Conditions**: How to combine the conditions in "Select Rows". The **AND** requires all conditions to be true, while **OR** requires at least one condition to be true.
48+
- **Drop**: Deletes the table's data and structure permanently.
49+
50+
#### Delete options
51+
52+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
53+
- **Statement Batching**: The way to send statements to the database:
54+
- **Single Statement**: A single statement for all incoming items.
55+
- **Independently**: Execute one statement per incoming item of the execution.
56+
- **Transaction**: Execute all statements in a transaction. If a failure occurs, Oracle Database rolls back all changes.
57+
58+
### Execute SQL
59+
60+
Use this operation to execute an SQL statement.
61+
62+
Enter these parameters:
63+
64+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
65+
- **Operation**: Execute SQL **Execute SQL**.
66+
- **Statement**: The SQL statement to execute. You can use n8n [expressions](/code/expressions.md) and positional parameters like `:1`, `:2`, or named parameters like `:name`, `:id` to use with [Use bind parameters](#use-bind-parameters).
67+
To run a PL/SQL procedure, for example `demo`, you can use:
68+
```sql
69+
BEGIN
70+
demo;
71+
END;
72+
```
73+
74+
#### Execute Statement options
75+
76+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
77+
- **Bind Variable Placeholder Values**: Enter the values for the bind parameters used in the statement [Use bind parameters](#use-bind-parameters).
78+
- **Output Numbers As String**: Indicates if the numbers should be retrieved as a String.
79+
- **Fetch Array Size**: This property is a number that sets the size of an internal buffer used for fetching query rows from Oracle Database. Changing it may affect query performance but does not affect how many rows are returned to the application.
80+
- **Number of Rows to Prefetch**: This property is a query tuning option to set the number of additional rows the underlying Oracle driver fetches during the internal initial statement execution phase of a query.
81+
82+
### Insert
83+
84+
Use this operation to insert rows in a table.
85+
86+
Enter these parameters:
87+
88+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
89+
- **Operation**: Select **Insert**.
90+
- **Schema**: Choose the schema that contains the table you want to work on. Select **From list** to choose the schema from the dropdown list or **By Name** to enter the schema name.
91+
- **Table**: Choose the table that you want to work on. Select **From list** to choose the table from the dropdown list, or select **By Name** to enter the table name.
92+
- **Mapping Column Mode**: How to map column names to incoming data:
93+
- **Map Each Column Manually**: Select the values to use for each column [Use n8n expressions for bind values](#use-n8n-expressions-for-bind-values).
94+
- **Map Automatically**: Automatically map incoming data to matching column names in Oracle Database. The incoming data field names must match the column names in Oracle Database for this to work. If necessary, consider using the [edit fields (set) node](/integrations/builtin/core-nodes/n8n-nodes-base.set.md) before this node to adjust the format as needed.
95+
96+
#### Insert options
97+
98+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
99+
- **Output Columns**: Choose which columns to output. You can select from a list of available columns or specify IDs using [expressions](/code/expressions.md).
100+
- **Statement Batching**: The way to send statements to the database:
101+
- **Single Statement**: A single statement for all incoming items.
102+
- **Independently**: Execute one statement per incoming item of the execution.
103+
- **Transaction**: Execute all statements in a transaction. If a failure occurs, Oracle Database rolls back all changes.
104+
105+
### Insert or Update
106+
107+
Use this operation to insert or update rows in a table.
108+
109+
Enter these parameters:
110+
111+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
112+
- **Operation**: Select **Insert or Update**.
113+
- **Schema**: Choose the schema that contains the table you want to work on. Select **From list** to choose the schema from the dropdown list or **By Name** to enter the schema name.
114+
- **Table**: Choose the table that you want to work on. Select **From list** to choose the table from the dropdown list, or select **By Name** to enter the table name.
115+
- **Mapping Column Mode**: How to map column names to incoming data:
116+
- **Map Each Column Manually**: Select the values to use for each column [Use n8n expressions for bind values](#use-n8n-expressions-for-bind-values).
117+
- **Map Automatically**: Automatically map incoming data to matching column names in Oracle Database. The incoming data field names must match the column names in Oracle Database for this to work. If necessary, consider using the [edit fields (set) node](/integrations/builtin/core-nodes/n8n-nodes-base.set.md) before this node to adjust the format as needed.
118+
119+
#### Insert or Update options
120+
121+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
122+
- **Output Columns**: Choose which columns to output. You can select from a list of available columns or specify IDs using [expressions](/code/expressions.md).
123+
- **Statement Batching**: The way to send statements to the database:
124+
- **Single Statement**: A single statement for all incoming items.
125+
- **Independently**: Execute one statement per incoming item of the execution.
126+
- **Transaction**: Execute all statements in a transaction. If a failure occurs, Oracle Database rolls back all changes.
127+
128+
### Select
129+
130+
Use this operation to select rows in a table.
131+
132+
Enter these parameters:
133+
134+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
135+
- **Operation**: Select **Select**.
136+
- **Schema**: Choose the schema that contains the table you want to work on. Select **From list** to choose the schema from the dropdown list or **By Name** to enter the schema name.
137+
- **Table**: Choose the table that you want to work on. Select **From list** to choose the table from the dropdown list, or select **By Name** to enter the table name.
138+
- **Return All**: Whether to return all results or only up to a given limit.
139+
- **Limit**: The maximum number of items to return when **Return All** is disabled.
140+
- **Select Rows**: Set the conditions to select rows. Define a **Column**, **Operator**, and **Value**(as `json`) to match rows on.
141+
The **Value** can vary by type — for example with Fixed mode:
142+
- String: "hello", hellowithoutquotes, "hello with space"
143+
- Number: 12
144+
- JSON: { "key": "val" }
145+
146+
If you don't select anything, Oracle Database selects all rows.
147+
- **Combine Conditions**: How to combine the conditions in **Select Rows**. The **AND** requires all conditions to be true, while **OR** requires at least one condition to be true.
148+
- **Sort**: Choose how to sort the selected rows. Choose a **Column** from a list or by ID and a sort **Direction**.
149+
150+
#### Select options
151+
152+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
153+
- **Output Numbers As String**: Indicates if the numbers should be retrieved as a String.
154+
- **Fetch Array Size**: This property is a number that sets the size of an internal buffer used for fetching query rows from Oracle Database. Changing it may affect query performance but does not affect how many rows are returned to the application.
155+
- **Number of Rows to Prefetch**: This property is a query tuning option to set the number of additional rows the underlying Oracle driver fetches during the internal initial statement execution phase of a query.
156+
157+
### Update
158+
159+
Use this operation to update rows in a table.
160+
161+
Enter these parameters:
162+
163+
- **Credential to connect with**: Create or select an existing [Oracle Database credential](/integrations/builtin/credentials/oracledb.md).
164+
- **Operation**: Select **Update**.
165+
- **Schema**: Choose the schema that contains the table you want to work on. Select **From list** to choose the schema from the dropdown list or **By Name** to enter the schema name.
166+
- **Table**: Choose the table that you want to work on. Select **From list** to choose the table from the dropdown list, or select **By Name** to enter the table name.
167+
- **Mapping Column Mode**: How to map column names to incoming data:
168+
- **Map Each Column Manually**: Select the values to use for each column [Use n8n expressions for bind values](#use-n8n-expressions-for-bind-values).
169+
- **Map Automatically**: Automatically map incoming data to matching column names in Oracle Database. The incoming data field names must match the column names in Oracle Database for this to work. If necessary, consider using the [edit fields (set) node](/integrations/builtin/core-nodes/n8n-nodes-base.set.md) before this node to adjust the format as needed.
170+
171+
#### Update options
172+
173+
- **Auto Commit**: When this property is set to true, the transaction in the current connection is automatically committed at the end of statement execution.
174+
- **Output Columns**: Choose which columns to output. You can select from a list of available columns or specify IDs using [expressions](/code/expressions.md).
175+
- **Statement Batching**: The way to send statements to the database:
176+
- **Single Statement**: A single statement for all incoming items.
177+
- **Independently**: Execute one statement per incoming item of the execution.
178+
- **Transaction**: Execute all statements in a transaction. If a failure occurs, Oracle Database rolls back all changes.
179+
180+
## Related resources
181+
182+
Refer to [SQL Language Reference](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=SQLRF) for more information about the service.
183+
184+
Refer to [node-oracledb documentation](https://node-oracledb.readthedocs.io/en/latest/) for more information about the node-oracledb driver.
185+
186+
## Use bind parameters
187+
188+
When creating a statement to run on an Oracle database instance, you can use the **Bind Variable Placeholder Values** field in the **Options** section to load data into the statement. n8n sanitizes data in statement parameters, which prevents SQL injection.
189+
190+
For example, you would want to find specific fruits by their color. Given the following input data:
191+
192+
```js
193+
[
194+
{
195+
"FRUIT_ID": 1,
196+
"FRUIT_NAME": "Apple",
197+
"COLOR": "Red"
198+
},
199+
{
200+
"FRUIT_ID": 2,
201+
"FRUIT_NAME": "Banana",
202+
"COLOR": "Yellow"
203+
}
204+
]
205+
```
206+
207+
You can write a statement like:
208+
209+
```sql
210+
SELECT * FROM FRUITS WHERE COLOR = :col
211+
```
212+
213+
Then in **Bind Variable Placeholder Values**, provide the field values to use. You can provide fixed values or expressions. For this example, use expressions so the node can pull the color from each input item in turn:
214+
215+
```js
216+
// fruits is an example table name
217+
fruits, {{ $json.color }}
218+
```
219+
220+
## Use n8n Expressions for bind values
221+
222+
For **Values to Send**, you can provide inputs using n8n Expressions. Below are examples for different data types — you can either enter constant values or reference fields from previous items (`$json`):
223+
224+
### JSON
225+
- Constant: `{{ { k1: "v1", k2: "v2" } }}`
226+
- From a previous item: `{{ $json.COL_JSON }}`
227+
228+
### VECTOR
229+
- Constant: `{{ [1, 2, 3, 4.5] }}`
230+
- From a previous item: `{{ $json.COL_VECTOR }}`
231+
232+
### BLOB
233+
- Constant: `{{ [94, 87, 34] }}` or `{{ ' BLOB data string' }}`
234+
- From a previous item: `{{ $json.COL_BLOB }}`
235+
236+
### RAW
237+
- Constant: `{{ [94, 87, 34] }}`
238+
- From a previous item: `{{ $json.COL_RAW }}`
239+
240+
### BOOLEAN
241+
- Constant: `{{ true }}`
242+
- From a previous item: `{{ $json.COL_BOOLEAN }}`
243+
244+
### NUMBER
245+
- Constant: `1234`
246+
- From a previous item: `{{ $json.COL_NUMBER }}`
247+
248+
## VARCHAR
249+
- Constant: `' Hello World '`
250+
- From a previous item: `{{ $json.COL_CHAR }}`
251+
252+
These examples assume JSON keys (e.g. `COL_JSON, COL_VECTOR`) map directly to the respective SQL column types.

‎docs/integrations/builtin/credentials/oracledb.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Oracle Database credentials
3+
description: Documentation for Oracle Database credentials. Use these credentials to authenticate Oracle Database in n8n, a workflow automation platform.
4+
contentType: [integration, reference]
5+
priority: high
6+
---
7+
8+
# Oracle Database credentials
9+
10+
You can use these credentials to authenticate the following nodes:
11+
12+
- [OracleDB](/integrations/builtin/app-nodes/n8n-nodes-base.oracledb/index.md)
13+
- [Agent](/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/index.md)
14+
15+
/// note
16+
These nodes do not support SSH tunnels.
17+
They require Oracle Database 19c or later. For thick mode, use Oracle Client Libraries 19c or later.
18+
///
19+
20+
## Prerequisites
21+
22+
Create a user account on a [OracleDB](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-F0246961-558F-480B-AC0F-14B50134621C) server database.
23+
24+
## Supported authentication methods
25+
26+
- Database connection
27+
28+
## Related resources
29+
30+
Refer to [Oracle Database documentation](https://docs.oracle.com/en/database/oracle/oracle-database) for more information about the service.
31+
32+
## Using database connection
33+
34+
To configure this credential, you'll need:
35+
36+
- A **User** name.
37+
- A **Password** for that user.
38+
- **Connection String**: The Oracle database instance to connect to. The string can be an Easy Connect string, or a TNS Alias from a tnsnames.ora file, or the Oracle database instance.
39+
- **Use Optional Oracle Client Libraries**: If you want to use node-oracledb Thick mode for working with Oracle Database advanced features, turn this on. This option is not available in official n8n docker images. Additional settings to enable Thick mode are required. Refer to [Enabling Thick mode documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#enabling-node-oracledb-thick-mode) for more information.
40+
- **Use SSL**: If your Connection String is using SSL, turn this on and configure additional details for the SSL Authentication.
41+
- **Wallet Password**: The password to decrypt the Privacy Enhanced Mail (PEM)-encoded private certificate, if it is encrypted.
42+
- **Wallet Content**: The security credentials required to establish a mutual TLS (mTLS) connection to Oracle Database.
43+
- **Distinguished Name**: The distinguished name (DN) that should be matched with the certificate DN.
44+
- **Match Distinguished Name**: Whether the server certificate DN should be matched in addition to the regular certificate verification that is performed.
45+
- **Allow Weak Distinguished Name Match**: Whether the secure DN matching behavior which checks both the listener and server certificates has to be performed.
46+
- **Pool Min**: The number of connections established to the database when a pool is created.
47+
- **Pool Max**: The maximum number of connections to which a connection pool can grow.
48+
- **Pool Increment**: The number of connections that are opened whenever a connection request exceeds the number of currently open connections.
49+
- **Pool Maximum Session Life Time**: The number of connections that are opened whenever a connection request exceeds the number of currently open connections.
50+
- **Pool Connection Idle Timeout**: The number of connections that are opened whenever a connection request exceeds the number of currently open connections.
51+
- **Connection Class Name**: DRCP/PRCP Connection Class. Refer to [Enabling DRCP](https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-processes.html#GUID-BB76E57C-3F16-4C85-AEF6-BA14FC1B4777) for more information.
52+
- **Connection Timeout**: The timeout duration in seconds for an application to establish an Oracle Net connection.
53+
- **Transport Connection Timeout**: The maximum number of seconds to wait to establish a connection to the database host.
54+
- **Keepalive Probe Interval**: The number of minutes between the sending of keepalive probes.
55+
56+
57+
To set up your database connection credential:
58+
59+
1. Enter your database's username as the **User** in your n8n credential.
60+
61+
2. Enter the user's **Password**.
62+
63+
3. Enter your database's connection string as the **Connection String** in your n8n credential.
64+
65+
4. If your database uses SSL and you'd like to configure **SSL** for the connection, turn this option on in the credential. If you turn it on, enter the information of your Oracle Database SSL certificate in these fields:
66+
1. Enter the output of PEM-encoded wallet file, **ewallet.pem** contents after retaining the new lines. The command
67+
68+
```bash
69+
node -e "console.log('{{\"' + require('fs').readFileSync('ewallet.pem', 'utf8').split('\n').join('\\\\n') + '\"}}')"
70+
```
71+
72+
can be used to dump file contents in the **Wallet Content** field.
73+
74+
Refer to [node-oracledb](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#mutual-tls-connections-to-oracle-cloud-autonomous-database) for more information on working with TLS connections.

0 commit comments

Comments
 (0)