dbclaw documentation

Ask your databases questions in plain English — locally, privately, read-only.

Install

Download the latest build from the releases page (Windows x64):

File	Use it if…
`dbclaw_<version>_x64-setup.exe`	Recommended. Per-user install, no admin, auto-updates.
`dbclaw_<version>_x64_en-US.msi`	Enterprise / Group Policy deployment.
`dbclaw-desktop.exe`	Run without installing (large standalone file).

⚠️ Builds are unsigned, so Windows SmartScreen shows "Windows protected your PC". Click More info → Run anyway. Removing this needs a paid code-signing certificate.

Quick start

Launch dbclaw.
Add a database — use the connection switcher (top-left) → Add connection. Pick the type, fill in the details, click Test, then Save.
Add an AI model — open Settings and paste a cloud provider's API key, or point dbclaw at a local Ollama model.
Ask — open the Chat tab, pick your database, and type a question like "How many users signed up last month?"

Connecting databases

Database	How to connect
PostgreSQL	Host, port, database, user, password. SSL modes supported.
MySQL / MariaDB	Host, port, database, user, password.
SQL Server	SQL auth, Windows Integrated auth, or Azure AD.
SQLite	Pick the `.db` / `.sqlite` file.
MongoDB	Host, user, password. Atlas: use the SRV host (`cluster.xxxx.mongodb.net`), leave Port blank, and allowlist your IP in Atlas → Network Access.
CSV / JSON / Excel	Pick the file.

🔒 Every query is read-only. dbclaw blocks INSERT/UPDATE/DELETE/DROP before anything reaches your database.

AI models (LLMs)

dbclaw uses a large language model to translate English into SQL. Choose one in Settings → LLM provider.

Cloud providers (need an API key)

Provider	Default model	Get a key
Anthropic (Claude)	`claude-haiku-4-5`	console.anthropic.com
OpenAI	`gpt-4o-mini`	platform.openai.com
DeepSeek	`deepseek-chat`	platform.deepseek.com
Google Gemini	`gemini-2.0-flash`	aistudio.google.com

Settings → Active provider → pick it → under Cloud provider keys click Add and paste your key. Keys are stored in your OS keychain, never in plain files. Leave the Model box blank to use the default.

Local models with Ollama (no key, fully offline)

Install Ollama and pull a model: ollama pull llama3.1:8b
Settings → Active provider → Ollama (local), set the model, keep base URL http://localhost:11434.
Make sure ollama serve is running.

dbclaw needs a tool-capable model. Known good: llama3.1:8b, qwen2.5-coder:7b, mistral-nemo, command-r. Local models slow down on long chats — use the Stop button or start a new chat.

Features

Tab	What it does
Chat	ChatGPT-style conversation over one or several databases. Remembers context, auto-fixes failed SQL, exports to Excel, and can be stopped mid-request.
Ask	One-shot question → SQL → result against a single database.
Query	Write and run your own SQL (read-only).
Compare	Ask one question across multiple databases at once and compare answers.
Diff	Compare schemas and data between two databases.
Federate	Join across different databases in one query (e.g. PostgreSQL + MongoDB + Excel).
Model	Semantic layer — friendly names, business metrics and a glossary so the AI speaks your terms.
Audit	Local log of everything dbclaw did.
Settings	Providers, API keys, preferences, and updates.

Auto-update

From v0.1.1 on, dbclaw checks for new versions on startup and shows an "Update & restart" banner when one is available. You can also check manually under Settings → About → Check for updates. Updates are cryptographically signed and verified before installing.

Privacy & safety

Local-first: your data and credentials stay on your machine.
Keychain: API keys and DB passwords live in your OS keychain, not plain files.
Minimal egress: only your question + schema go to the chosen AI provider — and with Ollama, nothing leaves your computer.
Read-only: dbclaw refuses to run anything that writes to your database.

Troubleshooting

"Windows protected your PC" (SmartScreen)

The build is unsigned. Click More info → Run anyway.

MongoDB Atlas won't connect

Use the SRV host (cluster.xxxx.mongodb.net), leave Port blank, use your database-user password, and allowlist your IP in Atlas → Network Access.

Local model errors or hangs

Make sure ollama serve is running and you pulled a tool-capable model. If a reply drags, hit Stop and start a new chat — long conversations are heavy for small local models.

About

dbclaw is built by Robert Ishimwe.

Website — www.ishimwe.rw
GitHub — @Robertishimwe
More of my work — Melonelab Academy