Skip to content

Commit b1a011c

Browse files
fdevansfdevans
authored
Merge pull request #1651 from rundeck/sqlrunner
SQL Runner Plugin Improvments
2 parents c172ccf + 218bc91 commit b1a011c

File tree

3 files changed

+96
-86
lines changed

3 files changed

+96
-86
lines changed

‎docs/.vuepress/public/assets/img/sqlrunner-plugin.png

231 KB
Loading

‎docs/history/5_x/version-5.11.0.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ MongoDB is a widely adopted NoSQL database known for its flexibility and ease of
2828

2929
### JSON and Table for SQL Query Plugin
3030

31-
The SQL Query job plugin is commonly used to automate tasks or provide a self-service mechanism for interfacing with SQL databases–such as MySQL, MSSQL, Oracle and so on. Previously, the job step would always return the output of the query as plain-text log-lines. Now, with this latest enhancement, users can select a format from a list of options, including JSON and CSV. These output options allow for the SQL output to be viewable as a HTML table in the GUI, and provides an easier method to capture specific data elements using log filters–for example, using the JQ log filter with the JSON output format. This enhancement both provides an improved visual experience of retrieving database data but also reduces the steps to use that data in subsequent workflow steps.
31+
The [SQL Runner Node Step plugin](/manual/jobs/job-plugins/node-steps/sqlrunner.md) is commonly used to automate tasks or provide a self-service mechanism for interfacing with SQL databases–such as MySQL, MSSQL, Oracle and so on. Previously, the step would always return the output of the query as plain-text log-lines. Now, with this latest enhancement, users can select a format from a list of options, including JSON and CSV. These output options allow for the SQL output to be viewable as a HTML table in the GUI, and provides an easier method to capture specific data elements using log filters–for example, using the JQ log filter with the JSON output format. This enhancement both provides an improved visual experience of retrieving database data but also reduces the steps to use that data in subsequent workflow steps.
3232

3333

3434

‎docs/manual/jobs/job-plugins/node-steps/sqlrunner.md

Lines changed: 95 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,107 @@
11
# SQL Runner Plugin (Commercial)
22

3-
The SQLRunner plugin is a node step plugin included with Runbook Automation that executes a .sql script against a JDBC URL.
3+
The SQL Runner Plugin is a node step plugin that enables direct execution of SQL scripts and commands within your Rundeck workflows. This plugin supports running SQL statements against any database with JDBC connectivity, making it versatile for database automation tasks. Whether you need to perform database updates, run queries, or execute complex SQL scripts, this plugin provides a robust way to integrate database operations into your automation workflows.
44

5-
## Usage
5+
![SQL Runner Plugin](/assets/img/sqlrunner-plugin.png)
66

7-
Add "SQLRunner Plugin" as a step in a workflow.
7+
## Configuration
88

9-
Provider name: `org.rundeck.sqlrunner.SQLRunnerNodeStepPlugin`
9+
### Script Configuration
1010

11-
## Configuration
11+
- **Statement Delimiter** (optional)
12+
: Single character used to define the end of a statement when multiple statements are present
13+
- Default: '/'
14+
- Can be overridden in the script using the comment: `-- delimiter = ;`
15+
16+
- **SQL Script Source** (required, choose one)
17+
- **SQL script path**: File path or URL to the SQL script
18+
- Supports local files and HTTP(S) URLs
19+
- **SQL command(s)**: Inline SQL commands
20+
- Supports option value references (e.g., `${option.tablename}`)
21+
- Multiple statements supported
22+
23+
:::note
24+
If both script path and inline commands are provided, the plugin will use the script path and ignore the inline commands.
25+
:::
26+
27+
### Database Connection
28+
29+
- **JDBC Driver class name** (required)
30+
: The full class name of the JDBC driver
31+
- Example: `org.mariadb.jdbc.Driver`
32+
- Common drivers:
33+
- PostgreSQL: `org.postgresql.Driver`
34+
- MySQL: `com.mysql.jdbc.Driver`
35+
- MariaDB: `org.mariadb.jdbc.Driver`
36+
- Oracle: `oracle.jdbc.OracleDriver`
37+
38+
- **JDBC URL** (required)
39+
: The complete JDBC connection URL
40+
- Format varies by database type
41+
- Examples:
42+
- PostgreSQL: `jdbc:postgresql://hostname:5432/database`
43+
- MySQL: `jdbc:mysql://hostname:3306/database`
44+
45+
### Authentication
46+
47+
- **Username** (required)
48+
: Database connection username
1249

13-
- _Statement Delimiter_: Single character used to define the end of a statement when multiple statements are present. Default: '/'
14-
- _SQL script path_: Path to the sql script
15-
- _SQL inline script_: Alternative to sql script path.
16-
- _Variables_: comma separated list of variables values too be used as Prepared Statement.
17-
- _JDBC Driver class name_: e.g. `org.mariadb.jdbc.Driver`
18-
- _JDBC url_: full JDBC url to use for connections
19-
- _Database username_ connection username
20-
- _Database password_ connection password
21-
- _Auto commit flag_: if true, a `Connection::commit()` will be called after the script.
50+
- **Password** (required, choose one method)
51+
- **Password from key storage**: Securely stored in Rundeck's Key Storage
52+
- **Direct Password**: Plain text password (not recommended for production)
2253

