> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/modules/ai-agents/workflows-and-actions/sql-query.md).

# SQL query

`Action` — Executes a read-only SQL query against a connected database. Only `SELECT` queries are permitted.

## What it does

Queries a connected database mid-chat and stores the result in a variable for use by downstream actions.

## When to use it

To read live data directly from your own database during a chat — looking up a record or checking a status — when the data is in a database rather than behind an API.

## Settings

| Setting                     | Description                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Database connector**      | The connected database to query. Connections must first be verified in Database connections settings.                               |
| **Query**                   | The SQL `SELECT` statement, entered as a [chat script](/docs/developers/chat-scripts.md) expression. Only read queries are allowed. |
| **Timeout after (seconds)** | The maximum query execution time before the action times out.                                                                       |
| **Resulting variable**      | The chat variable that stores the query result. Must start with a letter and contain only letters, numbers, or underscores.         |

Press **Save** to confirm edits.

## Outcome branches

The action branches into **Success**, **Error**, and **Timeout**. Nest subsequent actions under each as needed.

## Example

```
SQL query
• Connector: complaints_db
• Query:     SELECT status FROM complaints WHERE ref = {complaint_ref}
• Result:    complaint_status
```

## Related

{% content-ref url="/pages/dS84QlBWMPsz088Q7VcB" %}
[Send API](/docs/modules/ai-agents/workflows-and-actions/send-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/yRuISyntS8UJxaE5kgNX" %}
[Branch](/docs/modules/ai-agents/workflows-and-actions/branch.md)
{% endcontent-ref %}