> ## Documentation Index > Fetch the complete documentation index at: https://docs.dbflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # User Guide > Getting started with dbflow.ai ## Welcome to DBFlow DBFlow is a desktop AI agent that lets you query your databases using natural language. Instead of writing SQL, just ask: ``` Find all customers who haven't placed an order in the last 90 days ``` 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](#local-models-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](https://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](https://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](#local-models-ollama). *** ## 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](/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](/API_KEYS_SETUP) for the full list of supported providers and configuration details. ### 3. Run Your First Query Open the chat and try: ``` List all tables in the database ``` ``` Show me the schema for the customers table ``` ``` Get the top 10 records from the orders table ``` 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: | Tier | Models | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Standard** (auto-selected) | GPT-5.4 Mini (fast, cost-effective, free tier), Qwen (SQL specialist), Claude Sonnet 5, Claude Haiku 4.5, Gemini 3.7 Flash, DeepSeek-R1 (research) | | **Top tier** (manual select) | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, GPT-5.4, GPT-5.5, Qwen 3.5, Gemini 3.1 Pro | | **Local** (via Ollama) | Any installed Ollama model — see [Local Models](#local-models-ollama) | 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: ``` Create a bar chart showing monthly sales ``` ``` Make a pie chart of customer distribution by country ``` 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: ``` What are the best practices for database connection pooling? ``` Requires a Tavily or Serper API key (see [API Keys Setup](/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 PostgreSQL indexing strategies ``` Research runs at three depth levels: | Depth | Duration | When to use | | ----------------- | -------- | ----------------------------------------- | | **Quick** | 1–2 min | Fast overview, simple questions | | **Standard** | 2–4 min | Balanced depth; default for most research | | **Comprehensive** | 3–6 min | Deep dive with many sources | 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](https://ollama.com) as its local inference engine (llama.cpp under the hood, with GPU/Metal acceleration handled automatically). ### Setup 1. **Install Ollama** from [ollama.com/download](https://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 | Model | Size | Hardware tier | | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Qwen 3.5 — 8B** | \~5 GB | Laptop — 16 GB RAM | | **Qwen 3.5 — 14B** | \~9 GB | Workstation — 24 GB RAM (recommended default) | | **Qwen 3.5 — 35B MoE** | \~20 GB | GPU rig — 32 GB RAM/VRAM | | **Qwen 3.8 — 27B** | \~18 GB | GPU rig — 32 GB RAM/VRAM. Newest Qwen, 256K context; on Apple Silicon use the `qwen3.8:27b-mlx` tag | | **Muse Glimmer — 30B** (Meta) | \~19 GB | Discrete NVIDIA GPU (24 GB+ VRAM) — agent-tuned, 131K context. Dense model: slow on Apple Silicon, prefer Qwen 35B MoE there | | **Llama 4 Scout — 109B** | \~65 GB | Power user — 64 GB+ RAM | 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](#local-models-ollama) 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](/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](#local-models-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](https://dbflow.ai#download). *** ## Next Steps * [Adding Databases](/ADDING_DATABASES) — Detailed connection instructions for each database type * [API Keys Setup](/API_KEYS_SETUP) — Full guide to configuring bundled and BYOK keys **Need help?** Email [support@dbflow.ai](mailto:support@dbflow.ai) or visit [dbflow.ai](https://dbflow.ai).