eve-sql-tool

Give your Eve agent a focused, read-only way to query PostgreSQL or SQLite.

eve-sql-tool turns a database and a focused table list into one schema-aware, read-only SQL tool for Eve. It discovers the schema automatically, tells the model what it can query, and returns compact TOON results.

No schema copy-pasting and no custom SQL execution code to maintain.

✨ Features

• 🧠 Schema-aware — the model sees real tables, columns, types, nullability, and primary keys.
• 🔒 Read-only by default — basic query checks plus database-native read-only modes.
• 🎯 Focused context — only configured tables are introspected and shown to the model.
• 📦 Compact — TOON (Token-Oriented Object Notation) avoids repeating JSON keys in tabular results.
• ⚡ Lazy and cached — the schema loads on the first Eve session, once per defined tool.
• 🪶 Separate adapters — install only the database drivers your project needs.

🚀 Quick start

Install the package, Eve, and your PostgreSQL driver:

pnpm add eve-sql-tool eve pg

Create agent/tools/analytics.ts in your Eve project:

import { defineSqlTool } from "eve-sql-tool";
import { postgres } from "eve-sql-tool/postgres";

export default defineSqlTool({
  database: postgres(process.env.DATABASE_URL!),
  tables: ["orders", "customers"],
  maxRows: 100,
  description: `
    Sales analytics.
    Revenue includes only paid orders.
  `,
});

Start the local Eve runtime:

pnpm exec eve dev

Eve discovers the tool from its filename and makes it available as analytics.

Prefer one tool per business domain. A focused set of related tables gives the model better context than an entire database.

🧠 What does the model see?

You don't need to pass your database schema in the prompt. eve-sql-tool introspects the configured tables and builds the tool description automatically.

For the configuration above, Eve exposes context like this:

Query a PostgreSQL database using read-only SQL.

Business context:

Sales analytics.
Revenue includes only paid orders.

Available tables:

orders
- id: bigint, not null, primary key
- customer_id: bigint, not null
- status: text, not null
- total: numeric(12,2), not null

customers
- id: bigint, not null, primary key
- country: text, nullable

Rules:
- Write one read-only SELECT query.
- Only use the listed tables.
- Do not modify the database.
- Results are limited to 100 rows.

The model now knows the actual schema before it writes SQL.

Example tool call

User asks:

Show me the three largest paid orders.

The model calls the tool with one query:

{
  "query": "SELECT id, total FROM orders WHERE status = 'paid' ORDER BY total DESC LIMIT 3"
}

The tool returns compact TOON to the model:

rows[3]{id,total}:
  1842,"920.00"
  731,"875.50"
  2049,"810.00"
truncated: false

No repeated JSON keys for every row. When the configured limit is exceeded, truncated becomes true.

maxRows is optional and defaults to 100.

SQLite adapter

Install the package, Eve, and the SQLite driver:

pnpm add eve-sql-tool eve better-sqlite3

Then create a tool under agent/tools/:

import { defineSqlTool } from "eve-sql-tool";
import { sqlite } from "eve-sql-tool/sqlite";

export default defineSqlTool({
  database: sqlite("./analytics.db"),
  tables: ["orders", "customers"],
  maxRows: 100,
  description: "Local sales analytics.",
});

🔌 Custom database adapters

Other databases can be supported by implementing the exported SqlDatabase interface.

interface SqlDatabase {
  readonly dialect: string;
  introspect(tables: string[]): Promise<DatabaseSchema>;
  query(sql: string, options: SqlQueryOptions): Promise<QueryResult>;
}

To match the built-in adapters' behavior, a custom adapter should:

• introspect only the configured tables;
• accept a single SELECT-shaped query;
• enforce options.maxRows and report whether the result was truncated;
• sanitize database errors before returning them to the model; and
• use the database's native read-only protections where available.

🛡️ Read-only safety

The built-in adapters perform a small, conservative SELECT/WITH shape check, sanitize errors, and add database-native protection: read-only transactions in PostgreSQL and read-only/query-only modes in SQLite.

The configured tables list controls schema introspection and model context. It is not a query authorization boundary.

Query errors are returned to the model as concise, sanitized messages, so it can correct and retry the query.

[!IMPORTANT] eve-sql-tool reduces accidental writes, but it is not a SQL sandbox. Database permissions remain the security boundary.

For production, use dedicated read-only credentials and expose only the tables or views the agent needs. Read the complete security model.

🚧 Current limitations

The package currently supports Eve, PostgreSQL, SQLite, automatic schema context, configurable row limits, and TOON output. The schema cache is in memory.

It does not currently include query parameters, schema refresh, streaming, telemetry, or support for other agent frameworks.

🧑‍💻 Development

Requires Node.js 24+ and pnpm.

pnpm install
pnpm run check
pnpm run test
pnpm run build