SQLsaber
SQLsaber is an open-source agentic SQL assistant. Ask questions about databases, SQLite or DuckDB files, CSVs, and Parquet files in plain English from your terminal or from Python. SQLsaber reads your schema, writes SQL, runs read-only queries by default, and explains the results.
The CLI and TUI use the SQLSaber conversation lifecycle. Clients own input and presentation. SQLSaber owns agent behavior, completed history, and thread lifecycle.
SQLsaber appears in an ACM Conference on AI and Agentic Systems '26 paper. Read the paper.
Quickstart
# Recommended if you have uv
uv tool install sqlsaber
# If you do not have uv
curl -LsSf https://uvx.sh/sqlsaber/install.sh | sh
On Windows without uv:
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/sqlsaber/install.ps1 | iex"
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 several 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, and get answers.
- Schema-aware. Discovers tables, columns, indexes, comments, and relationships.
- Safe by default. Runs read-only queries unless you pass
--allow-dangerous. - 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. 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 several 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
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
- Plugins
- Python SDK
- Command reference
Contributing
Open an issue before large changes.
If you find SQLsaber useful, a star on GitHub helps others discover it.
License
Apache-2.0. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for sqlsaber 0.77.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sqlsaber-0.77.0.tar.gz | 9.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sqlsaber-0.77.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 9.3 MB
Release files / sqlsaber-0.77.0.tar.gz
| Download URL | sqlsaber-0.77.0.tar.gz |
|---|---|
| Size | 9.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cb1d58d50444cde8170aecf7689fbfd22ac68859adacc1133a23616b1185c53f
|
|
BLAKE2b-256 checksum How to use checksums |
a1881560b0f1f264c6b1e417ad26f4b046de18137cd03edf927c181a7db7ba51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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}
|
Release files / sqlsaber-0.77.0-py3-none-any.whl
| Download URL | sqlsaber-0.77.0-py3-none-any.whl |
|---|---|
| Size | 280.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67c4331fc0363a9147a6e3a8347fa947902294d8d7c2a89bdbef99fddb765336
|
|
BLAKE2b-256 checksum How to use checksums |
1580836ac7788a76b0b8da70f12ceab925fec65afab0098ae24c149dbde66e16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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}
|
