// This module is included in the following assemblies:
// as_connecting-to-databases.adoc

[id='about-parameter-placeholders-and-values_{context}']
= About parameter placeholders and values in SQL statements that update data

A database connection that is in the middle of a flow, or 
that finishes a simple integration, can execute a SQL statement 
that updates data. When you add a database connection to an integration, 
you can specify placeholder parameters in the SQL statement to be 
executed. During execution, the connection can perform a batch update 
when the input parameter values are in a collection. 

.Specifying parameters in SQL statements

When you create or edit an integration and you add a 
connection that updates a database, you can specify placeholder 
parameters in the SQL statement that the connection executes at 
runtime or there can be placeholders in the stored procedure 
that will be executed at runtime. For example: 

[source]
----
INSERT INTO TODO(task, completed) VALUES(:#param_1, :#param_2)
DELETE FROM TODO WHERE task LIKE :#param_3
----

To specify the values of these placeholders, add a data mapping step
to the flow before the database connection. In the data mapping
step, map the appropriate source data fields to the target data
fields, for example, map source data to the `:#param_1`, `:#param_2`, and
`:#param_3` target fields. See
link:{LinkSyndesisIntegrationGuide}#add-data-mapping-step_create[Adding a data mapper step].

.Batch update with a collection of parameter values 

At runtime, when a database connection executes a SQL statement that 
inserts, deletes, or updates data, the SQL statement being executed often 
specifies one or more 
placeholder parameters, for example, `:#task`. When it does, 
the input to the connection can be a single set of parameters 
or a collection of parameter sets, where each element in a set 
defines a value for the corresponding placeholder parameter. 

The input to the database connection comes from an earlier 
connection in the flow, for example, an HTTP request (Webhook) 
or a request sent to the REST API service for an API provider 
integration. When the input is a collection, 
the connection uses batch mode to update the table. 
For example, consider this SQL statement: 

----
insert into todo (task) values (:#task)
----

If the input collection contains 3 values, the connection inserts 
three records, one for each value. Now consider a SQL statement 
with two placeholder parameters:

----
insert into todo (task, completed) values (:#task, :#completed)
----
 
In the input to the connection that executes this SQL statement, 
a data shape specification could specify a single element, for example:

----
{"task": "write some docs", "completed": 0}
----

Or it could specify a collection, for example:

----
[{"task": "write doc", "completed": 1}, 
 {"task": "publish doc", "completed": 0}]
----
 
With a collection as input, the connection executes the insert operation 
once for each set of parameter values. In this example, the connection 
adds two records to the table, one for each set of parameter values. 
