easy-sql-agent

AI-powered SQL query generation tool. Connect to your database, select an AI agent, describe what you want in natural language — the agent generates, validates, and explains SQL for you.

Tech Stack

Layer	Stack
Frontend	Vue 3 + TypeScript + Vite + Pinia + Monaco Editor
Backend	Koa2 + TypeScript + Node.js
AI	OpenAI GPT models
Database	MySQL, PostgreSQL, SQLite

Features

• Natural language to SQL — describe your intent, get executable SQL
• Multi-database support — MySQL, PostgreSQL, SQLite connections
• SQL validation — blocks dangerous operations (DROP, TRUNCATE, etc.), warns on risky patterns
• Agent configuration — customize AI behavior per agent
• Schema browser — explore tables and columns from connected databases
• Query history — review past queries and results

Getting Started

Prerequisites

• Node.js 18+
• pnpm 9+
• OpenAI API key

Install & Run

# Install dependencies
pnpm install

# Start both frontend and backend dev servers
pnpm start

Frontend: http://localhost:5173 Backend API: http://localhost:3001

Configuration

Copy .env.example to .env and set your environment variables:

cp .env.example .env

Key variables:

Variable	Default	Description
PORT	3001	Backend server port
NODE_ENV	development	Runtime mode
VITE_API_BASE	http://localhost:3001	Backend API URL for frontend

For backend configuration (OpenAI API key, database credentials), refer to the backend .env setup in backend/.

Project Structure

easy-sql-agent/
├── frontend/          # Vue 3 SPA
│   └── src/
│       ├── api/       # API client
│       ├── views/     # Page components
│       ├── stores/    # Pinia stores
│       └── components/# Shared components
├── backend/           # Koa2 API server
│   └── src/
│       ├── routes/    # API endpoints
│       ├── services/  # Business logic (LLM, SQL validation)
│       ├── store/     # JSON file persistence
│       └── middleware/ # Error handling, CORS
└── package.json      # Workspace root

Available Scripts

Command	Description
pnpm install	Install all workspace dependencies
pnpm start	Start frontend + backend dev servers
pnpm build	Build all packages for production
pnpm lint	Lint all packages

API Endpoints

Method	Path	Description
GET	/api/health	Health check
GET/POST	/api/connections	Database connections
GET/POST/DELETE	/api/connections/:id	Connection CRUD
GET/POST/DELETE	/api/connections/:id/schema	Fetch DB schema
POST	/api/sql/generate	Generate SQL from natural language
POST	/api/sql/validate	Validate SQL
POST	/api/sql/explain	Explain SQL
POST	/api/sql/fix	Fix SQL error
GET/POST	/api/agents	Agent configurations
GET/POST/DELETE	/api/agents/:id	Agent CRUD
GET	/api/history	Query history
POST	/api/history	Save query to history