The community-maintained, security-focused continuation of Vanna.
🚧 Work in progress. Vanna was archived on 29 March 2026 with ~227 open issues. asksql picks it up: security fixes first, then bug fixes and dependency updates.
pip uninstall vanna
pip install asksqlasksql keeps the vanna import name (like Pillow did for PIL), so import vanna, from vanna import Agent and the legacy VannaBase API work as before. Uninstall Vanna before installing asksql, because both ship the same vanna/ folder.
📘 Migration guide: requirements files, coming from Vanna 0.x, behaviour changes, troubleshooting.
🔌 Server API: HTTP endpoints (/health, chat_poll, chat_sse), request/response format, CORS.
| Issue | Fix |
|---|---|
| CVE-2026-4229 · #1121 | SQL injection in the BigQuery vector store |
| #1098 | LLM-written Plotly code could run arbitrary Python on the server (exec with full access) |
| #1078 | LLM-generated SQL ran unfiltered (prompt injection → DROP, shell commands via the database) |
config={"allow_write_sql": True} (legacy API) or RunSqlTool(..., allow_write_sql=True) (v2). See CHANGELOG.md.
Found a bug or a security problem? Open an issue.
Everything below is the original Vanna 2.0 README. Upstream docs at vanna.ai still describe the API.
Natural language → SQL → Answers. Now with enterprise security and user-aware permissions.
1118.mp4
🔐 User-Aware at Every Layer — Queries automatically filtered per user permissions
🎨 Modern Web Interface — Beautiful pre-built <vanna-chat> component
⚡ Streaming Responses — Real-time tables, charts, and progress updates
🔒 Enterprise Security — Row-level security, audit logs, rate limiting
🔄 Production-Ready — FastAPI integration, observability, lifecycle hooks
Upgrading from 0.x? See the Migration Guide | What changed?
<!-- Drop into any existing webpage -->
<script src="https://img.vanna.ai/vanna-components.js"></script>
<vanna-chat
sse-endpoint="https://your-api.com/chat"
theme="dark">
</vanna-chat>Uses your existing cookies/JWTs. Works with React, Vue, or plain HTML.
Ask a question in natural language and get back:
1. Streaming Progress Updates
2. SQL Code Block (By default only shown to "admin" users)
3. Interactive Data Table
4. Charts (Plotly visualizations)
5. Natural Language Summary
All streamed in real-time to your web component.
- Production chat interface
- Custom agent with your database
- Embed in any webpage
User-aware at every layer — Identity flows through system prompts, tool execution, and SQL filtering Row-level security — Queries automatically filtered per user permissions Audit logs — Every query tracked per user for compliance Rate limiting — Per-user quotas via lifecycle hooks
Pre-built <vanna-chat> component — No need to build your own chat interface
Streaming tables & charts — Rich components, not just text
Responsive & customizable — Works on mobile, desktop, light/dark themes
Framework-agnostic — React, Vue, plain HTML
Any LLM: OpenAI, Anthropic, Ollama, Azure, Google Gemini, AWS Bedrock, Mistral, Others Any Database: PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQLite, Oracle, SQL Server, DuckDB, ClickHouse, Others Your Auth System: Bring your own — cookies, JWTs, OAuth tokens Your Framework: FastAPI, Flask
Custom tools — Extend the Tool base class
Lifecycle hooks — Quota checking, logging, content filtering
LLM middlewares — Caching, prompt engineering
Observability — Built-in tracing and metrics
sequenceDiagram
participant U as 👤 User
participant W as 🌐 <vanna-chat>
participant S as 🐍 Your Server
participant A as 🤖 Agent
participant T as 🧰 Tools
U->>W: "Show Q4 sales"
W->>S: POST /api/vanna/v2/chat_sse (with auth)
S->>A: User(id=alice, groups=[read_sales])
A->>T: Execute SQL tool (user-aware)
T->>T: Apply row-level security
T->>A: Filtered results
A->>W: Stream: Table → Chart → Summary
W->>U: Display beautiful UI
Key Concepts:
- User Resolver — You define how to extract user identity from requests (cookies, JWTs, etc.)
- User-Aware Tools — Tools automatically check permissions based on user's group memberships
- Streaming Components — Backend streams structured UI components (tables, charts) to frontend
- Built-in Web UI — Pre-built
<vanna-chat>component renders everything beautifully
Here's a complete example integrating Vanna with your existing FastAPI app and authentication:
from fastapi import FastAPI
from vanna import Agent
from vanna.servers.fastapi.routes import register_chat_routes
from vanna.servers.base import ChatHandler
from vanna.core.user import UserResolver, User, RequestContext
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.core.registry import ToolRegistry
# Your existing FastAPI app
app = FastAPI()
# 1. Define your user resolver (using YOUR auth system)
class MyUserResolver(UserResolver):
async def resolve_user(self, request_context: RequestContext) -> User:
# Extract from cookies, JWTs, or session
token = request_context.get_header('Authorization')
user_data = self.decode_jwt(token) # Your existing logic
return User(
id=user_data['id'],
email=user_data['email'],
group_memberships=user_data['groups'] # Used for permissions
)
# 2. Set up agent with tools
llm = AnthropicLlmService(model="claude-sonnet-4-5")
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))
agent = Agent(
llm_service=llm,
tool_registry=tools,
user_resolver=MyUserResolver()
)
# 3. Add Vanna routes to your app
chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)
# Now you have:
# - POST /api/vanna/v2/chat_sse (streaming endpoint)
# - GET / (optional web UI)Then in your frontend:
<vanna-chat sse-endpoint="/api/vanna/v2/chat_sse"></vanna-chat>See Full Documentation for custom tools, lifecycle hooks, and advanced configuration
Extend Vanna with custom tools for your specific use case:
from vanna.core.tool import Tool, ToolContext, ToolResult
from pydantic import BaseModel, Field
from typing import Type
class EmailArgs(BaseModel):
recipient: str = Field(description="Email recipient")
subject: str = Field(description="Email subject")
class EmailTool(Tool[EmailArgs]):
@property
def name(self) -> str:
return "send_email"
@property
def access_groups(self) -> list[str]:
return ["send_email"] # Permission check
def get_args_schema(self) -> Type[EmailArgs]:
return EmailArgs
async def execute(self, context: ToolContext, args: EmailArgs) -> ToolResult:
user = context.user # Automatically injected
# Your business logic
await self.email_service.send(
from_email=user.email,
to=args.recipient,
subject=args.subject
)
return ToolResult(success=True, result_for_llm=f"Email sent to {args.recipient}")
# Register your tool
tools.register(EmailTool())Vanna 2.0 includes powerful enterprise features for production use:
Lifecycle Hooks — Add quota checking, custom logging, content filtering at key points in the request lifecycle
LLM Middlewares — Implement caching, prompt engineering, or cost tracking around LLM calls
Conversation Storage — Persist and retrieve conversation history per user
Observability — Built-in tracing and metrics integration
Context Enrichers — Add RAG, memory, or documentation to enhance agent responses
Agent Configuration — Control streaming, temperature, max iterations, and more
Vanna is ideal for:
- 📊 Data analytics applications with natural language interfaces
- 🔐 Multi-tenant SaaS needing user-aware permissions
- 🎨 Teams wanting a pre-built web component + backend
- 🏢 Enterprise environments with security/audit requirements
- 📈 Applications needing rich streaming responses (tables, charts, SQL)
- 🔄 Integrating with existing authentication systems
- 🐛 asksql Issues — Bug reports and security problems for this fork
- 📖 Upstream Vanna Documentation — Guides and API reference (still applies)
Upgrading from Vanna 0.x?
Vanna 2.0 is a complete rewrite focused on user-aware agents and production deployments. Key changes:
- New API: Agent-based instead of
VannaBaseclass methods - User-aware: Every component now knows the user identity
- Streaming: Rich UI components instead of text/dataframes
- Web-first: Built-in
<vanna-chat>component and server
Migration path:
- Quick wrap — Use
LegacyVannaAdapterto wrap your existing Vanna 0.x instance and get the new web UI immediately - Gradual migration — Incrementally move to the new Agent API and tools
See the complete Migration Guide for step-by-step instructions.
MIT License — See LICENSE for details. Original copyright (c) 2024 Vanna.AI is kept.
Originally built with ❤️ by the Vanna team. asksql is an independent community fork and is not affiliated with or endorsed by Vanna.AI.