SQLMind — Natural Language to SQL for Java Applications

A Spring Boot library that lets any Java application answer business questions in plain English — no SQL knowledge required.

Demo

Demo GIF coming soon — see the interactive demo → or Setup to run locally.

Live Demo

Try the interactive demo →

Pre-recorded examples — no server, no API key, no setup. Click a question and see how DataAssist responds with charts, explanations, and structured data.

What This Does

SQLMind sits between a business user and a relational database. You ask a question in plain English (or Greek), it generates the SQL, runs it, and returns the answer with a human-readable explanation. It ships with a full browser UI (DataAssist) for non-technical users, a REST API, an MCP server, and Docker support.

Built as a Spring Boot auto-configuration library — drop one dependency into any Spring Boot project and your database becomes queryable in plain language.

How It Works

1. Schema analysis — on startup, Claude reads your database schema and builds a semantic understanding of the data model (cached to disk for 24h)
2. NL → SQL — user question arrives; Claude generates a safe, read-only SQL query against your schema
3. Security gate — a rule-based validator blocks any non-SELECT query before it touches the database
4. Execution — query runs via JDBC with a 10,000-row cap and 30-second timeout
5. Explanation — Claude produces a plain-English summary of the results
6. Chart advice — Claude decides whether a bar, line, or pie chart best represents the result
7. Anomaly monitoring — background scheduler periodically snapshots the database and alerts if anything looks unusual

Tech Stack

Component	Role
Java 21 + Spring Boot 3.x	Library core, auto-configuration, scheduling
Claude API (claude-sonnet-4-6)	NL→SQL generation, explanation, chart advice, insights, anomaly detection
OkHttp4	HTTP client for Claude API calls
Spring JDBC / JdbcTemplate	Query execution with safety limits
H2 (demo)	Embedded database for the banking demo
Chart.js 4	Browser-side chart rendering
jsPDF + AutoTable	PDF export from the browser
Python MCP Server	Exposes SQLMind as an MCP tool for Claude Code
Docker / Docker Compose	One-command deployment

Setup

As a Library (Spring Boot project)

Add to pom.xml:

<dependency>
    <groupId>io.sqlmind</groupId>
    <artifactId>sqlmind-core</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Set your API key:

sqlmind.claude.api-key=${CLAUDE_API_KEY}

Inject and use:

@Autowired SQLMindService sqlMind;

QueryResult result = sqlMind.query("Which customers have the highest loan balances?");
System.out.println(result.explanation()); // plain-English answer
System.out.println(result.rows());        // List<Map<String, Object>>

Auto-configuration wires everything if a DataSource bean is present.

Run the Banking Demo (browser UI)

Requirements: Java 21, Maven, CLAUDE_API_KEY environment variable

export CLAUDE_API_KEY=sk-ant-...
mvn exec:exec@bank-server

Then open your browser at port 8080.

Docker

docker compose up --build

Pass your API key:

CLAUDE_API_KEY=sk-ant-... docker compose up

MCP Server (Claude Code integration)

pip install mcp httpx

Add to .claude/settings.json:

"sqlmind": {
  "command": "python",
  "args": ["mcp/server.py"],
  "env": {
    "SQLMIND_BASE_URL": "http://localhost:8080"
  }
}

The MCP server exposes three tools: query_database, describe_database, get_insights.

Example

Input: "Which branches have the highest total loan amounts?"

Generated SQL:

SELECT b.BranchName, SUM(l.LoanAmount) AS TotalLoans
FROM Loans l JOIN Branch b ON l.BranchID = b.BranchID
GROUP BY b.BranchName ORDER BY TotalLoans DESC

Explanation: "The Athens branch leads with €580,000 in total loans across 12 accounts, followed by Thessaloniki at €340,000. Three branches have no active loans."

Chart: Bar chart rendered automatically in the browser.

DataAssist — Browser UI for Non-Technical Users

The included web interface (/static/index.html) is designed for bank employees with no SQL experience:

• Today's Snapshot — AI-generated insights load on page open (no question needed)
• Help panel — categorized example questions with one-click execution
• Explanation card — prominent plain-English summary above the data table
• Auto-charts — bar, line, or pie chart selected automatically based on the result
• Conversational follow-up — "now show only Athens" works after any query
• Query refiner — when 0 results, suggests an alternative question to try
• Pinned dashboard — pin up to 6 queries; key metrics reload on every page open
• PDF export — full report with chart, explanation, and table for sharing
• Mobile-responsive — works on tablets and phones

Use Cases

• Bank operations teams — branch managers query loan portfolios, account balances, and customer segments without writing SQL
• Internal analytics tools — add NL query capability to any existing Spring Boot + database application in minutes
• Anomaly detection — automated monitoring alerts on unusual patterns (sudden balance drops, volume spikes) without building a dedicated pipeline

Environment Variables

Variable	Description
CLAUDE_API_KEY	Anthropic API key — required
SQLMIND_BASE_URL	MCP server target (default: http://localhost:8080)
JAVA_OPTS	JVM flags (default: -Xmx256m in Docker)

---

Built by Theo — AI automation consultant based in Greece.