supabase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Supabase

Core Principles

核心原则

1. Supabase changes frequently — verify against current docs before implementing. Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions. Before implementing, look up the relevant topic using the documentation access methods below.

2. Verify your work. After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete.

3. Recover from errors, don't loop. If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding.

4. RLS by default in exposed schemas. Enable RLS on every table in any exposed schema, especially

public

. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API. For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same

auth.uid()

pattern.

5. Security checklist. When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities:

Auth and session security
- Never use
  user_metadata
  claims in JWT-based authorization decisions. In Supabase,
```
raw_user_meta_data
```
  is user-editable and can appear in
```
auth.jwt()
```
  , so it is unsafe for RLS policies or any other authorization logic. Store authorization data in
```
raw_app_meta_data
```
  /
```
app_metadata
```
  instead.
- Deleting a user does not invalidate existing access tokens. Sign out or revoke sessions first, keep JWT expiry short for sensitive apps, and for strict guarantees validate
```
session_id
```
  against
```
auth.sessions
```
  on sensitive operations.
- If you use
  app_metadata
  or
  auth.jwt()
  for authorization, remember JWT claims are not always fresh until the user's token is refreshed.
API key and client exposure
- Never expose the
  service_role
  or secret key in public clients. Prefer publishable keys for frontend code. Legacy
```
anon
```
  keys are only for compatibility. In Next.js, any
```
NEXT_PUBLIC_
```
  env var is sent to the browser.
RLS, views, and privileged database code
- Views bypass RLS by default. In Postgres 15 and above, use
```
CREATE VIEW ... WITH (security_invoker = true)
```
  . In older versions of Postgres, protect your views by revoking access from the
```
anon
```
  and
```
authenticated
```
  roles, or by putting them in an unexposed schema.
- UPDATE requires a SELECT policy. In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change.
- Do not put
  security definer
  functions in an exposed schema. Keep them in a private or otherwise unexposed schema.
Storage access control
- Storage upsert requires INSERT + SELECT + UPDATE. Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three.

For any security concern not covered above, fetch the Supabase product security index:

https://supabase.com/docs/guides/security/product-security.md

1. Supabase迭代非常频繁——实现前请对照当前官方文档验证。 不要依赖训练数据中的Supabase功能信息，函数签名、config.toml配置、API约定会随版本发生变化。实现功能前，请通过下文的文档访问方法查询相关主题。

2. 验证你的工作成果。 完成任何修复后，请运行测试查询确认变更生效，未经验证的修复是不完整的。

3. 从错误中恢复，不要循环重试。 如果某一方法尝试2-3次后仍然失败，请停下重新评估。尝试其他方案、查阅文档、仔细排查错误，如有相关日志请优先查看。重复执行相同命令通常无法解决Supabase问题，虽然答案不一定都在日志里，但操作前检查日志往往是值得的。

4. 暴露schema默认开启RLS。 所有暴露schema下的表都要启用RLS，尤其是

public

schema。这一点在Supabase中至关重要，因为暴露schema下的表可以通过Data API直接访问。私有schema也建议开启RLS作为深度防御。开启RLS后，要创建符合实际访问模型的策略，不要给所有表都默认套用相同的

auth.uid()

模板。

5. 安全检查清单 处理任何涉及auth、RLS、视图、存储、用户数据的Supabase任务时，请对照此清单检查。这些是Supabase特有的、容易悄悄产生安全漏洞的陷阱：

Auth与会话安全
- 永远不要在基于JWT的授权决策中使用
  user_metadata
  声明。在Supabase中，
```
raw_user_meta_data
```
  是用户可编辑的，会出现在
```
auth.jwt()
```
  返回结果中，因此不适合用于RLS策略或其他授权逻辑。请将授权数据存储在
```
raw_app_meta_data
```
  /
```
app_metadata
```
  中。
