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: 
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
    • 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 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.

​
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: 
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

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).

​
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:
DepthDurationWhen to use
Quick1–2 minFast overview, simple questions
Standard2–4 minBalanced depth; default for most research
Comprehensive3–6 minDeep 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 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.

​
Next Steps

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