---
title: Plugins
description: Extend SQLsaber with optional plugins for visualization and Python execution
---

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

```bash
uv tool install --with sqlsaber-viz sqlsaber
```

Or if you already have SQLsaber installed:

```bash
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

```bash
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:

```bash
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`:

```python
# myapp/apps.py
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)
```
