Supabase DB

Connect to Supabase for SQL queries, CRUD, table management, and vector similarity search using pgvector extension and OpenAI embeddings.

Security Scan

The skill implements the advertised Supabase DB functionality, but packaging inconsistencies and the requirement to supply a Supabase service-role key (full DB/admin access) and external API keys raise proportionality and installation concerns.

Purpose & Capability

The name/description match the provided script and README: the skill performs SQL, CRUD, table management, and pgvector/OpenAI-based vector search. However the registry metadata claims no required environment variables or binaries while SKILL.md and the shipped script explicitly require SUPABASE_URL, SUPABASE_SERVICE_KEY (and OPENAI_API_KEY for vector search) and rely on curl/jq. This metadata mismatch is a packaging/information inconsistency.

Instruction Scope

SKILL.md and the script confine actions to Supabase and OpenAI endpoints and to DB operations; they do not instruct reading arbitrary host files or harvesting unrelated environment variables. Vector-search flows call OpenAI to generate embeddings and call Supabase RPCs. The script will send the provided keys to those services (expected for the stated features).

Install Mechanism

There is no external install/download: this is an instruction-only skill with a bundled shell script. No remote archives or obscure URLs are fetched during install. Risk is limited to running the included script, which will be written to disk if the user installs the skill.

Credentials

The skill requires a Supabase service-role key (SUPABASE_SERVICE_KEY) which grants full database access and bypasses Row-Level Security — a high-privilege credential. That level of access is consistent with features like raw SQL and creating extensions but is sensitive and broad. The skill also uses OPENAI_API_KEY for embeddings. The registry metadata failing to declare these required env vars increases the chance users will unintentionally expose high-privilege credentials. Prefer least-privilege/project-scoped keys where possible.

Persistence & Privilege

The skill does not force permanent inclusion (always:false) but allows autonomous invocation (platform default). Autonomous invocation combined with a supplied service-role key raises the blast radius: if the agent invokes this skill on its own, it could perform high-privilege DB operations without further prompts. This is expected for DB admin-style skills but is worth conscious risk consideration.

What to consider before installing

This skill appears to implement the Supabase functionality it claims, but proceed cautiously: 1) It requires a Supabase service-role key (SUPABASE_SERVICE_KEY) that can read/modify all data and bypasses RLS — only provide a service key if you trust the skill and consider using a least-privilege/project-scoped key instead. 2) Vector search requires an OpenAI API key; the script will send your query text to OpenAI and use the returned embedding. 3) The package metadata does not list these env vars or required tools (curl, jq); check you trust the source and inspect scripts before installing. 4) If you install, run the skill in an isolated environment or with rotated/limited keys first, and avoid giving permanent high-privilege credentials to untrusted skills.

Supabase CLI

Interact with Supabase projects: queries, CRUD, vector search, and table management.

API Key Migration (March 2026): Supabase is deprecating legacy service keys starting March 11, 2026. Get your new project-scoped key: Dashboard → Settings → API → API Keys. Set SUPABASE_API_KEY going forward. Legacy SUPABASE_SERVICE_KEY still works until late 2026.

Setup

# Required
export SUPABASE_URL="https://yourproject.supabase.co"
export SUPABASE_SERVICE_KEY="eyJhbGciOiJIUzI1NiIs..."  # legacy — use SUPABASE_API_KEY for new projects

# New project-scoped key (preferred, March 2026+)
export SUPABASE_API_KEY="sbp_..."

# Optional: for management API
export SUPABASE_ACCESS_TOKEN="sbp_xxxxx"

Quick Commands

# SQL query
{baseDir}/scripts/supabase.sh query "SELECT * FROM users LIMIT 5"

# Insert data
{baseDir}/scripts/supabase.sh insert users '{"name": "John", "email": "[e-mail]"}'

# Select with filters
{baseDir}/scripts/supabase.sh select users --eq "status:active" --limit 10

# Update
{baseDir}/scripts/supabase.sh update users '{"status": "inactive"}' --eq "id:123"

# Delete
{baseDir}/scripts/supabase.sh delete users --eq "id:123"

# Vector similarity search
{baseDir}/scripts/supabase.sh vector-search documents "search query" --match-fn match_documents --limit 5

# List tables
{baseDir}/scripts/supabase.sh tables

# Describe table
{baseDir}/scripts/supabase.sh describe users

Commands Reference

query - Run raw SQL

{baseDir}/scripts/supabase.sh query "<SQL>"

