supabase-automation

通过 Rube MCP 自动化 Supabase

通过 Composio 的 Supabase 工具包自动执行 Supabase 操作，包括数据库查询、表结构检查、SQL 执行、项目和组织管理、存储桶、边缘函数以及服务健康监控。

前置条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Supabase 连接，工具包为 supabase
• 始终先调用 RUBE_SEARCH_TOOLS，获取当前工具架构

设置

获取 Rube MCP：在客户端配置中，将 https://rube.app/mcp 添加为 MCP 服务。完成客户端/服务端身份验证和明确授权的 Supabase 连接流程；仅有端点并不能建立访问权限。

1. 确认 RUBE_SEARCH_TOOLS 能正常响应，以验证 Rube MCP 可用
2. 使用工具包 supabase 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请根据返回的身份验证链接完成 Supabase 身份验证
4. 运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 查询和管理数据库表

适用场景：用户希望读取表中的数据、检查架构或执行 CRUD 操作

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 列出项目，找到目标 project_ref [前置条件]
2. SUPABASE_LIST_TABLES - 列出数据库中的所有表和视图 [前置条件]
3. SUPABASE_GET_TABLE_SCHEMAS - 获取详细的列类型、约束和关系 [写入操作的前置条件]
4. SUPABASE_SELECT_FROM_TABLE - 使用筛选、排序和分页查询行 [读取操作必需]
5. SUPABASE_BETA_RUN_SQL_QUERY - 执行任意 SQL，以处理复杂查询、插入、更新或删除 [写入操作必需]

SELECT_FROM_TABLE 的关键参数：

• project_ref：20 个字符的小写项目引用
• table：要查询的表名或视图名
• select：以逗号分隔的列名列表（支持嵌套选择和 JSON 路径，例如 profile->avatar_url）
• filters：筛选对象数组，包含 column、operator、value
• order：排序表达式，例如 created_at.desc
• limit：要返回的最大行数（至少为 1）
• offset：分页时要跳过的行数

PostgREST 筛选运算符：

• eq、neq：等于 / 不等于
• gt、gte、lt、lte：比较运算符
• like、ilike：模式匹配（区分大小写 / 不区分大小写）
• is：IS 检查（用于 null、true、false）
• in：值列表中的成员
• cs、cd：包含 / 被包含（数组）
• fts、plfts、phfts、wfts：全文搜索变体

RUN_SQL_QUERY 的关键参数：

• ref：项目引用（20 个小写字母，模式为 ^[a-z]{20}$）
• query：有效的 PostgreSQL SQL 语句
• read_only：布尔值，用于强制使用只读事务（执行 SELECT 时更安全）

注意事项：

• project_ref 必须恰好由 20 个小写字母组成（仅限 a-z，不含数字或连字符）
• SELECT_FROM_TABLE 为只读；请使用可用且已授权的写入工具；SQL 是一种可选方式
• 对于 PostgreSQL 数组列（text[]、integer[]），请使用 ARRAY['item1', 'item2'] 或 '{"item1", "item2"}' 语法，切勿使用 JSON 数组语法 '["item1", "item2"]'
• 查询中区分大小写的 SQL 标识符必须用双引号括起来
• 复杂的 DDL 操作可能会超时（限制约为 60 秒）；请拆分为较小的查询
• ERROR 42P01 可能表示数据库/架构/search_path 错误、关系不存在或引号不匹配
• ERROR 42883“function does not exist”表示调用了非标准辅助函数；优先使用 information_schema 查询

2. 管理项目和组织

使用时机：用户想要列出项目、检查配置或管理组织

工具调用顺序：

1. SUPABASE_LIST_ALL_ORGANIZATIONS - 列出所有组织（ID 和名称）[必需]
2. SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION - 根据 slug 获取组织详细信息 [可选]
3. SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION - 列出组织成员及其角色和 MFA 状态 [可选]
4. SUPABASE_LIST_ALL_PROJECTS - 列出所有项目及其元数据 [必需]
5. SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG - 获取数据库配置 [可选]
6. SUPABASE_GETS_PROJECT_S_AUTH_CONFIG - 获取身份验证配置 [可选]
7. SUPABASE_GET_PROJECT_API_KEYS - 获取 API 密钥（敏感信息——谨慎处理）[可选]
8. SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS - 检查服务健康状态 [可选]

关键参数：

• ref：项目专用工具所需的项目引用
• slug：组织工具所需的组织 slug（适用于 URL 的标识符）
• services：用于健康检查的服务数组：auth、db、db_postgres_user、pg_bouncer、pooler、realtime、rest、storage