- 删除用户不会让现有访问令牌失效。 请先登出或撤销用户会话，敏感应用请将JWT有效期设短，对安全要求极高的场景下，执行敏感操作时需要对照
```
auth.sessions
```
  验证
```
session_id
```
  。
- 如果你使用
  app_metadata
  或
  auth.jwt()
  做授权，请记住在用户令牌刷新前，JWT声明不一定是最新的。
API密钥与客户端暴露
- 永远不要在公共客户端暴露
  service_role
  或密钥。前端代码请优先使用可发布密钥，旧版
```
anon
```
  密钥仅用于兼容场景。在Next.js中，所有
```
NEXT_PUBLIC_
```
  开头的环境变量都会被发送到浏览器端。
RLS、视图与高权限数据库代码
- 视图默认绕过RLS。 Postgres 15及以上版本请使用
```
CREATE VIEW ... WITH (security_invoker = true)
```
  创建视图。旧版本Postgres请通过撤销
```
anon
```
  和
```
authenticated
```
  角色的视图访问权限，或将视图放到未暴露的schema中来保障安全。
- UPDATE操作需要SELECT策略支持。 在Postgres RLS规则中，UPDATE需要先查询到目标行才能执行。如果没有对应的SELECT策略，更新操作会静默返回0行——没有报错，也不会产生任何变更。
- 不要将
  security definer
  函数放在暴露的schema中。请将这类函数存放在私有或其他未暴露的schema下。
存储访问控制
- 存储upsert操作需要INSERT + SELECT + UPDATE三个权限。 仅授予INSERT权限允许新文件上传，但文件替换（upsert）会静默失败，你需要同时授予三个权限。

如有上文未覆盖的安全问题，请查阅Supabase产品安全索引：

https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

Always discover commands via

--help

— never guess. The CLI structure changes between versions.

bash

supabase --help                    # All top-level commands
supabase <group> --help            # Subcommands (e.g., supabase db --help)
supabase <group> <command> --help  # Flags for a specific command

Supabase CLI Known gotchas:

```
supabase db query
```
requires CLI v2.79.0+ → use MCP
```
execute_sql
```
or
```
psql
```
as fallback
```
supabase db advisors
```
requires CLI v2.81.3+ → use MCP
```
get_advisors
```
as fallback
When you need a new migration SQL file, always create it with
```
supabase migration new <name>
```
first. Never invent a migration filename or rely on memory for the expected format.

Version check and upgrade: Run

supabase --version

to check. For CLI changelogs and version-specific features, consult the CLI documentation or GitHub releases.

永远通过

--help

查询命令用法——不要猜测。CLI结构会随版本发生变化。

bash

supabase --help                    # 所有顶层命令
supabase <group> --help            # 子命令（例如：supabase db --help）
supabase <group> <command> --help  # 特定命令的参数说明

Supabase CLI已知注意事项：

```
supabase db query
```
需要CLI v2.79.0及以上版本 → 低版本请使用MCP
```
execute_sql
```
或
```
psql
```
作为替代
```
supabase db advisors
```
需要CLI v2.81.3及以上版本 → 低版本请使用MCP
```
get_advisors
```
作为替代
当你需要新建迁移SQL文件时，必须先通过
```
supabase migration new <name>
```
创建。不要自定义迁移文件名，也不要凭记忆编写迁移文件格式。

版本检查与升级： 运行

supabase --version

查看当前版本。如需了解CLI变更日志和版本专属功能，请查阅CLI文档或GitHub releases。

Supabase MCP Server

Supabase MCP服务器

For setup instructions, server URL, and configuration, see the MCP setup guide.

Troubleshooting connection issues — follow these steps in order:

Check if the server is reachable:
```
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp
```
A
```
401
```
is expected (no token) and means the server is up. Timeout or "connection refused" means it may be down.
Check
.mcp.json
configuration: Verify the project root has a valid
```
.mcp.json
```
with the correct server URL. If missing, create one pointing to
```
https://mcp.supabase.com/mcp
```
.
Authenticate the MCP server: If the server is reachable and
```
.mcp.json
```
is correct but tools aren't visible, the user needs to authenticate. The Supabase MCP server uses OAuth 2.1 — tell the user to trigger the auth flow in their agent, complete it in the browser, and reload the session.

