supabase-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Supabase Best Practices

Supabase 最佳实践

Comprehensive security and performance optimization guide for Supabase applications with Clerk authentication integration. Contains 40+ rules across 10 categories, prioritized by impact to guide secure development and code review.

集成Clerk身份验证的Supabase应用程序全面安全与性能优化指南。涵盖10个类别共40+条规则，按影响优先级排序，指导安全开发与代码审查。

When to Apply

适用场景

Reference these guidelines when:

Setting up a new Supabase project
Integrating Clerk authentication with Supabase
Writing Row Level Security (RLS) policies
Designing database schemas
Implementing real-time features
Configuring Storage buckets
Writing Edge Functions
Reviewing code for security issues

在以下场景中参考本指南：

搭建新的Supabase项目
将Clerk身份验证与Supabase集成
编写行级安全（Row Level Security, RLS）策略
设计数据库架构
实现实时功能
配置存储桶
编写Edge Functions
审查代码中的安全问题

Rule Categories by Priority

按优先级划分的规则类别


rls-
clerk-
db-
auth-
api-
storage-
realtime-
edge-
test-
security-

Priority	Category	Impact	Prefix
1	Row Level Security	CRITICAL	`rls-`
2	Clerk Integration	CRITICAL	`clerk-`
3	Database Security	HIGH	`db-`
4	Authentication Patterns	HIGH	`auth-`
5	API Security	HIGH	`api-`
6	Storage Security	MEDIUM-HIGH	`storage-`
7	Realtime Security	MEDIUM	`realtime-`
8	Edge Functions	MEDIUM	`edge-`
9	Testing	MEDIUM	`test-`
10	Security	MEDIUM	`security-`


rls-
clerk-
db-
auth-
api-
storage-
realtime-
edge-
test-
security-

优先级	类别	影响程度	前缀
1	行级安全（Row Level Security）	关键（CRITICAL）	`rls-`
2	Clerk集成	关键（CRITICAL）	`clerk-`
3	数据库安全	高（HIGH）	`db-`
4	认证模式	高（HIGH）	`auth-`
5	API安全	高（HIGH）	`api-`
6	存储安全	中高（MEDIUM-HIGH）	`storage-`
7	实时安全	中（MEDIUM）	`realtime-`
8	Edge Functions	中（MEDIUM）	`edge-`
9	测试	中（MEDIUM）	`test-`
10	安全	中（MEDIUM）	`security-`

Quick Reference

快速参考

1. Row Level Security (CRITICAL)

1. 行级安全（关键）

```
rls-always-enable
```
- Always enable RLS on public schema tables
```
rls-wrap-functions-select
```
- Wrap auth functions with (SELECT ...) for performance
```
rls-add-indexes
```
- Add indexes on columns used in RLS policies
```
rls-specify-roles
```
- Specify roles with TO authenticated clause
```
rls-security-definer
```
- Use SECURITY DEFINER functions for complex policies
```
rls-minimize-joins
```
- Minimize joins in RLS policies
```
rls-explicit-auth-check
```
- Use explicit auth.uid() checks
```
rls-restrictive-policies
```
- Use RESTRICTIVE policies for additional constraints

```
rls-always-enable
```
- 始终为公共架构表启用RLS
```
rls-wrap-functions-select
```
- 用(SELECT ...)包装认证函数以提升性能
```
rls-add-indexes
```
- 为RLS策略中使用的列添加索引
```
rls-specify-roles
```
- 通过TO authenticated子句指定角色
```
rls-security-definer
```
- 使用SECURITY DEFINER函数实现复杂策略
```
rls-minimize-joins
```
- 尽量减少RLS策略中的关联操作
```
rls-explicit-auth-check
```
- 使用显式的auth.uid()检查
```
rls-restrictive-policies
```
- 使用RESTRICTIVE策略添加额外约束

2. Clerk Integration (CRITICAL)

2. Clerk集成（关键）

```
clerk-setup-third-party
```
- Use Third-Party Auth integration (not JWT templates)
```
clerk-client-server-side
```
- Use accessToken callback for server-side clients
```
clerk-client-client-side
```
- Use useSession() hook for client-side clients
```
clerk-role-claim
```
- Configure role: authenticated claim in Clerk
```
clerk-org-policies
```
- Use organization claims for multi-tenant RLS
```
clerk-mfa-policies
```
- Enforce MFA with RESTRICTIVE policies
```
clerk-no-jwt-templates
```
- Never use deprecated JWT template integration

