SQLsaber
SQLsaber is an open-source agentic SQL assistant. Think Claude Code but for SQL.
Ask questions about databases, SQLite/DuckDB files, and CSVs 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 ./warehouse.duckdb "Show me the latest partition"
# 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, and CSV 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
- Discovery — Lists tables and identifies relevant ones based on your question.
- Schema analysis — Introspects only the tables needed.
- Knowledge retrieval — Searches saved KPI definitions and SQL patterns when useful.
- Query generation — Writes SQL tailored to your database dialect.
- Execution — Runs the query with safety checks.
- 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sqlsaber-0.73.0.tar.gz.
File metadata
- Download URL: sqlsaber-0.73.0.tar.gz
- Upload date:
- Size: 8.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
54ce528a36761c6c03e98756866d5b1d576428d4ae4b0d5155e6cbbd5504f3d2
|
|
| MD5 |
72ff56fa1c4d7073742a1a3df6a92c23
|
|
| BLAKE2b-256 |
b094066083b4507eb7a421626e4e6a466bf1bd686797dccc00bba6abf29a0daa
|
File details
Details for the file sqlsaber-0.73.0-py3-none-any.whl.
File metadata
- Download URL: sqlsaber-0.73.0-py3-none-any.whl
- Upload date:
- Size: 249.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f1718d7ff36339e00f41f75351ccc7f6a73614fad35807e4f3640527b3e6734c
|
|
| MD5 |
4efb8bc7a239fb447476babb10ed0307
|
|
| BLAKE2b-256 |
1df50c6d442f44e5f91223a49e092f92ed647afe0c621dccee2b17bf28da125d
|
