Back to Details

supabase

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Supabase Database Operations

Supabase 数据库操作

Execute database operations on Supabase: queries, writes, migrations, and diagnostics.
MCP is optional. This skill works with MCP (auto), Supabase CLI, psql, or Dashboard. See BACKENDS.md for execution options.
在Supabase上执行数据库操作：查询、写入、迁移和诊断。
MCP为可选配置。 本技能可与MCP（自动）、Supabase CLI、psql或控制台配合使用。有关执行选项，请参阅BACKENDS.md。

Scope

适用范围

Applies to:
  • Database actions on Supabase: query/statistics/export, write (after confirmation), migration (DDL), type generation, query logs/advisors
Does not apply to:
  • Project-side integration (env/client code/data access layer)
    → Use 
    workflow-ship-faster
    (Step 6) for project setup; this skill handles DB-side actions only
Called by:
  • workflow-ship-faster
    uses this skill as DB operation foundation
适用场景：
  • Supabase数据库操作：查询/统计/导出、写入（需确认后执行）、迁移（DDL）、类型生成、查询日志/建议器
不适用场景：
  • 项目侧集成（环境/客户端代码/数据访问层）
    → 项目设置请使用
    workflow-ship-faster
    （步骤6）；本技能仅处理数据库端操作
调用方式：
  • workflow-ship-faster
    将本技能作为数据库操作的基础组件调用

Postgres Best Practices (Built-in)

内置Postgres最佳实践

Ship Faster vendors Supabase's Postgres best practices under 
references/postgres-best-practices/
.
Consult it when:
  • Writing/reviewing/optimizing SQL queries
  • Designing indexes, schema changes, or RLS policies
  • Diagnosing performance, locking, or connection issues