```
clerk-setup-third-party
```
- 使用第三方认证集成（而非JWT模板）
```
clerk-client-server-side
```
- 为服务器端客户端使用accessToken回调
```
clerk-client-client-side
```
- 为客户端使用useSession()钩子
```
clerk-role-claim
```
- 在Clerk中配置role: authenticated声明
```
clerk-org-policies
```
- 使用组织声明实现多租户RLS
```
clerk-mfa-policies
```
- 通过RESTRICTIVE策略强制启用MFA
```
clerk-no-jwt-templates
```
- 切勿使用已弃用的JWT模板集成

3. Database Security (HIGH)

3. 数据库安全（高）

```
db-migrations-versioned
```
- Use versioned migrations for schema changes
```
db-schema-design
```
- Follow proper schema design patterns
```
db-indexes-strategy
```
- Implement proper indexing strategy
```
db-foreign-keys
```
- Always use foreign key constraints
```
db-triggers-security
```
- Secure trigger functions properly
```
db-views-security-invoker
```
- Use SECURITY INVOKER for views

```
db-migrations-versioned
```
- 使用版本化迁移管理架构变更
```
db-schema-design
```
- 遵循正确的架构设计模式
```
db-indexes-strategy
```
- 实施合理的索引策略
```
db-foreign-keys
```
- 始终使用外键约束
```
db-triggers-security
```
- 妥善保护触发器函数
```
db-views-security-invoker
```
- 为视图使用SECURITY INVOKER

4. Authentication Patterns (HIGH)

4. 认证模式（高）

```
auth-jwt-claims-validation
```
- Always validate JWT claims
```
auth-user-metadata-safety
```
- Treat user_metadata as untrusted
```
auth-app-metadata-authorization
```
- Use app_metadata for authorization
```
auth-session-management
```
- Implement proper session management

```
auth-jwt-claims-validation
```
- 始终验证JWT声明
```
auth-user-metadata-safety
```
- 将user_metadata视为不可信数据
```
auth-app-metadata-authorization
```
- 使用app_metadata进行授权
```
auth-session-management
```
- 实施合理的会话管理

5. API Security (HIGH)

5. API安全（高）

```
api-filter-queries
```
- Always filter queries even with RLS
```
api-publishable-keys
```
- Use publishable keys correctly
```
api-service-role-server-only
```
- Never expose service role key to client

```
api-filter-queries
```
- 即使启用RLS也始终过滤查询
```
api-publishable-keys
```
- 正确使用可发布密钥
```
api-service-role-server-only
```
- 切勿向客户端暴露服务角色密钥

6. Storage Security (MEDIUM-HIGH)

6. 存储安全（中高）

```
storage-rls-policies
```
- Enable RLS on storage.objects
```
storage-bucket-security
```
- Configure bucket-level security
```
storage-signed-urls
```
- Use signed URLs for private files

```
storage-rls-policies
```
- 为storage.objects启用RLS
```
storage-bucket-security
```
- 配置桶级安全
```
storage-signed-urls
```
- 为私有文件使用签名URL

7. Realtime Security (MEDIUM)

7. 实时安全（中）

```
realtime-private-channels
```
- Use private channels for sensitive data
```
realtime-rls-authorization
```
- RLS policies apply to realtime
```
realtime-cleanup-subscriptions
```
- Clean up subscriptions on unmount

```
realtime-private-channels
```
- 为敏感数据使用私有频道
```
realtime-rls-authorization
```
- RLS策略适用于实时功能
```
realtime-cleanup-subscriptions
```
- 在卸载时清理订阅

8. Edge Functions (MEDIUM)

8. Edge Functions（中）

```
edge-verify-jwt
```
- Always verify JWT in edge functions
```
edge-cors-handling
```
- Handle CORS properly
```
edge-secrets-management
```
- Use secrets for sensitive data

```
edge-verify-jwt
```
- 始终在Edge Functions中验证JWT
```
edge-cors-handling
```
- 妥善处理CORS
```
edge-secrets-management
```
- 使用密钥管理敏感数据

9. Testing (MEDIUM)

9. 测试（中）

```
test-pgtap-rls
```
- Test RLS policies with pgTAP
```
test-isolation
```
- Isolate tests properly
```
test-helpers
```
- Use test helper functions

```
test-pgtap-rls
```
- 使用pgTAP测试RLS策略
```
test-isolation
```
- 妥善隔离测试
```
test-helpers
```
- 使用测试辅助函数

10. Security (MEDIUM)

10. 安全（中）

```
security-validate-inputs
```
- Validate all inputs before processing
```
security-audit-advisors
```
- Regularly run Security Advisor checks

```
security-validate-inputs
```
- 处理前验证所有输入
```
security-audit-advisors
```
- 定期运行Security Advisor检查

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
When NOT to use the pattern
Reference links to official documentation

阅读单个规则文件获取详细说明与代码示例：

references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
不适用该模式的场景
官方文档参考链接

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

references/supabase-guidelines.md

如需查看包含所有扩展规则的完整指南：

references/supabase-guidelines.md