# Actions: Jdbc

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Check JDBC connection](#check-jdbc-connection) — `com.install4j.runtime.beans.actions.jdbc.CheckJdbcConnectionAction`
- [Execute SQL query](#execute-sql-query) — `com.install4j.runtime.beans.actions.jdbc.SqlQueryAction`
- [Execute SQL script](#execute-sql-script) — `com.install4j.runtime.beans.actions.jdbc.ExecuteSqlScriptAction`
- [JDBC container action](#jdbc-container-action) — `com.install4j.runtime.beans.actions.jdbc.JdbcContainerAction`

---

### Check JDBC connection
- **Class:** `com.install4j.runtime.beans.actions.jdbc.CheckJdbcConnectionAction`
- **Category:** JDBC
- **Multiple instances:** yes

Check if a connection can be made to the configured JDBC database. If no connection can be made, the action will fail. If the action is attached to a form screen that queries a database location, set its "Error message" property to an appropriate error message and the "Failure strategy" property to "Return to the parent screen".

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `driverClassName` — JDBC Driver class name | String | Connection | — | The class name of the JDBC driver. The JDBC driver JAR file must be added to the "Installer->Custom code & Resources" step. |
| `jdbcUrl` — JDBC URL | String | Connection | — | The JDBC URL that will be used to connect to the database. For example, to connect to a MySQL database named "test" and installed locally, the connection string is jdbc:mysql://localhost/test. |
| `user` — User | String | Connection | — | The username for connecting to the database. Can be empty if no username is required. |
| `password` — Password | String | Connection | — | The password for connecting to the database. Can be empty if no password is required. |
| `jdbcProperties` — Additional JDBC properties | Map [context=jdbcProperties] | Connection | — | Additional properties for configuring the JDBC driver. Property definitions that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate property definitions, this allows you to build a variable length list of property definitions at runtime. |
| `logWarnings` — Log warnings | boolean | Connection | — | If selected, warnings from the database are logged. |
| `useCustomCheckSql` — Use a custom SQL query | boolean | Configuration | — | By default, the action executes "select 1 from dual" for Oracle databases and "select 1" for other databases. If you would like to use another statement, select this property. |
| `customCheckSql` — Custom SQL query | String | Configuration | `useCustomCheckSql`=true | An SQL query that returns at least one row. If the statement fails or of it returns zero rows, the action will fail. |
| `errorMessagesVariableName` — Variable name for error messages | String [context=variableName] | Connection | — | The name of the variable that will be set with the error messages that were logged during the execution of the action. There may be multiple error messages in the order of occurrence, each error message starts on a new line. If no error occurred, the variable will be set to the empty string.Enter the variable without the installer prefix and the dollar sign. |

### Execute SQL query
- **Class:** `com.install4j.runtime.beans.actions.jdbc.SqlQueryAction`
- **Category:** JDBC
- **Multiple instances:** yes

Execute a single SQL query and store the result in an installer variable. If only the first row is taken, the row value is stored directly. Otherwise, the variable will contain an instance of java.util.List with the row values. If the query is for a single column, the row value is the Java object representation of the return type, e.g. java.lang.String for VARCHAR or java.lang.Long for INT.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `driverClassName` — JDBC Driver class name | String | Connection | — | The class name of the JDBC driver. The JDBC driver JAR file must be added to the "Installer->Custom code & Resources" step. |
| `jdbcUrl` — JDBC URL | String | Connection | — | The JDBC URL that will be used to connect to the database. For example, to connect to a MySQL database named "test" and installed locally, the connection string is jdbc:mysql://localhost/test. |
| `user` — User | String | Connection | — | The username for connecting to the database. Can be empty if no username is required. |
| `password` — Password | String | Connection | — | The password for connecting to the database. Can be empty if no password is required. |
| `jdbcProperties` — Additional JDBC properties | Map [context=jdbcProperties] | Connection | — | Additional properties for configuring the JDBC driver. Property definitions that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate property definitions, this allows you to build a variable length list of property definitions at runtime. |
| `logWarnings` — Log warnings | boolean | Connection | — | If selected, warnings from the database are logged. |
| `sqlQuery` — SQL query | String [context=multiline] | SQL execution | — | The SQL query. For example, select count(*) from customers will return a single row with a single column. To get the integer result directly in the installer variable, you also have to select the "Take first row only" property, otherwise a List<Object> with one element will be stored in the variable.For queries that return multiple rows like select first_name, last_name from customer, each row is stored as an instance of List<Object>. If "Take first row only" is selected, the variable will contain that list, otherwise it will contain an instance of List<List<Object>> with the entire table of the result set. |
| `firstOnly` — Take first row only | boolean | SQL execution | — | If selected, the result will at most consist of a single row. If the result has only one column, the cell value will be stored directly in the installer variable, otherwise a List<Object> with all column values will be stored. Also, if no row is returned, the installer variable will be set to null.If not selected, the result will be a List<Object> for a single column and a List<List<Object>> for multiple columns. |
| `failIfNotFound` — Fail if zero rows returned | boolean | SQL execution | — | If selected, and zero rows are returned, the action will fail, and the installer variable will not be changed. |
| `variableName` — Variable name for result | String [context=variableName] | SQL execution | — | The name of the variable that will be set with the result of the query as explained in the descriptions of the "SQL query" and the "Take first row only" properties. Enter the variable without the installer prefix and the dollar sign, or leave empty if the error message should not be saved. |
| `errorMessagesVariableName` — Variable name for error messages | String [context=variableName] | SQL execution | — | The name of the variable that will be set with the error messages that were logged during the execution of the action. There may be multiple error messages in the order of occurrence, each error message starts on a new line. If no error occurred, the variable will be set to the empty string.Enter the variable without the installer prefix and the dollar sign. |

### Execute SQL script
- **Class:** `com.install4j.runtime.beans.actions.jdbc.ExecuteSqlScriptAction`
- **Category:** JDBC
- **Multiple instances:** yes

Execute a single SQL statement or a script of SQL statements.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `driverClassName` — JDBC Driver class name | String | Connection | — | The class name of the JDBC driver. The JDBC driver JAR file must be added to the "Installer->Custom code & Resources" step. |
| `jdbcUrl` — JDBC URL | String | Connection | — | The JDBC URL that will be used to connect to the database. For example, to connect to a MySQL database named "test" and installed locally, the connection string is jdbc:mysql://localhost/test. |
| `user` — User | String | Connection | — | The username for connecting to the database. Can be empty if no username is required. |
| `password` — Password | String | Connection | — | The password for connecting to the database. Can be empty if no password is required. |
| `jdbcProperties` — Additional JDBC properties | Map [context=jdbcProperties] | Connection | — | Additional properties for configuring the JDBC driver. Property definitions that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate property definitions, this allows you to build a variable length list of property definitions at runtime. |
| `logWarnings` — Log warnings | boolean | Connection | — | If selected, warnings from the database are logged. |
| `scriptSource` — Script source | [ScriptSource](enums.md#scriptsource) | Script Execution | — | You can either enter the SQL statements directly in the install4j IDE, or read a file that contains the SQL script. In both cases, installer variables will be replaced. |
| `script` — SQL script | String [context=multiline] | Script Execution | `scriptSource`=Direct entry | Either a single SQL statement or a sequence of statements separated by the configured delimiter. Installer variables will be replaced before the execution. If no delimiter is found, the entire input is treated as a single SQL statement. |
| `scriptFile` — SQL script file | ExternalFile [context=externalOrInternal] | Script Execution | `scriptSource`=Read from file | A file containing the SQL script, either a single SQL statement or a sequence of statements separated by the configured delimiter. Installer variables will be replaced before the execution.The file may also be gzipped (with the Unix gzip command line utility), the action will then automatically decompress the file on the fly. |
| `encoding` — Encoding | String | Script Execution | `scriptSource`=Read from file | The encoding of the file. If you leave this empty, the system default will be used. Common encodings are UTF-8, UTF-16, ISO-8859-1. |
| `delimiter` — Statement delimiter | String | Script Execution | — | A regular expression that separates SQL statements. To match line breaks, enter $. If the delimited contains characters that have a special meaning in regular expressions, you have to quote them, like in \\. for a literal dot. |
| `commitEachStatement` — Commit each statement | boolean | Script Execution | — | If selected, each SQL statement will be committed separately. Otherwise, the entire script will be committed at the end. If the script contains a single statement, the setting has no effect. |
| `ignoreErrors` — Ignore errors | boolean | Script Execution | — | If selected, errors from single SQL statements will be ignored, and processing will not be stopped. Otherwise, processing stops at the first error and a database rollback will be performed unless "Commit each statement" is selected. |
| `errorMessagesVariableName` — Variable name for error messages | String [context=variableName] | Script Execution | — | The name of the variable that will be set with the error messages that were logged during the execution of the action. There may be multiple error messages in the order of occurrence, each error message starts on a new line. If no error occurred, the variable will be set to the empty string.Enter the variable without the installer prefix and the dollar sign. |

### JDBC container action
- **Class:** `com.install4j.runtime.beans.actions.jdbc.JdbcContainerAction`
- **Category:** JDBC
- **Multiple instances:** yes

This action allows you to configure connection properties just once and then execute a list of JDBC actions with the same connection.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `driverClassName` — JDBC Driver class name | String | Connection | — | The class name of the JDBC driver. The JDBC driver JAR file must be added to the "Installer->Custom code & Resources" step. |
| `jdbcUrl` — JDBC URL | String | Connection | — | The JDBC URL that will be used to connect to the database. For example, to connect to a MySQL database named "test" and installed locally, the connection string is jdbc:mysql://localhost/test. |
| `user` — User | String | Connection | — | The username for connecting to the database. Can be empty if no username is required. |
| `password` — Password | String | Connection | — | The password for connecting to the database. Can be empty if no password is required. |
| `jdbcProperties` — Additional JDBC properties | Map [context=jdbcProperties] | Connection | — | Additional properties for configuring the JDBC driver. Property definitions that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate property definitions, this allows you to build a variable length list of property definitions at runtime. |
| `logWarnings` — Log warnings | boolean | Connection | — | If selected, warnings from the database are logged. |
| `actionList` — JDBC actions | ActionList (action list) | Configuration | — | The JDBC actions that should be executed run with the same connection. |

