yoursqlfriend 3.9.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 analysis on a single workstation.

---

✨ 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 — the forensic atelier layout
🔎 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

The Flask server must be running for the app to work. Use ./run.sh to start it.

---

🚀 Quick Start

Prerequisite: Python 3.10+ must be installed.

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

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

---

🤖 LLM Setup

yourSQLfriend requires a local LLM. Set one up before you start:

Option A: Ollama (Recommended)

ollama pull llama3.2
ollama serve

Option B: LM Studio

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

Fair Warning: The system prompt required to get better SQL query results is token-heavy. For optimal usage, a ~16 000 tokens context window is MINIMUM, and ~32 000 or more is highly recommended.

Recommended models: Smallest => Qwen3:4B | Mid-Size => Qwen3:8B | Large => Ministral-3:14B OR Qwen3:14B | Largest => Qwen3-coder:30B

---

🛡️ 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

Note: The upload process excludes WAL files (.db-wal, .db-shm). Checkpoint your database first to include recent transactions.

---

📂 Data Storage

All data lives in your home directory:

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

Contains uploads/, logs/, and sessions/.

---

🧰 Tech Stack

Flask, Vanilla JS, CSS, HTML, SQLite, PWA, local LLM (OpenAI-compatible API)

---

Apache 2.0 — see LICENSE and NOTICE

Built by Reisset