supabase-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Database Migrations

数据库迁移

Creating New Migrations

创建新迁移

CRITICAL: Always use

npx supabase migration new <name>

to create migration files. Never create them manually.

bash

npx supabase migration new descriptive_migration_name

This creates a properly timestamped migration file in

supabase/migrations/

重要提示： 请始终使用

npx supabase migration new <名称>

创建迁移文件，切勿手动创建。

bash

npx supabase migration new descriptive_migration_name

此命令会在

supabase/migrations/

目录下创建一个带时间戳的规范迁移文件。

Applying Migrations

应用迁移

When changes are already applied to the database (e.g., via direct SQL execution), mark the migration as applied without re-running:

bash

undefined

当数据库已通过其他方式（例如直接执行SQL）应用变更时，可将迁移标记为已应用，无需重新运行：

bash

undefined

Mark migration as applied (skip execution)

npx supabase migration repair --status applied <timestamp>

Example:

npx supabase migration repair --status applied 20260122214732

undefined

npx supabase migration repair --status applied 20260122214732

undefined

Pushing New Migrations

推送新迁移

For changes not yet applied to the database:

bash

npx supabase db push

对于尚未应用到数据库的变更：

bash

npx supabase db push

Listing Migrations

列出迁移

bash

undefined

bash

undefined

Show recent migrations

npx supabase migration list | tail -5

undefined

npx supabase migration list | tail -5

undefined

Migration Best Practices

迁移最佳实践

ALWAYS create migrations with CLI - Use
```
npx supabase migration new
```
never manual file creation
Data migrations first - Add columns, then migrate data, then drop old structures
Test migrations locally if possible (though we use remote DB)
Use transactions for complex data migrations
Verify after migration - Query the data to ensure migration succeeded

始终通过CLI创建迁移 - 使用
```
npx supabase migration new
```
，切勿手动创建文件
先执行数据迁移 - 新增列，然后迁移数据，再删除旧结构
尽可能在本地测试迁移（尽管我们使用远程数据库）
复杂数据迁移使用事务
迁移后进行验证 - 查询数据以确保迁移成功

Type Generation

类型生成

Regenerating Types from Database Schema

从数据库架构重新生成类型

After any schema changes, regenerate TypeScript types from the live database:

bash

undefined

在任何架构变更后，从实时数据库重新生成TypeScript类型：

bash

undefined

Generate from remote database (recommended for this project)

npx supabase gen types typescript --linked > src/integrations/supabase/types.ts

If local Supabase is running (Docker required)

npx supabase gen types typescript --local > src/integrations/supabase/types.ts


**Location:** Types are generated to `src/integrations/supabase/types.ts`

npx supabase gen types typescript --local > src/integrations/supabase/types.ts


**类型文件位置：** 类型将生成到`src/integrations/supabase/types.ts`

When to Regenerate Types

何时重新生成类型

Regenerate types after:

Adding new columns to tables
Creating new tables
Modifying column types
Adding/modifying enums
Database schema migrations

IMPORTANT: The types file is generated from the database schema, not manually edited.

在以下场景后重新生成类型：

为表新增列
创建新表
修改列类型
新增/修改枚举
数据库架构迁移

重要提示： 类型文件由数据库架构生成，请勿手动编辑。

Edge Functions

边缘函数（Edge Functions）

Creating New Edge Functions

创建新边缘函数

bash

undefined

bash

undefined

Create new function directory

npx supabase functions new my-function-name

Or create directory manually in supabase/functions/<function-name>/


**CRITICAL:** Always set `verify_jwt = false` in `supabase/config.toml` for new functions. The JWT verification uses the anon key which is not useful for our use case.


**重要提示：** 请始终为新函数在`supabase/config.toml`中设置`verify_jwt = false`。JWT验证使用的anon密钥对我们的用例没有帮助。

Adding Function to Config

向配置中添加函数

After creating a function, add it to

supabase/config.toml

toml

[functions.my-function-name]
enabled = true
verify_jwt = false  # Always false for this project
import_map = "./functions/my-function-name/deno.json"
entrypoint = "./functions/my-function-name/index.ts"

创建函数后，将其添加到

supabase/config.toml

：

toml

[functions.my-function-name]
enabled = true
verify_jwt = false  # Always false for this project
import_map = "./functions/my-function-name/deno.json"
entrypoint = "./functions/my-function-name/index.ts"

Deploying Edge Functions

部署边缘函数

bash

npx supabase functions deploy my-function-name

bash

npx supabase functions deploy my-function-name

Deleting Edge Functions

删除边缘函数

