ethereumdegen/supabase

Supabase Integration

Manage your Supabase projects using the Supabase CLI. Run SQL queries, manage migrations, deploy edge functions, handle secrets, and more.

Authentication

First, check if SUPABASE_ACCESS_TOKEN is configured:

key_name: SUPABASE_ACCESS_TOKEN

If not configured, ask the user to create a Personal Access Token at https://supabase.com/dashboard/account/tokens and add it in Settings > API Keys as SUPABASE_ACCESS_TOKEN.

The SUPABASE_ACCESS_TOKEN env var is automatically injected into all exec commands.

---

Prerequisites

Ensure the Supabase CLI is installed:

command: supabase --version
timeout: 30

Supabase CLI is installed by the supabase_cli module. If missing, reinstall via manage_modules(action="install", name="supabase_cli").

---

Operations

1. List Projects

command: supabase projects list
timeout: 30

2. Link to Project

Link the current workspace to an existing Supabase project. The project ref is the unique ID found in your project's dashboard URL.

command: supabase link --project-ref PROJECT_REF
timeout: 30

3. Database Status

Inspect the linked database:

command: supabase inspect db info
timeout: 30

4. Run SQL Query

Execute a SQL query against the linked project:

command: supabase db execute "SELECT current_database(), current_user"
timeout: 60

For queries against a specific project (without linking):

command: supabase db execute --project-ref PROJECT_REF "SELECT ..."
timeout: 60

5. Pull Schema / Create Migration

Pull the current remote schema into a local migration file:

command: supabase db pull
timeout: 60

Generate a diff-based migration from local changes:

command: supabase db diff --use-migra -f MIGRATION_NAME
timeout: 60

6. Push Migrations

IMPORTANT: Confirm with the user before pushing migrations.

Push local migrations to the remote database:

command: supabase db push
timeout: 120

7. Generate TypeScript Types

Generate TypeScript types from the database schema:

command: supabase gen types typescript --project-ref PROJECT_REF
timeout: 60

8. Inspect Queries

View long-running queries:

command: supabase inspect db long-running-queries
timeout: 30

View most frequently called queries:

command: supabase inspect db calls
timeout: 30

View table sizes:

command: supabase inspect db table-sizes
timeout: 30

9. Deploy Edge Functions

IMPORTANT: Confirm with the user before deploying.

Deploy an edge function:

command: supabase functions deploy FUNCTION_NAME
timeout: 120

List deployed functions:

command: supabase functions list
timeout: 30

10. Manage Secrets

List all secrets:

command: supabase secrets list
timeout: 30

Set a secret:

IMPORTANT: Confirm with the user before modifying secrets.

command: supabase secrets set KEY=VALUE
timeout: 30

For multiple secrets:

command: supabase secrets set KEY1=VALUE1 KEY2=VALUE2
timeout: 30

11. Storage Operations

List files in a storage bucket:

command: supabase storage ls ss:///BUCKET_NAME
timeout: 30

Copy a file to storage:

command: supabase storage cp LOCAL_FILE ss:///BUCKET_NAME/PATH
timeout: 60

12. Create New Project

Create a new Supabase project. This is a multi-step workflow.

IMPORTANT: Confirm the project name, organization, region, and database password with the user before proceeding.

Step 1: Define the tasks

Call define_tasks with all steps upfront so progress is tracked:

{"tool": "define_tasks", "tasks": [
  "TASK 1 — List organizations: get available orgs to create project under. See supabase skill 'Step 2'.",
  "TASK 2 — Create project: create a new Supabase project. See supabase skill 'Step 3'.",
  "TASK 3 — Link project: link the workspace to the new project. See supabase skill 'Step 4'.",
  "TASK 4 — Configure secrets: set environment variables / secrets. See supabase skill 'Step 5'.",
  "TASK 5 — Verify project: confirm project is ready and accessible. See supabase skill 'Step 6'."
]}

Step 2: List organizations

command: supabase orgs list
timeout: 30

Step 3: Create the project

command: supabase projects create PROJECT_NAME --org-id ORG_ID --db-password DB_PASSWORD --region REGION
timeout: 120

Common regions: us-east-1, us-west-1, eu-west-1, ap-southeast-1.

Step 4: Link to the new project

command: supabase link --project-ref PROJECT_REF
timeout: 30

Step 5: Set secrets (if needed)

Use operation #10 to set any secrets the project needs.

Step 6: Verify project

command: supabase projects list
timeout: 30

Then inspect the database:

command: supabase inspect db info
timeout: 30

---

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Unauthorized | Token is invalid/expired | Regenerate PAT at https://supabase.com/dashboard/account/tokens | | Cannot find linked project | No project linked in current directory | Use supabase link --project-ref REF first | | Permission denied | Token lacks access to the project | Verify token owner has access to the project/org | | Migration conflict | Remote has changes not in local | Run supabase db pull first, then resolve conflicts | | Function deploy failed | Build error in edge function | Check function code for syntax errors | | supabase: command not found | CLI not installed | Report to admin — should be pre-installed in Docker |

---

Typical Workflow

1. Verify auth — supabase projects list
2. Link to project — supabase link --project-ref REF
3. Check database — supabase inspect db info
4. Take action — run queries, push migrations, deploy functions (confirm with user first)

---

Best Practices

1. Always verify auth first before running other commands
2. Link before acting — use supabase link so commands target the right project
3. Confirm mutations — always ask the user before pushing migrations, deploying functions, or modifying secrets
4. Pull before push — run supabase db pull before supabase db push to avoid conflicts
5. Be careful with secrets — they may contain sensitive values, don't log them unnecessarily
6. Use --project-ref for one-off commands against a specific project without linking