Query Supabase Safely with a CLI

---
name: query-supabase-workflow
description: "Inspect local project state first, identify the linked project explicitly, and use a read-only database path for production data."
---

# Query Supabase

## Intended outcome

Answer Supabase project or database questions without crossing project boundaries or bypassing data protections.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **Supabase CLI** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `npm install --save-dev supabase`
  - Authentication: access token, database password, local development
  - Minimum permissions: Use a token limited to the intended organization and verify the linked project before remote commands.
- **PostgreSQL psql** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 18.1 recorded)
  - Install: `brew install libpq`
  - Authentication: connection URI, password file, service file, peer authentication
  - Minimum permissions: Use a read-only database role, TLS, and a database/schema search path limited to the task.

## Input contract

- Project directory
- explicit project reference
- read-only database credentials
- bounded question

## Output contract

- Local service status
- confirmed project identity
- bounded query result
- risk-aware next steps

## Safe workflow

1. **Inspect local state** — Read project configuration and local service status before connecting remotely.
   - Input: Supabase project directory
   - Output: Local configuration and service state
   - Risk: `read-only`
   - Command: `supabase status --output json`
2. **Confirm the remote target** — Verify the project reference and credential scope without exposing secrets.
   - Input: Project reference and protected credentials
   - Output: Confirmed remote target
   - Risk: `read-only`
3. **Run a bounded read** — Use psql or an approved data API with a read-only identity and explicit limits.
   - Input: Reviewed query and confirmed target
   - Output: Structured result
   - Risk: `read-only`

## Ask before proceeding

- Linking or unlinking a project
- Database pushes, migrations, resets, or function deployments
- Using a service-role key or changing production data

## Rollback

- Keep local configuration changes in version control
- Use reversible migrations for approved schema changes
- Restore a database backup only through the project’s incident procedure

## Official sources

- [Supabase CLI documentation](https://supabase.com/docs/guides/cli) — Official Supabase CLI reference for local development and project operations.
- [PostgreSQL psql documentation](https://www.postgresql.org/docs/current/app-psql.html) — Official psql options, variables, output formats, and execution behavior.