= sql
:type: processor
:status: deprecated
:categories: ["Integration"]



////
     THIS FILE IS AUTOGENERATED!

     To make changes, edit the corresponding source file under:

     https://github.com/redpanda-data/connect/tree/main/internal/impl/<provider>.

     And:

     https://github.com/redpanda-data/connect/tree/main/cmd/tools/docs_gen/templates/plugin.adoc.tmpl
////

// © 2024 Redpanda Data Inc.


component_type_dropdown::[]


[WARNING]
.Deprecated
====
This component is deprecated and will be removed in the next major version release. Please consider moving onto <<alternatives,alternative components>>.
====
Runs an arbitrary SQL query against a database and (optionally) returns the result as an array of objects, one for each row returned.

Introduced in version 3.65.0.


[tabs]
======
Common::
+
--

```yml
# Common config fields, showing default values
label: ""
sql:
  driver: "" # No default (required)
  data_source_name: "" # No default (required)
  query: INSERT INTO footable (foo, bar, baz) VALUES (?, ?, ?); # No default (required)
  args_mapping: root = [ this.cat.meow, this.doc.woofs[0] ] # No default (optional)
  result_codec: none
```

--
Advanced::
+
--

```yml
# All config fields, showing default values
label: ""
sql:
  driver: "" # No default (required)
  data_source_name: "" # No default (required)
  query: INSERT INTO footable (foo, bar, baz) VALUES (?, ?, ?); # No default (required)
  unsafe_dynamic_query: false
  args_mapping: root = [ this.cat.meow, this.doc.woofs[0] ] # No default (optional)
  result_codec: none
```

--
======

If the query fails to execute then the message will remain unchanged and the error can be caught using xref:configuration:error_handling.adoc[error handling methods].

== Alternatives

For basic inserts or select queries use either the xref:components:processors/sql_insert.adoc[`sql_insert`] or the xref:components:processors/sql_select.adoc[`sql_select`] processor. For more complex queries use the xref:components:processors/sql_raw.adoc[`sql_raw`] processor.

== Fields

=== `driver`

A database <<drivers, driver>> to use.


*Type*: `string`


Options:
`mysql`
, `postgres`
, `clickhouse`
, `mssql`
, `sqlite`
, `oracle`
, `snowflake`
, `trino`
, `gocosmos`
.

=== `data_source_name`

Data source name.


*Type*: `string`


=== `query`

The query to execute. The style of placeholder to use depends on the driver, some drivers require question marks (`?`) whereas others expect incrementing dollar signs (`$1`, `$2`, and so on) or colons (`:1`, `:2` and so on). The style to use is outlined in this table:

| Driver | Placeholder Style |
|---|---|
| `clickhouse` | Dollar sign |
| `mysql` | Question mark |
| `postgres` | Dollar sign |
| `mssql` | Question mark |
| `sqlite` | Question mark |
| `oracle` | Colon |
| `snowflake` | Question mark |
| `trino` | Question mark |
| `gocosmos` | Colon |


*Type*: `string`


```yml
# Examples

query: INSERT INTO footable (foo, bar, baz) VALUES (?, ?, ?);
```

=== `unsafe_dynamic_query`

Whether to enable xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions] in the query. Great care should be made to ensure your queries are defended against injection attacks.


*Type*: `bool`

*Default*: `false`

=== `args_mapping`

An optional xref:guides:bloblang/about.adoc[Bloblang mapping] which should evaluate to an array of values matching in size to the number of placeholder arguments in the field `query`.


*Type*: `string`


```yml
# Examples

args_mapping: root = [ this.cat.meow, this.doc.woofs[0] ]

args_mapping: root = [ meta("user.id") ]
```

=== `result_codec`

Result codec.


*Type*: `string`

*Default*: `"none"`