SQLHubby

A terminal-based AI agent that lets you talk to your database in plain English.
No SQL knowledge needed, just ask questions and get answers.

Connect it to your MySQL, PostgreSQL, or SQLite database, pick a database at runtime, and start querying with natural language. Powered by any LLM via OpenRouter, Anthropic, OpenAI, or Ollama.

---

Setup

1. Clone and install dependencies

git clone https://github.com/Natique1415/SQLHubby.git
cd SQLHubby
pip install -r requirements.txt

2. Create your config

cp config.example.json config.json

Edit config.json, add your API keys and database credentials, remove the entries you don't need.

3. Run

python main.py

If you only have one AI provider and one database configured, DBChat auto-selects both and launches immediately. No flags needed.

---

CLI Flags

python main.py                          # auto-select AI + DB if only one of each
python main.py --ai claude              # pick a specific AI provider
python main.py --db my_postgres         # pick a specific database
python main.py --ai openai --db my_pg   # pick both explicitly
python main.py --list                   # list all configured databases
python main.py --list-ai                # list all configured AI providers
python main.py --allow-writes           # enable INSERT/UPDATE/DELETE (default: read-only)

---

config.json structure

Both AI providers and databases are named profiles — add as many as you want and select at runtime.

{
  "ai_providers": {
    "openrouter_free": {
      "provider": "openrouter",
      "model": "deepseek/deepseek-chat-v3-0324:free",
      "api_key": "your_openrouter_key"
    },
    "claude": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "api_key": "your_anthropic_key"
    }
  },
  "databases": {
    "my_mysql": {
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "your_password"
    },
    "my_postgres": {
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "user": "postgres",
      "password": "your_password"
    }
  },
  "agent": {
    "max_iterations": 10,
    "read_only": true,
    "confirm_writes": true,
    "max_rows": 200
  },
  "display": {
    "max_rows_shown": 50,
    "show_sql": true,
    "show_timing": true
  }
}

Note: name is optional in database profiles. If omitted, the agent will list available databases on the server and let you pick one at runtime.

---

How database selection works

DBChat connects to the database server on startup without selecting a specific database. Just ask naturally:

"What databases are available?"
"Use the shop database"
"How many orders came in this week?"

You can switch databases mid-conversation too:

"Actually, show me the analytics database instead"

---

Supported Databases

Database	type value	Required fields
MySQL	mysql	host, port, user, password
PostgreSQL	postgresql	host, port, user, password
SQLite	sqlite	path

Supported AI Providers

Provider	provider value	Example model
OpenRouter	openrouter	deepseek/deepseek-chat-v3-0324:free
Anthropic	anthropic	claude-sonnet-4-20250514
OpenAI	openai	gpt-4o-mini
Gemini	gemini	gemini-2.0-flash
Ollama	ollama	llama3

For free OpenRouter models, browse: openrouter.ai/models?q=free

---

Project Structure

SQLHubby/
├── main.py               # Entry point + CLI args
├── config.json           # Your config (git-ignored)
├── config.example.json   # Template to copy from
├── requirements.txt
├── README.md
├── core/
│   ├── config.py         # Loads config.json
│   ├── database.py       # DB connection, queries, schema inspection
│   └── agent.py          # AI agent loop, tools, prompts
└── tui/
    └── app.py            # Terminal UI

Keyboard Shortcuts

Key	Action
Enter	Send message
Ctrl+L	Clear chat
Ctrl+U	Clear Input Field
Ctrl+R	Reset session
Ctrl+C	Quit