54+
### Execution Options
55+
56+
- **Auto commit flag**
57+
: Controls transaction behavior
58+
- If true, executes `Connection::commit()` after the script
59+
- Default: false
60+
61+
- **Variables**
62+
: Comma-separated list of values for prepared statements
63+
- Replaces `?` placeholders in the SQL script
64+
- Format: `type:value` or simple `value`
65+
- Supported types:
66+
- `boolean`: Boolean values
67+
- `byte`: Byte values
68+
- `short`: Short integers
69+
- `int`: Integers
70+
- `long`: Long integers
71+
- `float`: Float numbers
72+
- `double`: Double numbers
73+
- `string`: Text strings
74+
75+
- **Output Format**
76+
: Controls how query results are displayed
77+
- Options:
78+
- `text`: Simple text output (default)
79+
- `table`: CSV-formatted table
80+
- `json`: JSON format
81+
82+
## Notes and Tips
2383

2484
:::tip
25-
Use a comment `-- delimiter = ;` at the beggining of the script file or inline script to override the **statement delimiter** property.
85+
For scripts with multiple statements, you can override the delimiter using a comment at the beginning of your script:
86+
87+
-- delimiter = ;
88+
CREATE TABLE users (...);
89+
INSERT INTO users (...);
2690
:::
2791

28-
## Usage of variables
29-
30-
The variable text field can receive a comma separated list of variables values too be used as Prepared Statement, this is, replacing a `?` variable in the script.
31-
The list of variables can be a list of values comma separated or using the format `type:value`.
32-
If you omit the type, it's going to be passed as generic object to the JDBC connector, this works only on some cases.
33-
## Example Job XML
34-
35-
```xml
36-
<joblist>
37-
<job>
38-
<description></description>
39-
<executionEnabled>true</executionEnabled>
40-
<id>c9704ff9-c34f-455e-aa4b-8f98eae9ed5b</id>
41-
<loglevel>INFO</loglevel>
42-
<name>SQL Test</name>
43-
<scheduleEnabled>true</scheduleEnabled>
44-
<sequence keepgoing='false' strategy='node-first'>
45-
<command>
46-
<node-step-plugin type='org.rundeck.sqlrunner.SQLRunnerNodeStepPlugin'>
47-
<configuration>
48-
<entry key='commit' value='true' />
49-
<entry key='jdbcDriver' value='org.mariadb.jdbc.Driver' />
50-
<entry key='jdbcUrl' value='asdf' />
51-
<entry key='password' value='password' />
52-
<entry key='scriptPath' value='/var/sql/dbupdate.sql' />
53-
<entry key='user' value='user' />
54-
</configuration>
55-
</node-step-plugin>
56-
</command>
57-
</sequence>
58-
<uuid>c9704ff9-c34f-455e-aa4b-8f98eae9ed5b</uuid>
59-
</job>
60-
</joblist>
61-
```
62-
63-
## Example Job XML using variables
64-
65-
```xml
66-
<joblist>
67-
<job>
68-
<description />
69-
<context>
70-
<options preserveOrder="true">
71-
<option name="name" required="true" />
72-
</options>
73-
</context>
74-
<executionEnabled>true</executionEnabled>
75-
<id>2d782a36-c06b-47fa-8ceb-7fcc9ff9fab7</id>
76-
<loglevel>INFO</loglevel>
77-
<name>SQL_test</name>v
78-
<scheduleEnabled>true</scheduleEnabled>
79-
<sequence keepgoing="false" strategy="node-first">
80-
<command>
81-
<node-step-plugin type="org.rundeck.sqlrunner.SQLRunnerNodeStepPlugin">
82-
<configuration>
83-
<entry key="commit" value="true" />
84-
<entry key="jdbcDriver" value="org.postgresql.Driver" />
85-
<entry key="jdbcUrl" value="jdbc:postgresql://wintermute/rundeck" />
86-
<entry key="password" value="rundeck" />
87-
<entry key="scriptBody" value="INSERT INTO test (id, version, args, date) VALUES(0, ?, ?, now());" />
88-
<entry key="user" value="rundeck" />
89-
<entry key="variables" value="int:0,string:${option.name}" />
90-
</configuration>
91-
</node-step-plugin>
92-
</command>
93-
</sequence>
94-
<uuid>2d782a36-c06b-47fa-8ceb-7fcc9ff9fab7</uuid>
95-
</job>
96-
</joblist>
97-
```
92+
:::warning
93+
When using password storage, ensure the key storage path is correctly set and accessible to the Rundeck server.
94+
:::
95+
96+
- Supports both local and URL-based script sources
97+
- Variables can be used for prepared statements to prevent SQL injection
98+
- Results can be formatted as text, CSV tables, or JSON
99+
- Transaction control through auto-commit configuration
100+
- Compatible with any database providing JDBC drivers
101+
102+
## Security Considerations
103+
104+
- Use Key Storage for database passwords instead of plain text
105+
- Consider using prepared statements with variables for dynamic SQL
106+
- Ensure proper database user permissions
107+
- Validate SQL scripts before deployment

0 commit comments

Comments
 (0)