# Examples
{baseDir}/scripts/supabase.sh query "SELECT COUNT(*) FROM users"
{baseDir}/scripts/supabase.sh query "CREATE TABLE items (id serial primary key, name text)"
{baseDir}/scripts/supabase.sh query "SELECT * FROM users WHERE created_at > '2024-01-01'"

select - Query table with filters

{baseDir}/scripts/supabase.sh select <table> [options]

Options:
  --columns <cols>    Comma-separated columns (default: *)
  --eq <col:val>      Equal filter (can use multiple)
  --neq <col:val>     Not equal filter
  --gt <col:val>      Greater than
  --lt <col:val>      Less than
  --like <col:val>    Pattern match (use % for wildcard)
  --limit <n>         Limit results
  --offset <n>        Offset results
  --order <col>       Order by column
  --desc              Descending order

# Examples
{baseDir}/scripts/supabase.sh select users --eq "status:active" --limit 10
{baseDir}/scripts/supabase.sh select posts --columns "id,title,created_at" --order created_at --desc
{baseDir}/scripts/supabase.sh select products --gt "price:100" --lt "price:500"

insert - Insert row(s)

{baseDir}/scripts/supabase.sh insert <table> '<json>'

# Single row
{baseDir}/scripts/supabase.sh insert users '{"name": "Alice", "email": "[e-mail]"}'

# Multiple rows
{baseDir}/scripts/supabase.sh insert users '[{"name": "Bob"}, {"name": "Carol"}]'

update - Update rows

{baseDir}/scripts/supabase.sh update <table> '<json>' --eq <col:val>

# Example
{baseDir}/scripts/supabase.sh update users '{"status": "inactive"}' --eq "id:123"
{baseDir}/scripts/supabase.sh update posts '{"published": true}' --eq "author_id:5"

upsert - Insert or update

{baseDir}/scripts/supabase.sh upsert <table> '<json>'

# Example (requires unique constraint)
{baseDir}/scripts/supabase.sh upsert users '{"id": 1, "name": "Updated Name"}'

delete - Delete rows

{baseDir}/scripts/supabase.sh delete <table> --eq <col:val>

# Example
{baseDir}/scripts/supabase.sh delete sessions --lt "expires_at:2024-01-01"

vector-search - Similarity search with pgvector

{baseDir}/scripts/supabase.sh vector-search <table> "<query>" [options]

Options:
  --match-fn <name>     RPC function name (default: match_<table>)
  --limit <n>           Number of results (default: 5)
  --threshold <n>       Similarity threshold 0-1 (default: 0.5)
  --embedding-model <m> Model for query embedding (default: uses OpenAI)

# Example
{baseDir}/scripts/supabase.sh vector-search documents "How to set up authentication" --limit 10

# Requires a match function like:
# CREATE FUNCTION match_documents(query_embedding vector(1536), match_threshold float, match_count int)

tables - List all tables

{baseDir}/scripts/supabase.sh tables

describe - Show table schema

{baseDir}/scripts/supabase.sh describe <table>

rpc - Call stored procedure

{baseDir}/scripts/supabase.sh rpc <function_name> '<json_params>'

# Example
{baseDir}/scripts/supabase.sh rpc get_user_stats '{"user_id": 123}'

Vector Search Setup

1. Enable pgvector extension

CREATE EXTENSION IF NOT EXISTS vector;

2. Create table with embedding column

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text,
  metadata jsonb,
  embedding vector(1536)
);

3. Create similarity search function

CREATE OR REPLACE FUNCTION match_documents(
  query_embedding vector(1536),
  match_threshold float DEFAULT 0.5,
  match_count int DEFAULT 5
)
RETURNS TABLE (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    documents.id,
    documents.content,
    documents.metadata,
    1 - (documents.embedding <=> query_embedding) AS similarity
  FROM documents
  WHERE 1 - (documents.embedding <=> query_embedding) > match_threshold
  ORDER BY documents.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

4. Create index for performance

CREATE INDEX ON documents 
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

Environment Variables

Variable	Required	Description
SUPABASE_URL	Yes	Project URL (https://xxx.supabase.co)
SUPABASE_SERVICE_KEY	Yes	Service role key (full access)
SUPABASE_ANON_KEY	No	Anon key (restricted access)
SUPABASE_ACCESS_TOKEN	No	Management API token
OPENAI_API_KEY	No	For generating embeddings

Notes

• Service role key bypasses RLS (Row Level Security)
• Use anon key for client-side/restricted access
• Vector search requires pgvector extension
• Embeddings default to OpenAI text-embedding-ada-002 (1536 dimensions)