Skip to main content

​
Welcome to DBFlow

DBFlow is a desktop AI agent that lets you query your databases using natural language. Instead of writing SQL, just ask:
DBFlow figures out the SQL, runs it, and returns formatted results — along with the generated query so you can see exactly what happened. It supports PostgreSQL, MySQL, SQLite, and MongoDB, runs entirely on your machine, and stores credentials in your OS keychain. Your data never passes through DBFlow’s servers — and with local models via Ollama, you can run inference on your own hardware so nothing leaves your machine at all.

​
Installation

  1. Download the installer for your OS from dbflow.ai/download
    • macOS: .dmg — drag to Applications
    • Windows: .exe — run the setup wizard
    • Linux: .AppImage (make executable with chmod +x) or .deb package
  2. Launch DBFlow and activate your license when prompted. If you don’t have one yet, you can purchase one at dbflow.ai/pricing — subscriptions with bundled AI credits, BYOK (Bring Your Own Key) subscriptions, or a one-time BYOK Pro Lifetime license.
System requirements: macOS 10.15+, Windows 10+, or Ubuntu 18.04+. 4 GB RAM minimum (8 GB recommended), 500 MB disk space, and an internet connection for cloud AI models. Local models via Ollama need more RAM — see Local Models.

​
Quick Setup

There are three things to do before your first query: add a database, make sure you have API keys, and go.

​
1. Add a Database

Go to Databases in the sidebar, click Add Connection, fill in your connection details, and click Add Connection. DBFlow tests the connection automatically. You can also paste a full connection URI (Neon, Supabase, MongoDB Atlas, etc.) straight into the Host field. No database handy? Click “…or try the demo database” in the Databases view — a bundled retail dataset you can query and chart immediately. For detailed setup instructions for each database type, see Adding Databases.

​
2. API Keys

If you have a license with bundled keys: You’re all set — keys are available automatically once your license is activated. If you’re using BYOK: Go to Settings → API Keys, select a provider (e.g., OpenAI), paste your key, and save. BYOK keys always take priority over bundled keys. See API Keys Setup for the full list of supported providers and configuration details.

​
3. Run Your First Query

Open the chat and try:
DBFlow will analyze your question, generate SQL, execute it, and return formatted results. The generated SQL is shown below the results so you can review or learn from it.

​
Querying

​
Tips for Good Queries

Be specific — “Show me sales by month for 2024” works better than “sales.” You can reference tables and columns by name, ask follow-up questions (DBFlow keeps conversational context), and ask about your schema when you’re not sure what’s available.

​
Model Selection

DBFlow automatically picks the best AI model for each query. You can also choose any model manually from the model picker in the chat input. Available models depend on your license tier and API keys: Top-tier models are never auto-selected — pick them explicitly for your hardest analysis. If you ask DBFlow to “help me write a query”, it returns the SQL for review instead of executing it; say “run it” when you’re ready.

​
Visualizations

Ask DBFlow to chart your data:
Charts appear inline in your results and can be copied or saved. Make sure your query returns data suitable for visualization — categories and values for bar charts, labels and proportions for pie charts.

​
Web Search & Deep Research

​
Web Search

DBFlow can search the web for database best practices and solutions. Just ask naturally:
Requires a Tavily or Serper API key (see API Keys Setup).

​
Deep Research

Deep research runs multi-step, web-backed analysis and returns structured reports with citations. It’s useful for topics like indexing strategies, migration planning, sharding approaches, or comparing database technologies. Select DeepSeek-R1 in the model picker, then ask:
Research runs at three depth levels: Deep research uses DeepSeek-R1 by default (free via HuggingFace). O4-mini-deep-research is available for more demanding analysis but runs longer (7–20 min) and may incur additional cost.

​
Local Models (Ollama)

Run AI inference entirely on your own hardware — no query, schema, or row data ever leaves your machine. Ideal for healthcare, legal, finance, or any environment with strict data-egress requirements. Available on Pro, Team, Enterprise, and all BYOK plans. DBFlow uses Ollama as its local inference engine (llama.cpp under the hood, with GPU/Metal acceleration handled automatically).

​
Setup

  1. Install Ollama from ollama.com/download (macOS, Windows, Linux) and make sure it’s running — the desktop app runs it automatically, or start it with ollama serve.
  2. In DBFlow, go to Settings → Local Inference and switch the master toggle on. DBFlow detects your Ollama installation and shows its status and version.
  3. Install a model. Pick from the curated catalog — each entry is validated for DBFlow’s SQL/code workload and labeled with the hardware it needs — and click install. Download progress streams right in the panel.

