Interact with Supabase database via MCP tools, execute queries, writes, migrations, and diagnostics.
Scope
Applies to:
Need to perform "database actions" on Supabase: query/statistics/export, write (after confirmation), migration (DDL), type generation, query logs/advisors
Does not apply to:
Need to complete "integration implementation" in Next.js project (env/client code/minimal data access layer/project structure)
→ Use
workflow-ship-faster
(Step 6: Supabase integration) for project-side setup; this skill only handles DB-side actions and gates
Called by:
workflow-ship-faster
uses this skill as DB operation foundation;
workflow-ship-faster
handles project-side integration, this skill handles DB-side actions and security gates
Postgres Best Practices (Bundled)
Ship Faster vendors Supabase's Postgres best practices inside the
supabase
skill (install
supabase
alongside this skill if you want these references available locally):
When integrating database operations into multi-step workflows, persist all context and artifacts to disk, passing only paths between agents/sub-agents.
Recommended directory structure (within project):
runs//active//
Input:
01-input/goal.md
(requirements),
01-input/context.json
(known tables/fields/IDs)
Plan:
03-plans/sql.md
(SQL to execute; write operations must be written here before confirmation)
Truncate + show total count + optional export/pagination
Example output:
✅ Query complete: 142 new users in the last 7 days
Executed SQL:
SELECT DATE(created_at) as date, COUNT() as count
FROM user_profiles
WHERE created_at > NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at) ORDER BY date DESC;
| date | count |
|------------|-------|
| 2025-01-09 | 23 |
| 2025-01-08 | 31 |
| ... | ... |
Error Handling
Situation
Action
SQL syntax error
Return error summary + fix suggestions
Insufficient permissions
Explain required permissions + alternatives
No data returned
Explain possible reasons (conditions too strict? data doesn't exist?)
RLS blocked
Suggest checking RLS policy or using service_role
Example Dialogues
Read: Simple Query
User: Get registered user count for the last 7 days, by day
Execution:
1. Confirm table user_profiles, field created_at
2. Execute aggregation SQL
3. Return: conclusion + numbers + SQL + table
Read: Complex Query
User: Find projects that have runs but all failed
Execution:
1. Confirm projects, runs tables and status field
2. Present JOIN + aggregation SQL
3. Execute and return results (mask email)
Write: Insert
User: Create a new run for project xxx
Execution:
1. First check if project exists
2. Present INSERT SQL + expected impact: 1 row
3. Await confirmation → execute → return new record id
Write: Update
User: Change run abc's status to completed
Execution:
1. First SELECT to verify current state
2. Present UPDATE SQL + WHERE id = 'abc'
3. Confirm → execute → SELECT again to verify
Dangerous: Delete
User: Delete all runs where status = 'failed'
Execution:
1. First SELECT count() WHERE status = 'failed'
2. Present count + DELETE SQL
3. If > 100 rows, force double confirmation
4. After confirmation execute → report deleted row count
Dangerous: DELETE without WHERE
User: Clear the runs table
Execution:
❌ Refuse to execute
→ Prompt: DELETE without WHERE condition, this will delete all data
→ Suggest: Use TRUNCATE (requires migration) or add explicit condition
Schema Reference
Get latest schema at runtime:
-- List all tables
SELECT
table_name
FROM
information_schema
.
tables
WHERE
table_schema
=
'public'
;
-- View table structure
SELECT
column_name
,
data_type
,
is_nullable
FROM
information_schema
.
columns
WHERE
table_name
=
''
;
For project-specific schema (may be outdated), see
schema.md
. Default to information_schema /
generate_typescript_types
as source of truth.