> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alumio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute SQL query

> Executes SQL queries.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Runs a SQL query against a database and places the rows it returns into your data. Use this to read records straight from a database in the middle of a route, for example pulling order lines, looking up stock levels, or fetching customer details to enrich the data flowing through. The rows come back as a list at the location you choose, ready for the next steps to work with.

This documentation describes: [Schema](/schemas/transformer/pdo-transformer)

## Fields

<FormField property="client" label="Database connection" required diType="database-connection">
  The pre-configured connection that decides which database to talk to, including its type, driver, and credentials. You select an existing database connection here.
</FormField>

<FormField property="destination" label="Destination" required>
  The location in your data where the returned rows are placed. Whatever was at that location is replaced with the list of rows. Placeholders are supported, so the destination can be built from the data.
</FormField>

<FormField property="queryType" label="Query Type" required>
  The kind of query to run. Currently the only choice is **Raw Query**, where you write the SQL yourself.
</FormField>

<FormField property="rawQuery" label="Query" required>
  The SQL statement to run, written as free text. Placeholders are supported, so you can build the query from values in your data, for example `SELECT * FROM products WHERE sku = '&{sku}'`. Bear in mind that the statements you can run depend on the rights of the account in the connection, so take care with accounts that can change structure or delete data.
</FormField>

<FormField property="logger" label="Logging" diType="database-query-logger">
  Chooses how this query is recorded for troubleshooting.
</FormField>

<FormField property="bypassDoctrine" label="Use SQL procedure query strategy">
  An alternative way of running the query, intended for stored procedures that may return more than one set of rows. Leave it off for ordinary queries. Off by default.
</FormField>

## Sample data

This step runs a live query against the database, so the rows you get back depend on the data in your database. The example below looks up a product by the incoming `sku` and places the matching rows at `matches`.

| Field               | Value                                                        |
| ------------------- | ------------------------------------------------------------ |
| Database connection | The configured database connection                           |
| Query               | `SELECT sku, name, price FROM products WHERE sku = '&{sku}'` |
| Destination         | `matches`                                                    |

For an input of `{ "sku": "SHIRT-RED-M" }`, the returned rows are placed at `matches`:

```json theme={null}
{
    "sku": "SHIRT-RED-M",
    "matches": [
        {
            "sku": "SHIRT-RED-M",
            "name": "Red T-Shirt M",
            "price": 19.95
        }
    ]
}
```

A query that returns no columns (such as an `UPDATE` or `INSERT`) places an empty list at the destination.

```json Configuration theme={null}
{
  "prototype": "pdo-transformer",
  "parameters": {
    "client": "default",
    "destination": "matches",
    "queryType": "rawQuery",
    "rawQuery": "SELECT sku, name, price FROM products WHERE sku = '&{sku}'"
  }
}
```

See [Placeholders](/references/placeholders) for how to reference values such as `&{sku}` when building the query.