name: supabase-query
description: Query Supabase cloud database via REST API using project ID and anon key. Use when the user needs to query their Supabase database, inspect table schemas, or retrieve data. Only supports read operations for security.
license: MIT
compatibility: Requires Python 3.x and Windows with PowerShell or CMD. No database drivers needed.
metadata:
author: user
version: "2.0"

Supabase Query Skill

This skill allows AI agents to query Supabase cloud database via REST API using only project ID and anon key.

Security Features

• Cloud-native: Uses Supabase REST API, no direct database connection
• Read-only operations: Only SELECT-style queries via HTTP GET
• Row limit: Maximum 200 rows returned per query
• Timeout protection: 30-second request timeout
• Local config: Credentials stored in local .env file (not in version control)

Prerequisites

1. Python 3.x installed
2. Supabase project with API access enabled

Setup

1. Copy references/.env.example to references/.env
2. Fill in your Supabase credentials in references/.env:

• SUPABASE_PROJECT_ID: Your Supabase project ID (from project URL)
• SUPABASE_ANON_KEY: Your anon/public API key (from Settings → API)

Usage

Run the query script from the skill directory:

python scripts/query.py "users" --select "*" --limit 10

Or on Windows:

scripts\query.bat users --select "*" --limit 10

Output Format

The script returns JSON:

{
  "success": true,
  "table": "users",
  "rows": [...],
  "row_count": 10,
  "truncated": false
}

Error response:

{
  "success": false,
  "error": "Error message here"
}

Examples

Query all columns

python scripts/query.py "users" --select "*" --limit 20

Query specific columns with filter

python scripts/query.py "users" --select "id,name,email" --eq "status:active" --limit 10

Query with ordering

python scripts/query.py "posts" --select "title,created_at" --order "created_at.desc" --limit 5

Troubleshooting

• "Config file not found": Create references/.env from the example file
• "Connection failed": Check your project ID and anon key
• "Table not found": Verify the table name and RLS policies
• "Permission denied": Check if anon key has access to the table (RLS settings)