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

Building a plugin

Plugins ship pydantic-ai capabilities through an entry point:

[project.entry-points."sqlsaber.capabilities"]
my_plugin = "my_plugin:capability"

A typical one-tool plugin is small:

from pydantic_ai.capabilities import Capability
from sqlsaber.capabilities.plugins import PluginContext


def my_tool(value: str) -> str:
    """Process a value using my application."""
    return value


def capability(context: PluginContext):
    return Capability(
        id="my-plugin",
        description="Process values with my application.",
        tools=[my_tool],
    )

The factory receives a PluginContext containing SQLsaber’s database registry, knowledge manager, dangerous-mode setting, and normalized tool model overrides. It can return one capability or a sequence. See the Capabilities SDK guide for standalone composition and lifecycle details.