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 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 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.