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

# SQL Database

> Query databases (SQLite, PostgreSQL, MySQL) from your agent.

# SQL Database

Query databases directly from your agent. Supports SQLite, PostgreSQL, and MySQL with read-only safety mode.

<Info>
  Requires the appropriate database driver as a peer dependency: `better-sqlite3`, `pg`, or `mysql2`.
</Info>

***

## Quick Start

```typescript theme={null}
import { Agent, openai, SqlToolkit } from "@agentium/core";

const sql = new SqlToolkit({
  dialect: "sqlite",
  connectionString: "./analytics.db",
});

const agent = new Agent({
  name: "data-analyst",
  model: openai("gpt-4o"),
  instructions: "Query the database to answer questions about the data.",
  tools: [...sql.getTools()],
});

const result = await agent.run("What are the top 10 users by order count?");
```

***

## Config

<ParamField body="dialect" type="'sqlite' | 'postgres' | 'mysql'" required>
  Database dialect.
</ParamField>

<ParamField body="connectionString" type="string" required>
  Connection string (for postgres/mysql) or file path (for sqlite).
</ParamField>

<ParamField body="readOnly" type="boolean" default="true">
  Restrict to read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN, PRAGMA, WITH).
</ParamField>

<ParamField body="maxRows" type="number" default="100">
  Max rows to return per query.
</ParamField>

***

## Tools

| Tool           | Description                                           |
| -------------- | ----------------------------------------------------- |
| `sql_query`    | Execute a SQL query. Returns formatted table results. |
| `sql_tables`   | List all tables in the database.                      |
| `sql_describe` | Describe the schema (columns, types) of a table.      |

***

## Peer Dependencies

Install the driver for your database:

```bash theme={null}
# SQLite
npm install better-sqlite3

# PostgreSQL
npm install pg

# MySQL
npm install mysql2
```

***

## Security

The SQL toolkit includes built-in protections:

* **Read-only mode** (default): Only `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA`, and `WITH` queries are permitted.
* **Parameterized queries**: Schema introspection (`sql_describe`) uses parameterized queries (`$1` bind parameters) for PostgreSQL to prevent SQL injection.
* **Table name validation**: Table names are validated against `^[a-zA-Z_]\w*$` to reject injection attempts.

<Warning>
  Read-only mode is enabled by default. Set `readOnly: false` only if your agent needs to write data.
</Warning>

See the [Security](/security) page for a full overview of security hardening across Agentium.