# Supabash

> Give Claude (and the user) direct psql access to a Supabase database by generating a project-specific db-cli.sh — no MCP, no Supabase CLI install. Invoke when the user wants database access, wants to run SQL against Supabase, apply schema migrations, back up / restore the database, or says things like "set up db access", "give me psql access to Supabase", "let Claude query my database", "inspect my Supabase schema", "I don't want an MCP for this".

- Skill: `jeep15cba/supabash` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jeep15cba/supabash`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeep15cba/supabash/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: jeep15cba (https://skillmd.com/u/jeep15cba)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jeep15cba/supabash

---


# supabash

Generate a lightweight, project-specific bash tool (`db-cli.sh`) that gives direct `psql` access to a Supabase Postgres database. Pure bash + `psql` + `pg_dump`. No MCP. No Supabase CLI.

## When to invoke

- User wants to query / inspect / migrate / backup a Supabase Postgres database
- User wants Claude to "have access" to their database for future sessions
- User hits IPv6 / connection errors with direct Supabase connection strings
- User says they don't want an MCP or the full Supabase CLI for this

## When NOT to invoke

- User is working in `@supabase/supabase-js` / Python SDK application code (that's the SDK, not direct DB access)
- User is running `supabase start` / `supabase db push` for local-first development (official CLI handles that)
- No Supabase project exists in the repo

## What this skill produces

Four artifacts in the user's project:

1. **`db-cli.sh`** at the repo root — bash script tailored to this project's actual env path, URL var name, and migrations dir
2. **`DB_ACCESS_GUIDE.md`** at the repo root — command reference with examples using the project's real table names
3. **Env file update** — `SUPABASE_SESSION_POOLER` variable added (or placeholder with clear instructions)
4. **`CLAUDE.md` (or `AGENTS.md`) update** — a "Database access" section so future sessions know the tool exists

## Step-by-step

### Step 1 — Discover the project

Read (in parallel where possible):
- `package.json` at root and `apps/*/package.json` — detect monorepo vs single app
- Env files: first match of `.env.local`, `.env`, `apps/*/.env.local`
- Migrations dir: first match of `supabase/migrations/`, `apps/*/supabase/migrations/`, `db/migrations/`
- Existing `CLAUDE.md` / `AGENTS.md` — check if skill has been run before (don't duplicate)

Report in 2 lines: "Detected [stack] at [env path], migrations at [path]. Proceeding." Then continue.

### Step 2 — Locate the Postgres URL

Grep the chosen env file for `SUPABASE_SESSION_POOLER`, `DATABASE_URL`, or `POSTGRES_URL`. If one is set, use that var name. If none, tell the user:

> To continue, grab the session pooler URL from Supabase dashboard → **Project Settings → Database → Connection string → Session pooler tab** (NOT "Direct connection" — that requires IPv6).
>
> Format: `postgresql://postgres.<ref>:<password>@aws-<n>-<region>.pooler.supabase.com:5432/postgres`
>
> Add it to `<detected env path>` as `SUPABASE_SESSION_POOLER=...` then say "done".

Wait for them. Re-grep. Do not proceed without it.

### Step 3 — Generate `db-cli.sh`

Read [`SPEC.md`](./SPEC.md) in this skill folder. Generate `db-cli.sh` at the user's repo root implementing every command listed there, with:

- **Hardcoded paths** (not auto-detection) — the script should literally reference the detected env file and migrations dir
- **Only include migrate-\* commands** if a migrations dir was found; otherwise omit them from the help text and dispatch
- **Executable bit set** (`chmod +x`)

Keep the script under 250 lines. Match command names, output formats, and exit codes exactly as SPEC.md describes — users copy-paste from that reference.

### Step 4 — Inspect real schema, generate `DB_ACCESS_GUIDE.md`

Run `./db-cli.sh tables` to list the actual tables. Copy [`GUIDE_TEMPLATE.md`](./GUIDE_TEMPLATE.md) to the user's repo root as `DB_ACCESS_GUIDE.md`, substituting:

- `{{TABLES}}` — real table names in examples
- `{{ENV_FILE}}` — detected env path
- `{{MIGRATIONS_DIR}}` — detected migrations dir (or remove the migrations section if none)

### Step 5 — Update `CLAUDE.md` / `AGENTS.md`

If `CLAUDE.md` exists at repo root, append (only if not already present — grep first):

    ## Database access (`db-cli.sh`)

    `./db-cli.sh` at the repo root gives direct Supabase psql access via the session pooler. Reads `SUPABASE_SESSION_POOLER` from `{{ENV_FILE}}`. See `DB_ACCESS_GUIDE.md` for full reference.

    Common commands:
    - `./db-cli.sh tables` — list tables with row counts
    - `./db-cli.sh describe <table>` — schema for a table
    - `./db-cli.sh query "<SQL>"` — run ad-hoc SQL
    - `./db-cli.sh migrate-new <name>` / `migrate-apply` — migrations
    - `./db-cli.sh backup [name]` — pg_dump to `.db-backups/`

    Connects as `postgres` superuser — RLS is **bypassed**. Be intentional with writes.

If `AGENTS.md` exists instead, use that. If neither exists, ask the user which convention they prefer before creating one.

### Step 6 — Update `.gitignore`

Append if not already present:
```
.db-backups/
```

### Step 7 — Verify

Run `./db-cli.sh tables` and show the output. Confirm setup worked. Done.

## Non-negotiables

- **No downloads.** Generate the script locally from SPEC.md. Do not curl/wget anything.
- **No auto-detection in the generated script.** This skill already did detection — bake paths in literally.
- **No telemetry, analytics, or phone-home.** Script is standalone.
- **Match SPEC.md exactly.** The generated help text, command names, and exit codes must match so users can trust the `DB_ACCESS_GUIDE.md` reference.
- **Session pooler only** (port 5432). Never default to transaction pooler (6543) or direct connection.