QueryWeaver: Turn Natural-Language Questions into SQL

Overview

QueryWeaver is a Text2SQL application and Python SDK. It represents database schemas as graphs, giving an AI model structured context about tables and relationships when translating natural-language questions into SQL. It can return query results as well as SQL.

The project is aimed at developers and teams who want to add natural-language database querying to an application or offer it directly through a web interface. Its REST API, MCP support, and SDK provide several ways to integrate it, while FalkorDB stores schema graphs and conversation memory.

Key Features

• Converts questions in plain English into SQL and can execute queries against the connected database.
• Builds graph-based schema context from PostgreSQL and MySQL databases.
• Provides a web application and REST API, including streaming chat responses.
• Includes an MCP-compatible HTTP surface with operations for listing databases, connecting, retrieving schema, and querying.
• Offers a Python SDK for using Text2SQL without running the web server.
• Supports multiple LLM providers, including OpenAI, Gemini, Anthropic, Cohere, Azure OpenAI, and Ollama.
• Requires confirmation before executing destructive SQL operations.
• Supports multi-turn queries, custom instructions, and optional conversation-memory expiration.

Use Cases

• Analytics teams can ask questions about connected PostgreSQL or MySQL data without writing every query by hand.
• Application developers can add natural-language query capabilities through the SDK or REST API.
• MCP clients can use QueryWeaver’s database and query operations through its MCP HTTP interface.
• Teams exploring Text2SQL can evaluate a graph-based schema approach using the Docker image and their own database and LLM credentials.

Getting Started

For a quick Docker evaluation, run:

docker run -p 5000:5000 -it falkordb/queryweaver

Then open http://localhost:5000. For required configuration, database setup, and development instructions, see the repository README.

Considerations

• QueryWeaver requires a FalkorDB instance and an LLM provider configuration. Running it against real data also requires a PostgreSQL or MySQL database.
• The documented requirements include Python 3.12+ for the SDK and development setup.
• The project is licensed under AGPL-3.0, which may affect use in proprietary or networked deployments.
• Destructive SQL requires a confirmation flow. Integrations that automate queries should handle confirmation rather than treating generated SQL as automatically safe to execute.