# PiperQL

> Open-source AI agent that lets you talk to PostgreSQL databases in plain English.

- URL: https://piperql.vercel.app
- GitHub: https://github.com/ajaysharmadeveloper/piperql
- License: AGPL-3.0
- Full docs: https://piperql.vercel.app/llms-full.txt

## What is PiperQL?

PiperQL is a self-hosted, open-source AI database agent. Connect it to your PostgreSQL databases, ask questions in plain English, and get direct answers — no SQL knowledge required. It generates tables, charts, and insights automatically. Your data never leaves your servers.

## Key Features

- **Natural Language Queries**: Ask "How many users signed up this week?" and get instant answers
- **Auto-Generated Charts**: 10+ chart types — bar, line, pie, area, scatter, radar, donut, stacked bar, radial bar, composed
- **Three Access Modes**: Read Only (SELECT only), CRUD (write needs confirmation), Full Access (DDL needs type-to-confirm)
- **AI Memory**: Powered by Mem0, remembers context across conversations
- **Web Search**: Built-in Tavily integration for SQL syntax help
- **Multi-User**: JWT authentication, admin panel, user management
- **Self-Hosted**: Your data stays on your infrastructure
- **Real-time Streaming**: SSE-based token streaming for instant responses
- **Safe Write Operations**: All write/DDL queries require explicit user confirmation

## Tech Stack

- Backend: FastAPI + LangGraph + OpenAI (Python)
- Frontend: Next.js 16 + React 19 + Tailwind CSS 4
- Database: PostgreSQL (app DB + target DBs)
- AI Memory: Mem0
- Charts: Recharts (10+ types)
- License: AGPL-3.0

## Getting Started

1. Clone: `git clone https://github.com/ajaysharmadeveloper/piperql.git`
2. Install: `cd piperql && make install`
3. Configure: `cp backend/.env.example backend/.env` (add APP_DATABASE_URL, JWT_SECRET)
4. Setup DB: `createdb ai_agent_db && make migrate && make create-admin`
5. Run: `make run` (Backend on localhost:8000, Frontend on localhost:3000)
6. Docker: `docker compose up -d`

## API Endpoints

- POST /api/chat/stream — SSE streaming chat with database
- POST /api/chat/confirm — Confirm write operations
- GET /api/databases/ — List available databases
- POST /api/auth/login — Authentication
- GET /api/settings/ — Configuration management
- GET /health — Server health check

## Contact

Built by Ajay Kumar Sharma
- Website: https://www.ajaykumarsharma.co.in/
- GitHub: https://github.com/ajaysharmadeveloper
- LinkedIn: https://www.linkedin.com/in/ajaykumarsharma1996/
- Twitter/X: https://x.com/ajaykumar143136