> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL buttons

> Run a stored SQL query against a connected database.

SQL buttons will wrap a parameterized query as a pressable action. The query lives as a file inside the button folder, the database connection is resolved from a reusable credential stored in Buttons' credential system, and arguments are bound as query parameters (not string-interpolated).

```bash theme={null}
# Planned shape
buttons create top-users \
  --sql ./queries/top-users.sql \
  --db analytics-prod \
  --arg limit:int:optional
```

Press it:

```bash theme={null}
buttons press top-users --arg limit=50 --json
```

## Current workaround

SQL buttons are not implemented yet. Today, wrap a SQL CLI with a code button and store credentials in batteries:

```bash theme={null}
buttons batteries set ANALYTICS_DATABASE_URL 'postgres://...' --global

buttons create top-users \
  --code 'psql "$BUTTONS_BAT_ANALYTICS_DATABASE_URL" -f queries/top-users.sql' \
  --runtime shell \
  --arg limit:int:optional
```

## What's changing when SQL buttons land

* `--sql <file>` flag reads the query from disk, copies it into the button folder
* `--db <name>` resolves to a battery-backed connection reference
* Arguments bind as parameters, not string substitution — no SQL injection surface
* Supported drivers: Postgres first, then MySQL, then SQLite