SQL File Explainer

It explains your SQL file. No live database, no API key required, no network by default.

A Visual Studio Code extension that explains your SQL schema and migration files directly inside the editor — as a chat participant, a right-click command, or a standalone MCP server for other AI tools. It reads only the .sql files already in your workspace: no live database connection, no credentials, and no schema data leaves your machine unless you explicitly turn on a cloud model.

About
Why This Extension
Meet Schemer
Features
Installation
Usage
Commands
Settings
How It Works
MCP Server
Build From Source
Contributing
Roadmap
License
Acknowledgments
Authors
Contact Us

About

You open a schema you didn't design, or a migration someone else wrote, and you need to know what it does. Ask, and get an answer grounded in the actual .sql files in your workspace — no need to spin up the database, request credentials, or wait for whoever wrote the migration to explain it.

No database connection. No credentials. Nothing invented — if it's not in your schema, the answer says so instead of guessing.

Why This Extension

Most "chat with your database" tools solve a different problem: connect to a live database and ask analytics questions about the data inside it. That space is already crowded — Microsoft ships schema-aware Copilot chat natively for SQL Server and PostgreSQL, and open-source engines like Vanna.ai already do live-database Q&A well.

What none of them cover is the narrower, file-only case: understanding structure, not data, with no live connection at all.

Need	Live-DB chat tools	SQL File Explainer
Onboard onto a schema you didn't design	Requires DB credentials	Reads the `.sql` files only
Review a migration before merging it	Not their focus	`Explain this SQL file`, migration diff
Generate types/ORM models from schema	Not their focus	Built in
Works with no database running	No	Yes
Schema/data ever leaves your machine	Depends on the tool	Never, unless you opt into a cloud key

This isn't a smaller version of a live-database chatbot. It solves a task those tools don't attempt: explaining a schema from files alone.

Meet Schemer

Every answer inside VS Code comes from Schemer — the persona behind the @schemer chat participant. Schemer has one job and stays honest about its limits:

Answers only from the .sql files it has indexed — never a live database, never invented columns
Always names the specific table(s) or column(s) an answer is about, and cites the source file and line
Says "that's not in your schema" instead of guessing when the context doesn't contain the answer
Keeps answers short — you're mid-task in an editor, not reading a report

Say hello with @schemer in Copilot Chat and ask anything about your indexed schema.

Features

Core Engine (Local RAG Pipeline)

Schema chunking — one chunk per table, with foreign-key relationships stored as metadata
Local embeddings by default (dependency-free hashing provider, zero install, zero network)
Optional richer embeddings via transformers.js, opt-in and lazy-loaded
A lightweight local vector index with disk-backed caching
Pluggable LLM providers — local Ollama by default, or bring-your-own-key Anthropic/OpenAI
Incremental re-indexing on file create, change, and delete

Chat, Commands & Settings

@schemer chat participant inside Copilot Chat, with follow-up suggestions
Right-click Explain this SQL file on any .sql file
Settings for provider, cloud provider kind, embedding method, and schema folder path
Cloud API keys stored via VS Code SecretStorage — never in settings.json

Beyond the MVP

Migration diff — compare two schema snapshots and get a plain-English summary of what changed and what it breaks
Type generation — turn a parsed schema into TypeScript interfaces
Relationship graph — the full foreign-key graph across your schema, exportable as Graphviz DOT
MCP server — the same engine, exposed to Cursor, Windsurf, Claude Code, or any MCP client, outside VS Code entirely

Tested, Not Just Written

Unit tests for every engine module — chunking, both embedding paths, the vector store, migration diff, type generation, the relationship graph, and the engine itself — runnable without the VS Code test host
VS Code integration tests via @vscode/test-electron
GitHub Actions CI on every push and pull request

Installation

SQL File Explainer is not yet published to the VS Code Marketplace. Until then, install it from source or from a packaged .vsix.

From a `.vsix` file

# Build the .vsix yourself (see Build From Source), then:
code --install-extension sql-file-explainer-0.1.0.vsix

From source (Extension Development Host)

git clone https://github.com/aflinrinosha2004/sql-schema-copilot.git
cd sql-schema-copilot
npm install
npm run compile
# Press F5 in VS Code to launch the Extension Development Host

Usage

Open a workspace that has a schema folder (or set sqlFileExplainer.schemaFolderPath) containing .sql files
Open Copilot Chat and type @schemer explain the orders table
Or right-click any .sql file → Explain this SQL file
Keep asking — Schemer re-indexes automatically whenever a schema file changes

By default, answers are generated by a local Ollama instance. To use a cloud model instead:

Ctrl+Shift+P → SQL File Explainer: Set Cloud API Key

then set sqlFileExplainer.provider to cloud and sqlFileExplainer.cloudProviderKind to anthropic or openai.

Commands

Command	What it does
`SQL File Explainer: Explain this SQL file`	Summarizes and explains the table(s) in the selected `.sql` file
`SQL File Explainer: Set Cloud API Key`	Stores a cloud provider API key securely in SecretStorage
`@schemer <question>`	Ask Schemer anything about your indexed tables, in Copilot Chat

