How to Query Your Database with Vanna AI

What Vanna AI Does

If your team relies on a developer or analyst to run database queries every time someone needs an answer, Vanna AI removes that bottleneck. It sits between your database and your users, takes a question in plain English, generates the corresponding SQL, executes it, and returns the result as a data table or chart.

The mechanism behind this is retrieval-augmented generation. When you set up Vanna, you give it your database's table definitions and a set of example question-SQL pairs. Vanna stores these in a local vector database. When someone asks a question, Vanna finds the most relevant examples and schema fragments, assembles them into context for the language model, and uses that context to generate a query that fits your actual data structure rather than guessing column names.

Vanna 2.0, released in early 2026, added production-ready features including streaming responses, a built-in web interface, and user-awareness that makes it practical to deploy for a whole team, not just run locally by one analyst.

Step 1: Install Vanna

You need Python 3.9 or later. Open a terminal and run:

pip install vanna

To add OpenAI integration and the built-in Flask web interface:

pip install "vanna[openai]" flask

If you prefer a fully local setup where no data leaves your machine, install Ollama and pull a model before running Vanna:

brew install ollama
ollama pull llama3.2
pip install "vanna[ollama]"

The local Ollama setup is slower and slightly less accurate on complex queries, but it keeps all data on your own hardware, which matters for sensitive business data.

Step 2: Connect to Your Database

Vanna works with PostgreSQL, SQLite, Snowflake, BigQuery, MySQL, DuckDB, and most other major databases. The connection setup differs slightly per database, but the pattern is the same.

For PostgreSQL with OpenAI as the LLM:

from vanna.openai import OpenAI_Chat
from vanna.chromadb import ChromaDB_VectorStore

class MyVanna(ChromaDB_VectorStore, OpenAI_Chat):
    def __init__(self, config=None):
        ChromaDB_VectorStore.__init__(self, config=config)
        OpenAI_Chat.__init__(self, config=config)

vn = MyVanna(config={
    'api_key': 'your_openai_key',
    'model': 'gpt-4o'
})

vn.connect_to_postgres(
    host='localhost',
    dbname='your_database',
    user='your_user',
    password='your_password',
    port=5432
)

For a local SQLite file, replace the connection call with:

vn.connect_to_sqlite('path/to/database.db')

ChromaDB is the default vector store for training data and runs locally without any additional setup. For team deployments where multiple people share the same training data, Vanna supports hosted vector stores including Pinecone.

Step 3: Train Vanna on Your Schema

This is the step that determines whether Vanna produces useful output or unreliable guesses. Without training, a language model has no knowledge of your column names, table relationships, or the logic behind your business data. With training, it does.

Start by feeding Vanna your DDL, which is the table and column definitions from your database. For SQLite:

df_ddl = vn.run_sql("SELECT sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL")
for ddl in df_ddl['sql'].to_list():
    vn.train(ddl=ddl)

For PostgreSQL:

schema = vn.run_sql("""
    SELECT table_name, column_name, data_type
    FROM information_schema.columns
    WHERE table_schema = 'public'
    ORDER BY table_name, ordinal_position
""")
vn.train(documentation=schema.to_markdown())

Then add example question-to-SQL pairs. These do more for accuracy than anything else in the training process. Aim for ten to fifteen examples that cover the questions your team asks most often:

vn.train(
    question="What were total sales by product category last month?",
    sql="""SELECT c.name, SUM(o.amount) as total
           FROM orders o JOIN categories c ON o.category_id = c.id
           WHERE o.created_at >= date_trunc('month', current_date - interval '1 month')
           GROUP BY c.name ORDER BY total DESC"""
)

vn.train(
    question="Which customers have not placed an order in 90 days?",
    sql="""SELECT customer_id, email, MAX(created_at) as last_order
           FROM orders GROUP BY customer_id, email
           HAVING MAX(created_at) < current_date - 90"""
)

A consistent finding across teams that have deployed Vanna in production: questions involving date arithmetic and multi-table joins benefit most from explicit training examples. Generic LLM knowledge handles single-table aggregations reasonably well, but date filters and join paths across related tables require domain-specific examples to get right.

Step 4: Ask Questions and Browse Results

Once trained, you have two ways to interact with Vanna. The first is directly in Python:

sql = vn.generate_sql("What were last month's top ten customers by revenue?")
print(sql)  # inspect the generated SQL first
df = vn.run_sql(sql)
print(df)

Printing the generated SQL before running it is good practice, especially early on. You can see exactly what Vanna generated and verify the logic before acting on the results.

The second option is Vanna's built-in web interface:

from vanna.flask import VannaFlaskApp
app = VannaFlaskApp(vn)
app.run()

This starts a local server at http://localhost:8084 with a chat interface. Users type a question, see the SQL Vanna generated, and browse results in an interactive table. Responses stream in real-time, and Vanna can also render simple charts. Vanna 2.0 ships with a <vanna-chat> web component you can embed directly into an internal tool or dashboard page.

Where Vanna Works Well and Where It Struggles

In independent benchmarks on real enterprise schemas, Vanna with full schema training achieves roughly 75 to 80 percent accuracy on novel questions. Without training, a generic LLM on the same questions scores below 50 percent. The difference is entirely explained by the context provided during the training phase.

Vanna handles straightforward aggregations, group-bys, date ranges, and joins between tables it has been trained on with high reliability. It struggles with deeply nested subqueries, questions that require business logic not encoded in the schema (for example, "show me at-risk accounts" where at-risk is a concept not reflected in any column), and tables it has never seen during training.

When Vanna produces a wrong answer, it typically produces syntactically valid SQL that returns incorrect data rather than an outright error. This is the practical risk to manage. For analysis that informs decisions, sanity-check results against known totals before acting on them. Building a few validation queries into your routine is the fastest way to catch errors early.

Adding more training examples is the reliable fix for persistent errors. If a category of question keeps failing, add two or three more examples covering that pattern and accuracy improves measurably.

Deploying Vanna for a Team

If you want more than one person using Vanna, the Flask app needs to run on a server your team can access. Any standard deployment that hosts a Python Flask app works: a cloud VM, a Docker container, or a managed platform like Railway or Render.

Training data lives in a ChromaDB directory on disk by default. For team deployments, either point all instances at a shared network volume or migrate to a hosted vector store so that training updates made by one person are immediately visible to everyone else.

If your data lives in flat files rather than a database, setting up a schema, training Vanna, and maintaining a server is significant overhead. VSLZ handles plain-English data analysis from a direct file upload with no schema training or infrastructure required.

Practical Summary

Vanna's setup reduces to four steps: install the package, connect to your database, train it on your schema and a set of example queries, then ask questions through Python or the web app. The training step is what makes Vanna accurate. Teams that skip it get below-50-percent accuracy on novel questions; teams that complete it with fifteen or more domain-specific examples typically land above 75 percent. For any team with data locked in a database that wants to give non-technical colleagues a query interface without building a full BI stack, Vanna 2.0 is a practical starting point.