Plugins

SQLsaber supports optional plugins that extend its capabilities. Plugins are installed alongside SQLsaber using uv tool install --with.

You can even write your own plugins and make them available to SQLsaber to use.

Visualization Plugin

The visualization plugin renders charts directly in your terminal from query results.

Installation

uv tool install --with sqlsaber-viz sqlsaber

Or if you already have SQLsaber installed:

uv tool install --with sqlsaber-viz --force sqlsaber

Usage

After running a query, ask for a visualization in natural language:

> Show me the top 10 customers by revenue

| customer_name | total_revenue |
|---------------|---------------|
| Acme Corp     | 50000         |
| Beta Inc      | 45000         |
| ...           | ...           |

> Plot that as a bar chart

┌────────────────────────────────────────────────────┐
│ ███████████████████████████████████████████  50000 │
│ ██████████████████████████████████████       45000 │
│ ...                                                │
└────────────────────────────────────────────────────┘

Supported Chart Types

Chart Type	Best For
Bar	Comparing categories, rankings, distributions
Line	Time series, trends over time
Scatter	Correlations between two numeric variables
Histogram	Distribution of a single numeric variable
Boxplot	Statistical distribution across categories

You don’t need to specify the chart type explicitly. Just describe what you want to see and SQLsaber will pick the appropriate chart type based on your data.

Python Sandbox Plugin

The sandbox plugin lets SQLsaber run Python code in a secure remote sandbox. This is useful for calculations, stats, or data transformations that are easier in Python than SQL.

Installation

uv tool install --with sqlsaber-sandbox sqlsaber

Configuration

You need to configure at least one sandbox provider:

Provider	Environment Variable
Daytona	`DAYTONA_API_KEY`
E2B	`E2B_API_KEY`
Sprites	`SPRITES_TOKEN`
Hopx	`HOPX_API_KEY`
Modal	`MODAL_TOKEN_ID` or `~/.modal.toml`
Cloudflare	`CLOUDFLARE_SANDBOX_BASE_URL` + `CLOUDFLARE_API_TOKEN`

When at least one provider is configured, the agent can use a run_python tool to execute Python code in that sandbox. If no provider is configured, the tool is not available.

Installing Multiple Plugins

You can install multiple plugins at once:

uv tool install --with sqlsaber-viz,sqlsaber-sandbox sqlsaber

Registering Custom Tools in a Django App

You can register custom tools directly in a Django app using AppConfig.ready:

from django.apps import AppConfig

from sqlsaber.tools.registry import tool_registry
from myapp.tools import MyCustomTool


class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        tool_registry.register(MyCustomTool)