注意事项：

• LIST_ALL_ORGANIZATIONS 返回 id 和 slug；LIST_MEMBERS_OF_AN_ORGANIZATION 需要 slug，而不是 id
• GET_PROJECT_API_KEYS 会返回正在使用的密钥——绝不要记录、显示或持久化完整的密钥值
• GETS_PROJECT_S_SERVICE_HEALTH_STATUS 需要非空的 services 数组；空数组会导致 invalid_request 错误
• 如果令牌缺少必需的作用域，配置工具可能会返回 401/403；应妥善处理，而不是导致整个工作流失败

3. 检查数据库架构

使用时机：用户想要了解表结构、列、约束或生成类型

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找目标项目 [前置条件]
2. SUPABASE_LIST_TABLES - 列出所有表和视图及其元数据 [必需]
3. SUPABASE_GET_TABLE_SCHEMAS - 获取指定表的详细架构 [必需]
4. SUPABASE_GENERATE_TYPE_SCRIPT_TYPES - 根据架构生成 TypeScript 类型 [可选]

LIST_TABLES 的关键参数：

• project_ref：项目引用
• schemas：要搜索的架构名称数组（例如 ["public"]）；省略则搜索所有非系统架构
• include_views：是否在表之外包含视图（默认值为 true）
• include_metadata：是否包含行数估算和大小（默认值为 true）
• include_system_schemas：是否包含 pg_catalog、information_schema 等（默认值为 false）

GET_TABLE_SCHEMAS 的关键参数：

• project_ref：项目引用
• table_names：表名数组（每次请求最多 20 个）；支持 public.users、auth.users 这样的架构前缀
• include_relationships：是否包含外键信息（默认值为 true）
• include_indexes：是否包含索引信息（默认值为 true）
• exclude_null_values：隐藏 null 字段以简化输出（默认值为 true）

GENERATE_TYPE_SCRIPT_TYPES 的关键参数：

• ref：项目引用
• included_schemas：以逗号分隔的架构名称（默认值为 "public"）

注意事项：

• 不带架构前缀的表名默认使用 public 架构
• LIST_TABLES 返回的 row_count 和 size_bytes 对于视图或最近创建的表可能为 null；应视为未知，而非零
• GET_TABLE_SCHEMAS 每次请求最多处理 20 个表；必要时分批请求
• TypeScript 类型包含指定架构中的所有表；无法筛选单个表

4. 管理 Edge Functions

适用场景：用户想要列出、检查或使用 Supabase Edge Functions

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找项目引用 [前置条件]
2. SUPABASE_LIST_ALL_FUNCTIONS - 列出所有 Edge Function 及其元数据 [必需]
3. SUPABASE_RETRIEVE_A_FUNCTION - 获取特定函数的详细信息 [可选]

关键参数：

• ref：项目引用
• RETRIEVE_A_FUNCTION 的函数 slug

注意事项：

• LIST_ALL_FUNCTIONS 仅返回元数据，不包含函数代码或日志
• created_at 和 updated_at 可能是 Unix 毫秒时间戳；请将其转换为人类可读的时间戳
• 这些工具无法创建或部署 Edge Function；它们只是只读检查工具
• 如果没有组织/项目管理员权限，可能会出现权限错误

5. 管理存储桶

适用场景：用户想要列出存储桶或管理文件存储

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找项目引用 [前置条件]
2. SUPABASE_LISTS_ALL_BUCKETS - 列出所有存储桶 [必需]

关键参数：

• ref：项目引用

注意事项：

• LISTS_ALL_BUCKETS 仅返回存储桶列表，不包含存储桶内容或访问策略
• 对于文件上传，SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID 仅处理 TUS 可恢复上传的 CORS 预检
• 只能在相同的授权范围内使用有文档记录且可用的存储工具/API；不要虚构代理工具

常见模式

ID 解析

• 项目引用：SUPABASE_LIST_ALL_PROJECTS -- 提取 ref 字段（20 个小写字母）
• 组织 slug：SUPABASE_LIST_ALL_ORGANIZATIONS -- 下游组织工具应使用 slug（而非 id）
• 表名：SUPABASE_LIST_TABLES -- 查询前先枚举可用表
• 架构发现：SUPABASE_GET_TABLE_SCHEMAS -- 写入前检查列和约束

分页

• SUPABASE_SELECT_FROM_TABLE：使用 offset + limit 分页。每次将 offset 增加 limit，直到返回的行数少于 limit。
• SUPABASE_LIST_ALL_PROJECTS：大型账户可能需要分页；请按照游标/页码逐页获取，直至全部获取完毕。
• SUPABASE_LIST_TABLES：大型数据库可能需要分页。

