yoursqlfriend 3.14.0

SQLite forensic analysis with local LLMs — ask questions in plain English

yourSQLfriend

Connect SQLite databases to a local LLM. Ask questions in plain English, get SQL queries and results.

Built for offline forensic analysis on a single workstation — no cloud, no telemetry, nothing leaves your machine.

---

yourSQLfriend is for analysts, investigators, and developers who need to interrogate SQLite databases without sending data anywhere. Load a .db, .sqlite, .csv, or .sql file, ask questions in plain English, and get parameterised read-only SQL with full results — air-gap safe, forensic-grade.

---

✨ Features

🔒 100% Offline	Runs on a local LLM via Ollama or LM Studio. Zero telemetry, air-gap safe
💬 Natural Language	Ask "show me the top 5 customers" and get results + the exact SQL query
🔍 Search All Tables	Find a value across your entire database (⌘K / Ctrl+K)
🪟 Three-Pane Workbench	Schema browser · conversation · Row Inspector
🔎 Row Inspector	Click any result row to expand it; foreign keys become clickable links
🕘 Query History	Per-session panel of every question asked; click to jump back to that turn
📋 Interactive Tables	Sort, filter, paginate results with dark/light theme
💾 Export Sessions	Save your entire chat session as a formatted HTML file with hashes + timestamps
🖥️ Install as App	PWA support — install as a standalone desktop app from Chrome/Edge/Brave

yourSQLfriend is a desktop-first workbench: on narrow screens (below ~880px) the schema browser and Row Inspector are hidden by design.

Ask a question in plain English — the LLM writes parameterised read-only SQL, runs it, and returns results you can sort, filter, and export.

Schema browser & query history

Browse all tables, columns, types, and row counts in the left pane. Query history lives at the bottom — click any entry to jump back.

Row Inspector

Click any result row to expand it. Foreign key references become navigable links — follow relationships without writing another query.

---

🤖 LLM Setup

yourSQLfriend requires a local LLM running before you launch. Set one up first:

Option A: Ollama

ollama pull gemma4:26b
ollama serve

Option B: LM Studio

1. Download LM Studio
2. Load a model
3. Start local server on port 1234

Once connected, the provider indicator in the top bar turns green.

Context window: The system prompt is token-heavy by design. A 16K context window is the minimum; 32K or more is strongly recommended for complex schemas.

LLM model sizes: Smallest → 4B | Mid → 8-9B | Large → 14B | Largest → 26-30B

Recommended LLM families: Qwen | Gemma | Mistral / Devstral

Choosing a model

General chat models (the families above) are the flexible default — they explain schemas well and hold a conversation. If your sessions are SQL-heavy and you're seeing too many failed queries, try a SQL-specialized model: Arctic-Text2SQL-R1-7B (GGUF) outperforms GPT-4o on text-to-SQL benchmarks despite being a 7B model, and loads in LM Studio like any other GGUF. Trade-off: it's a Qwen2.5-Coder fine-tune, so its prose explanations are terser than a general chat model's. A/B both against your own database and keep whichever fails less.

---

🚀 Quick Start

Prerequisite: Python 3.10+ must be installed, and your LLM must be running (see above).

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/reisset/yourSQLfriend/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/reisset/yourSQLfriend/main/install.ps1 | iex

Then launch from any terminal: yoursqlfriend

Options: yoursqlfriend --port 8080, --no-browser, --host 0.0.0.0

Note: The Flask server must be running for the app to work. yoursqlfriend starts it automatically — do not close the terminal.

Updating

Re-run the install one-liner above — it upgrades an existing installation in place. Or, equivalently:

pipx upgrade yoursqlfriend

Install with pipx (manual)

pipx install yoursqlfriend

From source (developers)

git clone https://github.com/reisset/yourSQLfriend.git
cd yourSQLfriend
./run.sh          # Linux/macOS
run.bat           # Windows

---

🛡️ Forensic Integrity

Read-only guaranteed	SQL validation + SQLite mode=ro block all writes
Chain of custody	SHA256 hashes logged, timestamped exports
Audit logs	All queries logged to logs/ with daily rotation
Air-gap safe	Zero telemetry, works fully offline

WAL files: The upload process excludes .db-wal and .db-shm files. Checkpoint your database first to ensure recent transactions are included.

---

⚠️ Known Limitations

• Model quality matters. Smaller models will produce incorrect or incomplete SQL on complex schemas. If results look wrong, the query is the first thing to check.
• SQLite only. No support for Postgres, MySQL, or other engines.
• Single database per session. You can replace the loaded database mid-session, but results from different databases are not cross-queryable.
• Complex queries may fail. Heavily nested subqueries, window functions, and non-standard SQLite extensions may exceed what the LLM generates reliably.

---

📂 Data Storage

All data lives in your home directory:

Platform	Path
Linux / macOS	~/.yourSQLfriend/
Windows	%APPDATA%\.yourSQLfriend\

Contains uploads/, logs/, and sessions/.

---

Apache 2.0 — see LICENSE and NOTICE

Built by Reisset