To properly remove an edge function:

Delete from remote Supabase:

bash

npx supabase functions delete function-name

Remove local directory:
bash
```
rm -rf supabase/functions/function-name
```
Remove from config.toml: Delete the
```
[functions.function-name]
```
section from
```
supabase/config.toml
```

要正确移除边缘函数：

从远程Supabase删除：

bash

npx supabase functions delete function-name

删除本地目录：
bash
```
rm -rf supabase/functions/function-name
```

从config.toml中移除： 从

supabase/config.toml

中删除

[functions.function-name]

部分

Complete Edge Function Deletion Example

完整边缘函数删除示例

bash

undefined

bash

undefined

1. Delete from remote

npx supabase functions delete create-team-member

2. Delete local directory

rm -rf supabase/functions/create-team-member

3. Edit config.toml to remove the function section

Remove lines like:

[functions.create-team-member]

enabled = true

verify_jwt = false

import_map = "./functions/create-team-member/deno.json"

entrypoint = "./functions/create-team-member/index.ts"

undefined

undefined

Listing Edge Functions

列出边缘函数

bash

undefined

bash

undefined

List all functions

ls supabase/functions/

Check config for function definitions

grep -A 4 "[functions" supabase/config.toml

undefined

grep -A 4 "[functions" supabase/config.toml

undefined

Database Query Execution

数据库查询执行

Running SQL Queries

运行SQL查询

This project uses a custom Supabase CLI wrapper:

bash

undefined

本项目使用自定义的Supabase CLI包装器：

bash

undefined

Run a query

bun run supabase:sql --query "SELECT COUNT(*) FROM profiles"

Alternative: Use the generated TypeScript CLI

./supabase-cli execute-sql --query "SELECT COUNT(*) FROM profiles"

undefined

./supabase-cli execute-sql --query "SELECT COUNT(*) FROM profiles"

undefined

Common Workflows

常见工作流

Complete Schema Change Workflow

完整架构变更工作流

When making database schema changes:

Create migration:

bash

npx supabase migration new describe_the_change

Write migration SQL in the created file
Apply migration:
bash
```
npx supabase db push
```

Regenerate types:

bash

npx supabase gen types typescript --linked > src/integrations/supabase/types.ts

Update frontend code to use new types/fields

进行数据库架构变更时：

创建迁移：

bash

npx supabase migration new describe_the_change

在创建的文件中编写迁移SQL
应用迁移：
bash
```
npx supabase db push
```

重新生成类型：

bash

npx supabase gen types typescript --linked > src/integrations/supabase/types.ts

更新前端代码以使用新类型/字段

Database Investigation Workflow

数据库调查工作流

When investigating database state:

bash

undefined

调查数据库状态时：

bash

undefined

Use bun run supabase:sql --query for quick queries

bun run supabase:sql --query "SELECT * FROM profiles LIMIT 5"

Or use the generated CLI

./supabase-cli execute-sql --query "SELECT * FROM app_roles"

undefined

./supabase-cli execute-sql --query "SELECT * FROM app_roles"

undefined

Project-Specific Notes

项目特定说明

This Project's Supabase Setup

本项目的Supabase设置

Database: Remote Supabase (project ref: sbdlvtfjsdldekqjzngh)
Local Docker: Not configured (use
```
--linked
```
flag for remote operations)
Type Location:
```
src/integrations/supabase/types.ts
```
Migrations Location:
```
supabase/migrations/
```
Functions Location:
```
supabase/functions/
```
Config Location:
```
supabase/config.toml
```

数据库： 远程Supabase（项目引用ID：sbdlvtfjsdldekqjzngh）
本地Docker： 未配置（远程操作使用
```
--linked
```
标志）
类型文件位置：
```
src/integrations/supabase/types.ts
```
迁移文件位置：
```
supabase/migrations/
```
函数文件位置：
```
supabase/functions/
```
配置文件位置：
```
supabase/config.toml
```

Key Learnings

关键经验总结

Always use migration repair when changes are already applied to remote DB
Regenerate types after every schema change - don't manually edit types
verify_jwt = false is standard for this project's edge functions
Use
--linked
flag for remote database operations (no local Docker)
Delete edge functions completely - remote, local files, AND config.toml

当变更已应用到远程数据库时，始终使用迁移修复命令
每次架构变更后重新生成类型 - 请勿手动编辑类型
本项目的边缘函数默认设置
verify_jwt = false
远程数据库操作使用
--linked
标志（无需本地Docker）
彻底删除边缘函数 - 包括远程、本地文件及config.toml中的配置