SQL 最佳实践

• 编写 SQL 前，务必使用 SUPABASE_GET_TABLE_SCHEMAS 或 SUPABASE_LIST_TABLES
• 使用 read_only: true 执行 SELECT 查询，避免意外修改数据
• 对区分大小写的标识符加引号：使用 SELECT * FROM "MyTable"，而非 SELECT * FROM MyTable
• 数组列使用 PostgreSQL 数组语法：ARRAY['a', 'b']，而非 ['a', 'b']
• 将复杂的 DDL 拆分为较小的语句，以避免超时

已知问题

ID 格式

• 项目引用恰好由 20 个小写字母（a-z）组成：模式为 ^[a-z]{20}$
• 组织标识符有两种形式：id（UUID）和 slug（适用于 URL 的字符串）；不同工具接受的形式可能不同
• LIST_MEMBERS_OF_AN_ORGANIZATION 要求使用 slug，而非 id

SQL 执行

• 复杂操作中，BETA_RUN_SQL_QUERY 的超时时间约为 60 秒
• 必须使用 PostgreSQL 数组语法：ARRAY['item'] 或 '{"item"}'，不能使用 JSON 语法 '["item"]'
• 在 SQL 中，区分大小写的标识符必须用双引号括起来
• ERROR 42P01：关系不存在（请检查引号和架构前缀）
• ERROR 42883：函数不存在（请使用 information_schema，而非自定义辅助函数）

敏感数据

• GET_PROJECT_API_KEYS 会返回服务角色密钥——绝不要暴露完整值
• Auth 配置工具会排除密钥，但仍可能包含敏感配置
• 输出 API 密钥时，务必遮盖或截断

架构元数据

• LIST_TABLES 中的 row_count 和 size_bytes 可能为 null；不要将其视为零
• 默认情况下会排除系统架构；设置 include_system_schemas: true 可查看这些架构
• 除非设置 include_views: false，否则视图会与表一同显示

速率限制和权限

• 丰富数据的工具（API 密钥、配置）可能会因缺少适当的作用域而返回 401/403；请妥善跳过
• 大型表列表可能需要分页
• GETS_PROJECT_S_SERVICE_HEALTH_STATUS 在 services 数组为空时会失败——请务必至少指定一项服务

快速参考

任务	工具 Slug	关键参数
列出组织	SUPABASE_LIST_ALL_ORGANIZATIONS	（无）
获取组织信息	SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION	slug
列出组织成员	SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION	slug
列出项目	SUPABASE_LIST_ALL_PROJECTS	（无）
列出表	SUPABASE_LIST_TABLES	project_ref、schemas
获取表架构	SUPABASE_GET_TABLE_SCHEMAS	project_ref、table_names
查询表	SUPABASE_SELECT_FROM_TABLE	project_ref、table、select、filters
运行 SQL	SUPABASE_BETA_RUN_SQL_QUERY	ref、query、read_only
生成 TS 类型	SUPABASE_GENERATE_TYPE_SCRIPT_TYPES	ref、included_schemas
Postgres 配置	SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG	ref
Auth 配置	SUPABASE_GETS_PROJECT_S_AUTH_CONFIG	ref
获取 API 密钥	SUPABASE_GET_PROJECT_API_KEYS	ref
服务健康状态	SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS	ref、services
列出边缘函数	SUPABASE_LIST_ALL_FUNCTIONS	ref
获取边缘函数	SUPABASE_RETRIEVE_A_FUNCTION	ref、函数 slug
列出存储桶	SUPABASE_LISTS_ALL_BUCKETS	ref
列出数据库分支	SUPABASE_LIST_ALL_DATABASE_BRANCHES	ref

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

示例

用户请求：

通过 Rube MCP（Composio）自动执行 Supabase 数据库查询、表管理、项目管理、存储、边缘函数和 SQL。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。

上述工具名称、架构、标识符限制和限额描述的是历史连接器快照。当前发现结果优先；请保留返回的标识符，不要根据显示名称推导标识符。架构检查不代表获准执行写入、获取密钥、批量导出个人数据或更改身份验证。管理 SQL 可能以特权访问权限运行并绕过应用程序 RLS：请限制项目、架构和行的范围，并对值进行参数化。只读事务仍可能开销很大；请限制查询范围，并在执行 DDL 前检查锁。不要仅为避免超时而拆分原子迁移，除非已有恢复计划。使用稳定的唯一排序进行偏移分页，并说明并发变更带来的限制。不要重放结果未知的写入操作。