​
Recommended models

The catalog is a starting point, not a limit — any Ollama model you install (via the custom-install field or ollama pull in your terminal) appears in the model picker under Local Models.

​
Remote Ollama

If your workstation is modest but you have a beefier machine on your network, point DBFlow at it: in Settings → Local Inference, switch mode to Remote and enter the server’s URL (e.g. http://192.168.1.50:11434). Data stays inside your network.

​
Notes

  • Local models are slower than cloud models and response time depends on your hardware; DBFlow adjusts its timeouts accordingly and warms the model up when you select it.
  • Models under ~7B parameters can struggle with DBFlow’s structured query generation — the app will warn you if an installed model is below the reliable threshold.
  • Local inference works offline — pair it with a SQLite or local database and DBFlow runs fully air-gapped (license validation still needs to reach the internet every 30 days).

​
Security

DBFlow offers three security tiers. You can configure these in Settings → Security. Standard (default) — SQL injection protection, secure credential storage in your OS keychain, encrypted local storage, and XSS protection via Content Security Policy. Business — Everything in Standard, plus audit logging (all queries logged to a local SQLite database), local API authentication via session tokens, and an optional audit webhook for SIEM integration (Datadog, Splunk, etc.). Healthcare — Everything in Business, plus automatic PHI masking. Sensitive data (SSN, phone, email, DOB, MRN) is detected and masked before being sent to AI providers. Superuser access is available for authorized viewing of unmasked data. For the strongest posture, pair the Healthcare tier with local models so data never reaches a cloud provider at all. Changing security tiers triggers an automatic backend restart. The Healthcare tier is not a complete HIPAA compliance solution — ensure you have appropriate BAAs with any cloud services.

​
Other Features

Query History — All queries are saved automatically. Click History in the sidebar to search, filter, and rerun past queries. Multiple Connections — Add as many databases as you need and switch between them by clicking on a connection in the Databases view, or by asking in chat: “Switch to production_db.” Only one connection is active at a time. You can also switch and query in one message: “Switch to production_db and show me all tables.” Cost Tracking — Monitor your API usage and costs in Settings.

​
Troubleshooting

Can’t connect to a database — Verify your credentials, check that the database server is running, and make sure firewall rules allow connections. Try connecting with a standalone client (psql, mysql, mongosh) first to rule out DBFlow-specific issues. See Adding Databases — Troubleshooting for detailed guidance. “Invalid API key” or “API key not found” — Check your keys in Settings → API Keys. Make sure there are no extra spaces or quotes. For bundled keys, verify your license is active. For BYOK, confirm the key works on the provider’s website. Query fails or returns unexpected results — Review the generated SQL shown below the results. Try rephrasing your question, being more specific about table/column names, or selecting a different model for complex queries. “Model not available” — The model may not be included in your license tier, or you may be missing the required API key. Try a different model or check Settings → Models. Slow queries — Use GPT-5.4 Mini for simple queries (it’s faster). For large datasets, check that your database has appropriate indexes. Network latency can also be a factor with remote databases. Local models are hardware-bound — a smaller model or a machine with more RAM/GPU makes the biggest difference. Local model not available / “Could not reach Ollama” — Make sure Ollama is running (ollama serve, or launch the Ollama desktop app) and the master toggle in Settings → Local Inference is on. For remote mode, verify the URL is reachable from your machine. Local models require a Pro or higher license.

​
FAQ

Do I need to know SQL? No. DBFlow translates natural language to SQL automatically. The generated SQL is shown with each result if you want to learn from it. Does DBFlow modify my database? By default, DBFlow only runs SELECT queries and cannot modify, delete, or insert data. Are my credentials secure? Yes. Credentials are stored in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux libsecret) and are never sent to DBFlow’s servers. What’s the difference between bundled keys and BYOK? Bundled keys come with your license and have usage limits. BYOK means you provide your own API keys from providers like OpenAI or Anthropic — unlimited usage, and you pay the provider directly. BYOK Pro is available as a monthly/yearly subscription or a one-time lifetime purchase. Can I use DBFlow offline? The app can run offline for up to 30 days using cached license validation. Cloud AI queries require an internet connection, but local models via Ollama run entirely on your machine — paired with a local database, DBFlow works without any network access. Can I export results? Results can be copied, and charts are saved to files. CSV/Excel export availability depends on your license tier. How do I update? DBFlow checks for updates automatically. You can also check manually via Help → Check for Updates or download the latest version from dbflow.ai/download.

​
Next Steps

Need help? Email support@dbflow.ai or visit dbflow.ai.