Settings

Setting	Default	Description
`sqlFileExplainer.provider`	`local`	`local` (Ollama) or `cloud` (bring-your-own-key)
`sqlFileExplainer.cloudProviderKind`	`anthropic`	`anthropic` or `openai`, used when `provider` is `cloud`
`sqlFileExplainer.embeddingProvider`	`hashing`	`hashing` (default, no extra install) or `transformers-js` (richer, requires `npm install @xenova/transformers`)
`sqlFileExplainer.schemaFolderPath`	`schema`	Relative path to the folder containing SQL files
`sqlFileExplainer.cloudApiKey`	(empty)	Stored via SecretStorage. Do not edit this in `settings.json`

How It Works

.sql files
  │
  ├─▶ 1. WATCH     detect create/change/delete under the schema folder
  ├─▶ 2. PARSE     node-sql-parser → tables, columns, types, foreign keys
  ├─▶ 3. CHUNK     one chunk per table, related tables attached as metadata
  ├─▶ 4. EMBED     local embedding (hashing, or transformers.js if enabled)
  ├─▶ 5. INDEX     local vector store, cached to disk, updated incrementally
  ├─▶ 6. RETRIEVE  question → embedding → top-k matching chunks
  ├─▶ 7. GROUND    chunks + question → a prompt Schemer can only answer from
  └─▶ 8. ANSWER    local Ollama or your own cloud key, streamed into chat

Nothing in steps 1–6 ever leaves your machine. Only step 8 can reach the network, and only if you have explicitly configured a cloud provider.

MCP Server

The same engine that powers the VS Code chat participant is also available as a standalone Model Context Protocol server, so any MCP-compatible client — Cursor, Windsurf, Claude Code — can ask it the same questions.

npm run mcp:start -- <path-to-schema-folder>

This exposes two tools:

Tool	Arguments	Returns
`askQuestion`	`question: string`	A grounded answer with source citations
`explainFile`	`filePath: string`	An explanation of the table(s) in that file

Build From Source

# 1. Clone
git clone https://github.com/aflinrinosha2004/sql-schema-copilot.git
cd sql-schema-copilot

# 2. Install dependencies
npm install

# 3. Build (esbuild, bundles the extension, the MCP server, and the tests)
npm run compile

# 4. Run the engine unit tests (no VS Code host required)
npm run test:unit

# 5. Run the full suite, including VS Code integration tests
npm test

# 6. Launch the Extension Development Host
#    Press F5 in VS Code

Script	Purpose
`npm run compile`	Production build via esbuild
`npm run watch`	Rebuild on save
`npm run test:unit`	Engine unit tests only, no VS Code host
`npm test`	Full suite, including VS Code integration tests
`npm run mcp:start -- <folder>`	Run the standalone MCP server against a schema folder

Contributing

Contributions are welcome — especially additional SQL dialect support, new chat follow-ups, and more engine test coverage.

Fork the repository and create a feature branch
Keep the shared contract in mind: the parsing layer produces ParsedSchema, the engine implements SchemaEngine (explainFile, askQuestion) — changes to either shape affect both sides
Add or update tests under src/test/suite/
Run npm run compile && npm run test:unit before opening a pull request

Roadmap

[ ] Additional SQL dialect support (MySQL, SQLite, SQL Server syntax variants)
[ ] Multi-file relationship graph rendered visually in a webview
[ ] Chat commands for migration diff and type generation directly from @schemer
[ ] VS Code Marketplace publish

Have a request? Open an issue.

License

This project is released under the MIT License. You are free to use, modify, and distribute it under the terms of this license. See the LICENSE file for the full text.

Acknowledgments

Built with these open-source projects:

node-sql-parser — parses SQL DDL into a structured AST
Model Context Protocol SDK — powers the standalone MCP server
esbuild — bundles the extension, tests, and MCP server
VS Code Extension API — the Chat Participant API that gives Schemer a home in Copilot Chat

Authors

SQL File Explainer is designed and built by two co-authors:

Aflin Rinosha S (@aflinrinosha2004) - author
Anand Sundaramoorthy SA - co-author

Contact Us

If you have any questions, feedback, or suggestions, feel free to reach out to the authors:

Aflin Rinosha S: aflinrinosha2004@gmail.com
Anand Sundaramoorthy SA: sanand03072005@gmail.com

GitHub · Issues

_{Made by Aflin Rinosha S and Anand Sundaramoorthy SA · MIT License}

SQL File Explainer

Anand Sundaramoorthy

SQL File Explainer

Table of Contents

About

Why This Extension

Meet Schemer

Features

Core Engine (Local RAG Pipeline)

Chat, Commands & Settings

Beyond the MVP

Tested, Not Just Written

Installation

From a .vsix file

From source (Extension Development Host)

Usage

Commands

Settings

How It Works

MCP Server

Build From Source

Contributing

Roadmap

License

Acknowledgments

Authors

Contact Us

From a `.vsix` file