如需了解配置说明、服务器地址、参数设置，请查看MCP配置指南。

连接问题排查 —— 请按以下顺序操作：

检查服务器是否可达：
```
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp
```
返回
```
401
```
属于预期结果（无token），说明服务器正常运行。返回超时或「连接拒绝」说明服务器可能已宕机。
检查
.mcp.json
配置：确认项目根目录下存在有效的
```
.mcp.json
```
文件，且服务器地址配置正确。如果文件不存在，请创建文件并配置地址为
```
https://mcp.supabase.com/mcp
```
。
认证MCP服务器： 如果服务器可达且
```
.mcp.json
```
配置正确，但工具仍无法正常显示，说明用户需要完成认证。Supabase MCP服务器使用OAuth 2.1协议——请告知用户在Agent中触发认证流程，在浏览器中完成认证后重载会话即可。

Supabase Documentation

Supabase文档

Before implementing any Supabase feature, find the relevant documentation. Use these methods in priority order:

MCP
search_docs
tool (preferred — returns relevant snippets directly)
Fetch docs pages as markdown — any docs page can be fetched by appending
```
.md
```
to the URL path.
Web search for Supabase-specific topics when you don't know which page to look at.

实现任何Supabase功能前，请先查找相关文档。请按以下优先级选择查询方式：

MCP
search_docs
工具（优先使用——可直接返回相关文档片段）
拉取markdown格式的文档页面 —— 任何文档页面的URL后追加
```
.md
```
即可获取markdown格式内容。
不清楚对应文档页面时，可通过网页搜索查询Supabase相关主题。

Making and Committing Schema Changes

创建与提交Schema变更

To make schema changes, use
execute_sql
(MCP) or
supabase db query
(CLI). These run SQL directly on the database without creating migration history entries, so you can iterate freely and generate a clean migration when ready.

Do NOT use

apply_migration

to change a local database schema — it writes a migration history entry on every call, which means you can't iterate, and

supabase db diff

supabase db pull

will produce empty or conflicting diffs. If you use it, you'll be stuck with whatever SQL you passed on the first try.

When ready to commit your changes to a migration file:

Run advisors →
```
supabase db advisors
```
(CLI v2.81.3+) or MCP
```
get_advisors
```
. Fix any issues.
Review the Security Checklist above if your changes involve views, functions, triggers, or storage.

Generate the migration →

supabase db pull <descriptive-name> --local --yes

Verify →
```
supabase migration list --local
```

如需修改Schema，请使用
execute_sql
（MCP）或
supabase db query
（CLI）。这两个工具会直接在数据库运行SQL，不会创建迁移历史记录，因此你可以自由迭代，最终准备就绪后生成干净的迁移文件。

不要使用

apply_migration

修改本地数据库Schema——该命令每次调用都会写入一条迁移历史记录，导致你无法迭代修改，后续执行

supabase db diff

supabase db pull

会生成空的或冲突的diff。如果使用了该命令，你只能保留第一次传入的SQL内容，无法再调整。

准备好将变更提交到迁移文件时：

运行检查工具 →
```
supabase db advisors
```
（CLI v2.81.3+）或MCP
```
get_advisors
```
，修复所有问题。
如果变更涉及视图、函数、触发器或存储，请对照上文的安全检查清单核查。

生成迁移文件 →

supabase db pull <descriptive-name> --local --yes

验证迁移 →
```
supabase migration list --local
```

Reference Guides

参考指南

Skill Feedback → references/skill-feedback.md MUST read when the user reports that this skill gave incorrect guidance or is missing information.

技能反馈 → references/skill-feedback.md 当用户反馈本技能提供了错误指导或信息缺失时必须阅读此文档。