Skip to content
Get packs

Vanna

Ask questions of your SQL database in plain English and get SQL, tables, and charts back.

GitHub Download v2.0.2
Stars
23.8k
Forks
2.5k
Licence
MIT
Language
Python
Last update
9 months ago
Type
Library

This repository is archived and no longer maintained.

What it is

Vanna is a Python library that lets people ask questions in natural language and receive answers from a SQL database. It uses a large language model to write SQL, runs it against your database, and returns a table, a Plotly chart, and a written summary. Version 2.0 adds user-aware permissions, so results can be filtered based on who is asking.

  • Add a chat box to an existing web app where users ask for sales figures and receive a table and chart
  • Restrict query results so each user only sees rows their group permissions allow
  • Register a custom tool, such as sending an email, that the agent can call
  • Connect an LLM such as Anthropic's model to a SQLite database for a quick local demo

Great for

  • Developers adding a natural-language data question box to an internal app
  • Teams that want a pre-built chat web component connected to their own database
  • Applications that need per-user row-level filtering of query results
  • Projects using FastAPI or Flask that want to add a chat endpoint

Not ideal for

  • People who want a finished end-user product without writing any code, since setup requires Python and wiring up an LLM and database
  • Teams needing a project that is still actively maintained, since the repository is archived and the last push was 2026-02-02
  • Users who cannot send database schema or data to a third-party LLM provider, since the README lists hosted LLMs such as OpenAI and Anthropic

How to get it

  1. 1

    Install with a package manager

    You'll need: Python 3.8 or newer · An LLM API key or local model such as Ollama

    Clone the repository

    git clone https://github.com/vanna-ai/vanna
  2. 2

    Run it

    • Install Python dependencies for the project, following the Quickstart in the docs at https://vanna.ai/docs/quick-start
    • Create an Agent with an LLM service, a tool registry, and a user resolver as shown in the README example
    • Register the chat routes on a FastAPI app with register_chat_routes
    • Start the server and open the page that embeds the <vanna-chat> component pointed at /api/vanna/v2/chat_sse
  3. 3

    Get the most out of it

    • Write a UserResolver that reads identity from your existing cookies or JWTs so permissions apply automatically
    • Use lifecycle hooks for quota checking, logging, or content filtering, as described in the README
    • Extend the Tool base class to give the agent access to your own business logic
    • Add context enrichers to supply documentation or RAG content to the agent

Downloads

Source code (.zip)main branch · straight from GitHubRelease v2.0.2Release notes and sourceOfficial website & docsvanna.ai/docs/

Strengths

  • Supports many LLM providers and databases listed in the README, including PostgreSQL, Snowflake, and SQLite
  • Includes a pre-built web component and streaming responses for tables and charts
  • Released under the MIT license, which permits commercial use

Trade-offs

  • The repository is marked archived, so it may receive no further updates or fixes
  • The README is truncated and documents the 2.0 API mainly through examples; 0.x users must follow a separate migration guide
  • Using it well requires an LLM account or local model and a working database connection

How it compares

ProjectStarsTypeLevelUpdatedBest for
vanna (this)23.8kLibraryintermediate9 months agoDevelopers adding a natural-language data question box to an internal app
duckdb42.7kLibrarybeginner4 days agoAnalysts who want to run SQL directly on CSV, Parquet, or JSON files
turso25.1kLibraryintermediate4 days agoDevelopers who want an embedded SQLite-compatible database in a Rust, JavaScript, Python, Java, Go, or .NET project
DB-GPT20.2kAppintermediate4 days agoAnalysts who want to ask questions of CSV or Excel files in plain language
kysely14.3kLibraryintermediate4 days agoTypeScript developers who want SQL control without losing compile-time type checks
Prompt-Engineering-Guide79.8kLearning resourcebeginner8 months agoPeople who are new to prompting and want structured lessons with examples

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.