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)