SQLsaber

SQLsaber is an open-source agentic SQL assistant. Think Claude Code but for SQL.

Ask questions about databases, SQLite/DuckDB files, CSVs, and Parquet files in plain English from your terminal or Python code. SQLsaber reads your schema, writes SQL, executes read-only queries by default, and explains the results.

SQLSaber is the canonical conversation lifecycle used by the CLI and TUI. Clients own input and presentation, while SQLSaber owns agent behavior, completed history, and thread lifecycle.

Featured in research: SQLsaber appears in an ACM Conference on AI and Agentic Systems '26 paper. Read the paper.

Quickstart

# Recommended
uv tool install sqlsaber

Try SQLsaber with the sample SQLite database:

curl -L -o legislators.db https://github.com/SarthakJariwala/sqlsaber/raw/refs/heads/main/legislators.db

saber -d ./legislators.db "How many VPs became president by election in the 20th century?"

Or connect your own database:

saber db add analytics
saber "Show me revenue by month"

On first launch, SQLsaber walks you through connecting a database and setting up authentication.

Use it with your data

# Interactive mode
saber

# Single question
saber "show me users who signed up this week"

# Pipe from stdin
echo "top 10 customers by revenue" | saber

# Use a saved database connection
saber -d analytics "count active subscriptions"

# Use a connection string directly
saber -d "postgresql://user:pass@localhost:5432/mydb" "count users"

# Query local files
saber -d ./customers.csv "How many customers are from each state?"
saber -d ./orders.parquet "What is total revenue?"
saber -d ./warehouse.duckdb "Show me the latest partition"

# Join CSV and Parquet files using DuckDB
saber -d ./customers.csv -d ./orders.parquet "Revenue by customer"

# Connect multiple databases in one session
saber -d sales -d analytics "Compare last month's revenue to web sessions"

Why SQLsaber?

• No context switching — Stay in your terminal, ask questions, get answers.
• Schema-aware — Automatically discovers tables, columns, indexes, comments, and relationships.
• Safe by default — Runs read-only queries unless you explicitly enable dangerous mode.
• Works with your stack — PostgreSQL, MySQL, SQLite, DuckDB, CSV, and Parquet files.
• Remembers your work — Resume previous analysis with conversation threads.
• Learns your business context — Store KPI definitions, SQL patterns, and domain notes in a searchable knowledge base.
• Flexible model support — Use Anthropic, OpenAI, Google, Groq, xAI, Mistral, Cohere, Hugging Face, and other supported providers.

Common workflows

Workflow	Command
Explore data interactively	saber
Ask a one-off question	saber "monthly active users"
Analyze a CSV	saber -d ./customers.csv "customers by state"
Compare multiple databases	saber -d sales -d analytics "compare revenue to traffic"
Save a KPI definition	saber knowledge add "Revenue KPI" "Recognized revenue from shipped orders only"
Resume previous analysis	saber threads list then saber threads resume <id>
Automate a thread follow-up	saber --thread <id> "compare with last quarter"
Use deeper reasoning	saber --thinking "analyze retention by cohort"

Knowledge base

Save reusable business context so SQLsaber can answer consistently:

saber knowledge add \
  "Revenue KPI" \
  "Recognized revenue from shipped orders only" \
  --sql "SELECT SUM(amount) FROM orders WHERE status = 'shipped'" \
  --source "finance-wiki"

saber knowledge search "revenue shipped orders"

Knowledge entries are scoped per database and are discovered automatically when relevant.

Optional plugins

Install official plugins alongside SQLsaber:

# Render charts in your terminal
uv tool install --with sqlsaber-viz sqlsaber

# Delegate multi-step analysis to a sandboxed notebook agent (recommended)
uv tool install --with sqlsaber-notebook sqlsaber

# Run one-off Python snippets in a remote sandbox
uv tool install --with sqlsaber-sandbox sqlsaber

# Install all official analysis plugins
uv tool install --with sqlsaber-viz,sqlsaber-notebook,sqlsaber-sandbox sqlsaber

Python SDK

Use the same SQLsaber conversation lifecycle from Python scripts, notebooks, web apps, or pipelines. A second saber.query() on the same instance uses the prior completed history automatically:

import asyncio

from sqlsaber import SQLSaber, SQLSaberOptions


async def main() -> None:
    options = SQLSaberOptions(database="sqlite:///my.db")

    async with SQLSaber(options=options) as saber:
        result = await saber.query("Top 5 customers by revenue")
        print(result.text)
        print(result.usage)

        follow_up = await saber.query("Now show the same customers by country")
        print(follow_up.text)


asyncio.run(main())

Or compose SQLsaber's tools into an agent you own:

from pydantic_ai import Agent
from sqlsaber import SqlTools

sql = SqlTools(database="sqlite:///my.db")
agent = Agent(
    "anthropic:claude-sonnet-4-6",
    instructions="You are my analytics copilot.",
    capabilities=[sql],
)

async with agent:  # opens and closes connections owned by SqlTools
    result = await agent.run("Top 5 customers by revenue")

See the Capabilities guide for multi-database use, knowledge search, custom capabilities, and lifecycle details.

How it works

1. Discovery — Lists tables and identifies relevant ones based on your question.
2. Schema analysis — Introspects only the tables needed.
3. Knowledge retrieval — Searches saved KPI definitions and SQL patterns when useful.
4. Query generation — Writes SQL tailored to your database dialect.
5. Execution — Runs the query with safety checks.
6. Results — Formats the output with an explanation.

Documentation

Full docs at sqlsaber.com:

• Installation
• Getting Started
• Database Setup
• Running Queries
• Multiple Databases
• Knowledge Base
• Python SDK
• Command Reference

Contributing

Contributions welcome! Please open an issue first to discuss changes.

If you find SQLsaber useful, a ⭐ on GitHub helps others discover it.

License

Apache-2.0 — see LICENSE