ajan-sql

library0.3.0jsnpmunverified

ajan-sql is an MCP (Model Context Protocol) server that provides safe, read-only SQL access to PostgreSQL, MySQL, and SQLite databases for AI agents. Version 0.3.0 (as of this entry) enforces strict guardrails: only SELECT queries allowed, no INSERT/UPDATE/DELETE, no DDL, no multi-statement, no comments, result limit of 100 rows, and a 5-second timeout. It offers tools like list_tables, describe_table, run_readonly_query, and explain_query. Its key differentiator is that safety rules are enforced at the server level and cannot be bypassed, making it ideal for AI copilots and automation. Human approval flows are delegated to the MCP host. The package ships TypeScript types and can be run via npx or global install.

database ai-ml

npm install ajan-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AJAN-SQL

ajan-sql

databasejavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

runReadonlyQuery

✓ import { runReadonlyQuery } from 'ajan-sql'

✗ import runReadonlyQuery from 'ajan-sql'

Named export, not default. Only available in ESM context; package is ESM-only.

listTables

✓ import { listTables } from 'ajan-sql/tools'

✗ import { listTables } from 'ajan-sql'

Most tools are exported from ajan-sql/tools subpath; check docs for exact exports.

AjanSqlServer

✓ import { AjanSqlServer } from 'ajan-sql/server'

✗ import { AjanSqlServer } from 'ajan-sql'

Server class is exported from 'ajan-sql/server'. For custom programmatic use.

Shows how to run ajan-sql via npx with environment variables and programmatic usage with runReadonlyQuery.

// Run via npx with environment variables // DATABASE_URL: connection string, DATABASE_DIALECT: 'postgres'|'mysql'|'sqlite' // Example: DATABASE_URL=postgres://user:pass@localhost:5432/mydb DATABASE_DIALECT=postgres npx ajan-sql // Programmatic usage (ESM) import { runReadonlyQuery } from 'ajan-sql'; const result = await runReadonlyQuery({ sql: 'SELECT * FROM users LIMIT 10', databaseUrl: process.env.DATABASE_URL ?? '', dialect: 'postgres' }); console.log(result);

Debug

Known issues

gotchaajan-sql enforces LIMIT 100 on all queries; queries that return more than 100 rows will be truncated.

fix

Use pagination or aggregate queries to work within the limit. There is no way to increase it.

affects: >=0.1.0

gotchaMulti-statement queries (e.g., 'SELECT 1; SELECT 2') are rejected for security reasons.

fix

Send each statement as a separate request.

affects: >=0.1.0

gotchaComments in SQL (--, /* */) are stripped and the query may fail if comments are essential.

fix

Remove comments from SQL before sending.

affects: >=0.1.0

gotchaTimeout is set to 5 seconds; queries taking longer will be aborted.

fix

Optimize queries or break them into smaller chunks.

affects: >=0.1.0

deprecatedVersion 0.2.x introduced the 'ajan-sql.conf' config file; it is now deprecated in favor of environment variables only.

fix

Use environment variables (DATABASE_URL, DATABASE_DIALECT, etc.) instead of config file.

affects: 0.2.x - 0.3.0

Errors

Common errors & fixes

Error: Unsupported database dialect. Supported: postgres, mysql, sqlite

DATABASE_DIALECT environment variable is missing or set to an unsupported value.

fix

Set DATABASE_DIALECT to 'postgres', 'mysql', or 'sqlite'.

Error: Only SELECT queries are allowed

An INSERT, UPDATE, DELETE, or DDL statement was sent to runReadonlyQuery.

fix

Ensure the SQL statement is a SELECT or use other tools like describe_table.

Error: Query too long (max 10000 characters)

SQL query exceeds 10,000 character limit.

fix

Shorten the query or break it into smaller parts.

Module not found: Can't resolve 'ajan-sql'

Attempting to import in a CommonJS context; ajan-sql is ESM-only.

fix

Use dynamic import: const { runReadonlyQuery } = await import('ajan-sql'); or ensure 'type': 'module' in package.json.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

mcprequiredMCP SDK used to implement the Model Context Protocol server

Agent activity

50 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/borakilicoglu/ajan-sql ↗

packageajan-sql ↗

homepagehttps://borakilicoglu.github.io/ajan-sql/ ↗