sql-explainer

Explain SQL queries in plain language. npm/CLI package — runs locally, no SaaS, no API keys.

Installation

npm install @sgvolpe/sql-explainer

Usage

# From string
npx sql-explainer "SELECT * FROM users WHERE active = 1"

# From file
npx sql-explainer query.sql

API

import { explainSql } from '@sgvolpe/sql-explainer';

const result = explainSql('SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id WHERE o.total > 100');
// result.summary: "This query retrieves data from the database."
// result.steps: ["It reads from: users, orders", "It joins multiple tables together.", ...]
// result.tables: ["users", "orders"]
// result.operations: ["join", "filter"]

🔄 Difference from other packages

| Tool | Format | Our difference | |------|--------|----------------| | SQLAI.ai, Text2SQL.ai, ChartDB | Online SaaS — paste SQL in a web form | sql-explainer is an npm package and CLI. Use it in scripts, CI, or programmatically. No signup, no API keys. | | DBeaver AI Explain, Oracle AI Explain | Built into database tools | sql-explainer is standalone. Works with any SQL file or string. Integrate into your own tools. | | llm-to-sql, ormGPT | Natural language → SQL (opposite direction) | sql-explainer does SQL → natural language. You have a query, you want to understand it. | | Rule-based vs LLM | — | Current version uses rule-based parsing (no LLM). Works offline, fast, no cost. Can be extended with optional LLM for deeper explanations. |

TL;DR: Online tools = paste in browser. sql-explainer = npx sql-explainer query.sql in your terminal or import { explainSql } in your code. Fully local.