> ## 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. *** ## 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) or use BYOK (Bring Your Own Key) mode. **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 AI model access. *** ## 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. 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 manually by prefixing your message: ``` use gpt-4: Analyze my database schema and suggest optimizations ``` ``` use qwen: Write a query to find duplicate orders ``` Available models include GPT-5-mini (fast, cost-effective), GPT-4 (complex reasoning), Claude Haiku and Sonnet, Qwen (SQL specialist), and DeepSeek-R1 (research). Availability depends on your license tier and API keys. ### 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. ``` use deepseek-r1: 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. *** ## 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. 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-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. *** ## 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. **Can I use DBFlow offline?** The app can run offline for up to 30 days using cached license validation, but AI queries require an internet connection. **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).