Skip to main content

​
SQL Database

Query databases directly from your agent. Supports SQLite, PostgreSQL, and MySQL with read-only safety mode.
Requires the appropriate database driver as a peer dependency: better-sqlite3, pg, or mysql2.

​
Quick Start

import { Agent, openai, SqlToolkit } from "@radaros/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

​
dialect
'sqlite' | 'postgres' | 'mysql'
required
Database dialect.
​
connectionString
string
required
Connection string (for postgres/mysql) or file path (for sqlite).
​
readOnly
boolean
default:"true"
Restrict to read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN, PRAGMA, WITH).
​
maxRows
number
default:"100"
Max rows to return per query.

​
Tools

ToolDescription
sql_queryExecute a SQL query. Returns formatted table results.
sql_tablesList all tables in the database.
sql_describeDescribe the schema (columns, types) of a table.

​
Peer Dependencies

Install the driver for your database: 
# 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.
Read-only mode is enabled by default. Set readOnly: false only if your agent needs to write data.
See the Security page for a full overview of security hardening across RadarOS.