Source of truth:
  • Full guide: 
    references/postgres-best-practices/AGENTS.md
  • Individual rules: 
    references/postgres-best-practices/rules/*.md
When proposing changes, cite the relevant rule file path (for example: 
references/postgres-best-practices/rules/query-missing-indexes.md
) and keep changes minimal.
Ship Faster 在
references/postgres-best-practices/
目录下提供了Supabase的Postgres最佳实践。
以下场景请参考该指南：
  • 编写/审核/优化SQL查询
  • 设计索引、架构变更或RLS策略
  • 诊断性能、锁或连接问题
权威来源：
  • 完整指南：
    references/postgres-best-practices/AGENTS.md
  • 独立规则：
    references/postgres-best-practices/rules/*.md
提出变更建议时，请引用相关规则文件路径（例如：
references/postgres-best-practices/rules/query-missing-indexes.md
），并尽量保持变更最小化。

Security Rules (Must Follow)

安全规则（必须遵守）

  1. Read first: Always check schema before any operation
  2. Default LIMIT 50: All SELECT queries default to 
    LIMIT 50
    , unless user explicitly requests more
  3. Write operation confirmation: INSERT/UPDATE/DELETE must before execution:
    • Display the SQL to be executed
    • State expected number of affected rows
    • Await explicit user confirmation
  4. No bare writes: UPDATE/DELETE without WHERE condition → refuse directly, do not execute
  5. Batch threshold: Affecting > 100 rows → force double confirmation + suggest 
    SELECT count(*)
    first
  6. DDL via migration: Schema changes must use migrations, not direct DDL
  7. Production environment: Write disabled by default; only allow when user explicitly says "execute on prod" and double confirms
  8. Sensitive fields: email/phone/token/password are masked or not returned by default, unless user explicitly requests
  1. 先读取：执行任何操作前务必检查数据库架构
  2. 默认LIMIT 50：所有SELECT查询默认使用
    LIMIT 50
    ，除非用户明确要求更多结果
  3. 写入操作需确认：INSERT/UPDATE/DELETE操作执行前必须：
    • 展示待执行的SQL语句
    • 说明预计影响的行数
    • 等待用户明确确认
  4. 禁止无限制写入：直接拒绝执行不带WHERE条件的UPDATE/DELETE操作
  5. 批量操作阈值：影响行数>100时→强制二次确认 + 建议先执行
    SELECT count(*)
  6. 通过迁移执行DDL：架构变更必须使用迁移，而非直接执行DDL
  7. 生产环境限制：默认禁用写入操作；仅当用户明确说明“在生产环境执行”并二次确认后才允许
  8. 敏感字段处理：默认屏蔽或不返回email/phone/token/password等敏感字段，除非用户明确要求

Operation Flow

操作流程

1. Parse requirements → restate objective
2. Unsure about tables/fields → first query schema (information_schema or list_tables)
3. Plan SQL → present to user
4. Read-only → execute directly
5. Write operation → confirm before execution → verify affected rows → report result
1. 解析需求 → 重述目标
2. 若对表/字段不明确 → 先查询架构（information_schema或list_tables）
3. 规划SQL → 提交给用户
4. 只读操作 → 直接执行
5. 写入操作 → 确认后执行 → 验证影响行数 → 报告结果

File-based Pipeline

基于文件的流水线

When integrating into multi-step workflows, persist artifacts to disk:
runs/<workflow>/active/<run_id>/
├── proposal.md                # Requirements / objective
├── context.json               # Known tables/fields/IDs
├── tasks.md                   # Checklist + approval gate
├── evidence/sql.md            # SQL to execute (write ops written here first)
├── evidence/result.md         # Conclusion + SQL + results
└── logs/events.jsonl          # Optional tool call summary (no sensitive data)
集成到多步骤工作流时，请将工件持久化到磁盘：
runs/<workflow>/active/<run_id>/
├── proposal.md                # 需求/目标
├── context.json               # 已知表/字段/ID
├── tasks.md                   # 检查清单 + 审批节点
├── evidence/sql.md            # 待执行SQL（写入操作先写入此文件）
├── evidence/result.md         # 结论 + SQL + 结果
└── logs/events.jsonl          # 可选工具调用摘要（无敏感数据）

Output Format

输出格式

  • Language: English
  • Structure: Conclusion → Key numbers → Executed SQL → Result table (max 50 rows)
  • Overflow handling: Truncate + show total count + optional export/pagination
Example:
✅ 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    |
| ...        | ...   |
  • 语言：英文
  • 结构：结论 → 关键数据 → 执行的SQL → 结果表（最多50行）
  • 溢出处理：截断结果 + 显示总行数 + 可选导出/分页
示例：
✅ 查询完成：过去7天新增142位用户

执行的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

错误处理

SituationAction
SQL syntax errorReturn error summary + fix suggestions
Insufficient permissionsExplain required permissions + alternatives
No data returnedExplain possible reasons (conditions too strict? data doesn't exist?)
RLS blockedSuggest checking RLS policy or using service_role
场景操作
SQL语法错误返回错误摘要 + 修复建议
权限不足说明所需权限 + 替代方案
无数据返回解释可能原因（条件过严？数据不存在？）
RLS拦截建议检查RLS策略或使用service_role

Example Workflows

示例工作流

Read: Simple Query

只读：简单查询

User: Get registered user count for the last 7 days, by day

1. Confirm table user_profiles, field created_at
2. Execute aggregation SQL
3. Return: conclusion + numbers + SQL + table
用户：获取过去7天每天的注册用户数

1. 确认表user_profiles和字段created_at
2. 执行聚合SQL
3. 返回：结论 + 数据 + SQL + 结果表

Read: Complex Query

只读：复杂查询

User: Find projects that have runs but all failed

1. Confirm projects, runs tables and status field
2. Present JOIN + aggregation SQL
3. Execute and return results (mask email)
用户：找出有运行记录但全部失败的项目

1. 确认projects、runs表和status字段
2. 提交JOIN + 聚合SQL
3. 执行并返回结果（屏蔽email）

Write: Insert

写入：插入

User: Create a new run for project xxx

1. First check if project exists
2. Present INSERT SQL + expected impact: 1 row
3. Await confirmation → execute → return new record id
用户：为项目xxx创建一条新的运行记录

1. 先检查项目是否存在
2. 提交INSERT SQL + 预计影响：1行
3. 等待确认 → 执行 → 返回新记录ID

Write: Update

写入：更新

User: Change run abc's status to completed

1. First SELECT to verify current state
2. Present UPDATE SQL + WHERE id = 'abc'
3. Confirm → execute → SELECT again to verify
用户：将运行记录abc的状态改为已完成

1. 先执行SELECT验证当前状态
2. 提交带WHERE id = 'abc'的UPDATE SQL
3. 确认 → 执行 → 再次SELECT验证

Dangerous: Delete

高危操作：删除

User: Delete all runs where status = 'failed'

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
用户：删除所有状态为失败的运行记录

1. 先执行SELECT count(*) WHERE status = 'failed'
2. 提交统计数 + DELETE SQL
3. 若行数>100，强制二次确认
4. 确认后执行 → 报告删除行数

Dangerous: DELETE without WHERE

高危操作：无WHERE条件的DELETE

User: Clear the runs table

❌ Refuse to execute
→ Prompt: DELETE without WHERE condition, this will delete all data
→ Suggest: Use TRUNCATE (requires migration) or add explicit condition
用户：清空runs表

❌ 拒绝执行
→ 提示：不带WHERE条件的DELETE会删除所有数据
→ 建议：使用TRUNCATE（需通过迁移）或添加明确条件

Schema Discovery

架构发现

Get latest schema at runtime:
sql
-- 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 = '<table_name>';
For project-specific schema (may be outdated), see schema.md.
运行时获取最新架构：
sql
-- 列出所有表
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public';

-- 查看表结构
SELECT column_name, data_type, is_nullable 
FROM information_schema.columns 
WHERE table_name = '<table_name>';
项目特定架构（可能已过时）请参阅schema.md。

Related Files

相关文件

  • BACKENDS.md — Execution options (MCP/CLI/Console)
  • SETUP.md — MCP configuration (optional)
  • schema.md — Project-specific schema reference
  • BACKENDS.md — 执行选项（MCP/CLI/控制台）
  • SETUP.md — MCP配置（可选）
  • schema.md — 项目特定架构参考