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

# Database tools

> Query uploaded CSV and Excel files with SQL automatically, or connect a live PostgreSQL, MySQL, or MongoDB database read-only

## Overview

MagOneAI gives agents two distinct SQL capabilities:

* **Query uploaded files.** When a user uploads a tabular file — a CSV or Excel/XLSX spreadsheet — as an input to a workflow or agent, MagOneAI gives the agent a **SQL query tool** scoped to that file's data. The agent answers analytical questions by writing and running real SQL, instead of reasoning over thousands of rows of raw text. This is automatic and needs no configuration.
* **Query a live database.** The built-in **database** integration connects agents to a real PostgreSQL, MySQL, or MongoDB database, **read-only**. You configure the connection once, and a workspace can hold **more than one** connection.

Most of this page covers the uploaded-file query tool. See [Connecting to a live database](#connecting-to-a-live-database) for the database integration.

<Info>
  The uploaded-file query tool works on CSV and Excel inputs and needs no setup. To query a live PostgreSQL, MySQL, or MongoDB database, enable the built-in [database integration](#connecting-to-a-live-database). It is read-only. For any other engine, or to allow writes, build a [custom MCP tool](/tools/custom-tools) that wraps your database access.
</Info>

## How it works

<Steps>
  <Step title="A tabular file is provided as input">
    A CSV or XLSX file reaches the agent as a workflow input (for example at the Start node) or directly as an agent input. See [Triggers and execution](/workflows/triggers-and-execution) for how files enter a workflow.
  </Step>

  <Step title="The file is converted to a queryable table">
    Behind the scenes, MagOneAI reads the file and converts it to an efficient columnar format. The column names and types are detected automatically.
  </Step>

  <Step title="The agent gets a dedicated query tool">
    For each tabular input, the agent receives its own SQL query tool, **named after the input field**. The tool's description automatically includes the table's columns and schema, so the agent knows exactly what it can query.
  </Step>

  <Step title="The agent writes and runs SQL">
    During its reasoning loop, the agent writes a `SELECT` query, runs it against the file, and reads the results back — just like any other [tool call](/workflows/agent-node#tool-calling-loop).
  </Step>
</Steps>

## The query engine

Queries run on **DuckDB**, an in-process analytical SQL engine. Two things matter for how you design prompts and workflows:

* **It is read-only.** Only `SELECT` and `WITH` (CTE) queries are allowed. `INSERT`, `UPDATE`, `DELETE`, and any DDL (`CREATE`, `DROP`, `ALTER`, …) are rejected. The agent can read and analyze the uploaded data, but it can never modify it.
* **It speaks standard SQL.** Aggregations, filters, `GROUP BY`, `ORDER BY`, window functions, and CTEs all work, so the agent can express genuinely analytical questions.

**Example query an agent might run:**

```sql theme={null}
SELECT region, SUM(revenue) AS total_revenue
FROM sales
GROUP BY region
ORDER BY total_revenue DESC;
```

Because the column list is in the tool description, the agent constructs queries against the real schema rather than guessing column names.

## Querying multiple files

If several tabular files are supplied together as an array of inputs — **up to 10 files** — each becomes its own table, and the agent can **JOIN across them in a single query**.

**Example: joining two uploaded files:**

```sql theme={null}
SELECT c.company_name, SUM(o.amount) AS lifetime_value
FROM customers c
JOIN orders o ON o.customer_id = c.id
GROUP BY c.company_name
ORDER BY lifetime_value DESC;
```

This lets an agent reconcile, enrich, or cross-reference datasets — for example matching an uploaded contacts list against an uploaded transactions export — without any pre-processing step.

## What this is good for

Database tools shine whenever the answer lives in a spreadsheet and would be tedious or unreliable to reason over as plain text:

* **Aggregate questions** — "What's the total revenue by region?" or "What's the average order value per month?"
* **Data quality checks** — "Which rows are missing an email address?" or "How many duplicate IDs are there?"
* **Filtering and ranking** — "List the top 10 accounts by spend" or "Show every order over AED 50,000."
* **Cross-file analysis** — join an uploaded list against another uploaded export to find matches, gaps, or totals.

By delegating the counting and filtering to SQL, the agent spends its reasoning on interpreting results rather than arithmetic over raw rows.

## Connecting to a live database

Separately from the uploaded-file tool, the built-in **database** integration lets agents query a live database. It supports **PostgreSQL, MySQL, and MongoDB**, and it is **read-only** by design: `SELECT`-style reads run, while destructive statements (`INSERT`, `UPDATE`, `DELETE`, and DDL) are blocked automatically.

<Steps>
  <Step title="Add a connection string credential">
    In **Settings → Credentials**, add a `db_connection_string` credential in the form `postgresql://user:pass@host:5432/db` (or `mysql://…` or `mongodb://…`). Like all secrets, it is stored in HashiCorp Vault.
  </Step>

  <Step title="Configure one or more connections">
    A workspace isn't limited to a single database. You can configure **multiple connections** — for example a reporting replica and an analytics warehouse — each with its own name, and point an agent at the one it should use.
  </Step>

  <Step title="Agents query it read-only">
    Enabled agents get the database tool and can run read queries against the connection. Any attempt to modify data is rejected before it reaches the database.
  </Step>
</Steps>

<Warning>
  The built-in database integration is read-only across all three engines. There is no supported way to make it write. If a workflow must write to a database, wrap that access in a [custom MCP tool](/tools/custom-tools) with its own guardrails.
</Warning>

## Using it in a workflow

The uploaded-file query tool is part of file handling and agent tooling — there's no separate connection to configure.

<Steps>
  <Step title="Accept a tabular file input">
    Define a file input on your workflow trigger or agent. Provide a CSV or XLSX file at run time. See [Triggers and execution](/workflows/triggers-and-execution).
  </Step>

  <Step title="Run an Agent node">
    When the [Agent node](/workflows/agent-node) executes, the per-file query tool is attached automatically. No tool needs to be enabled by hand.
  </Step>

  <Step title="Prompt the agent to answer from the data">
    In the agent's instructions, tell it to answer questions by querying the file. The agent will choose when to call the query tool during its [tool-calling loop](/workflows/agent-node#tool-calling-loop).
  </Step>
</Steps>

**Example agent instruction:**

```
You are a data analyst. The user has uploaded a sales spreadsheet.
Answer their questions by querying the data with SQL using the query
tool, then explain the results in plain language. Always base numbers
on what the query returns — never estimate.
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent didn't query the file">
    **Symptoms:** The agent answers from guesswork or says it can't see the data.

    **Solutions:**

    * Confirm the file was actually provided as an input to the workflow or agent.
    * Confirm the file is CSV or Excel/XLSX — other file types don't get a query tool.
    * Make the instruction explicit: tell the agent to use the query tool to answer.
  </Accordion>

  <Accordion title="A write query was rejected">
    **Symptoms:** A query fails because it tried to modify data.

    **Solutions:**

    * The engine is read-only by design. Rewrite the request as a `SELECT` or `WITH` query.
    * There is no way to write back to the file — database tools are for analysis only.
  </Accordion>

  <Accordion title="The agent used the wrong column names">
    **Symptoms:** Queries fail with unknown-column errors.

    **Solutions:**

    * Column names come from the file's header row — make sure the spreadsheet has clear headers.
    * Avoid duplicate or blank header cells, which make columns ambiguous.
  </Accordion>

  <Accordion title="A JOIN across files didn't work">
    **Symptoms:** The agent can only see one table.

    **Solutions:**

    * Provide the files together as an array input (up to 10 files), so each becomes its own table.
    * Make sure the files share a column the agent can join on.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Triggers and execution" icon="bolt" href="/workflows/triggers-and-execution">
    Learn how files enter a workflow as inputs
  </Card>

  <Card title="Agents overview" icon="robot" href="/agents/overview">
    Understand how agents call tools during reasoning
  </Card>

  <Card title="Tools overview" icon="plug" href="/tools/overview">
    See all the tools your agents can use
  </Card>

  <Card title="Custom MCP tools" icon="puzzle-piece" href="/tools/custom-tools">
    Wrap a live database with a custom tool
  </Card>
</CardGroup>