本地开发

使用模式迁移进行本地开发

使用Supabase CLI和模式迁移进行本地开发。


Supabase 是一个灵活的平台,让您可以自由选择项目的构建方式。您可以直接使用 Dashboard 快速启动和运行,也可以采用完整的本地开发环境。我们建议您在本地进行开发,然后将变更部署到 Supabase 平台 上关联的项目。

使用 CLI 在本地运行 Supabase 技术栈进行开发。您可以通过集成的 Studio Dashboard 进行修改,然后将变更记录到模式迁移文件中,这些文件可以保存到版本控制系统中。

或者,如果您熟悉迁移文件和 SQL,可以直接编写自己的迁移脚本,在本地数据库中进行测试后再共享您的变更。

数据库迁移

数据库变更通过"迁移(migration)"进行管理。数据库迁移是一种常用的方式,用于跟踪数据库随时间的变化。

本指南将创建一个名为employees的表,并演示如何对其进行修改。

1

创建第一个迁移文件

首先,生成一个新的迁移来存储创建employees表所需的SQL

Terminal
1
supabase migration new create_employees_table
2

向迁移文件添加SQL

这将创建一个新迁移文件:supabase/migrations/<时间戳> _create_employees_table.sql。

在该文件中添加创建employees表的SQL

20250101000000_create_employees_table.sql
1
2
3
4
5
6
create table employees ( id bigint primary key generated always as identity, name text, email text, created_at timestamptz default now());
3

应用迁移

现在您已经有了迁移文件,可以运行此迁移来创建employees表。

此处使用reset命令将数据库重置为当前迁移状态

Terminal
1
supabase db reset
4

修改employees表

现在您可以在仪表板中查看新建的employees表。

接下来,通过添加部门列来修改employees表。为此创建一个新的迁移文件。

Terminal
1
supabase migration new add_department_to_employees_table
5

向表添加新列

这将创建一个新迁移文件:supabase/migrations/<时间戳> _add_department_to_employees_table.sql。

在该文件中添加创建新部门列的SQL

20250101000001_add_department_to_employees_table.sql
1
2
alter table if exists public.employeesadd department text default 'Hooli';

添加示例数据

既然您现在使用迁移脚本来管理数据库,那么最好有一些种子数据,以便每次重置数据库时使用。

为此,您可以在 supabase/seed.sql 中创建一个种子脚本。

1

填充数据表

通过 supabase/seed.sql 文件向 employees 表插入数据。

supabase/seed.sql
1
2
3
4
5
6
insert into public.employees (name)values ('Erlich Bachman'), ('Richard Hendricks'), ('Monica Hall');
2

重置数据库

重置数据库(应用当前迁移)并填充种子数据

Terminal
1
supabase db reset

现在您应该在控制面板中看到 employees 表以及种子数据了!所有的数据库变更都被记录在代码中,您可以随时重置到已知状态,包括完整的种子数据。

差异对比变更

如果您熟悉SQL并擅长创建表和列,这个工作流程非常理想。如果不熟悉,您仍然可以使用仪表板创建表和列,然后通过CLI对比差异并生成迁移。

创建一个名为cities的新表,包含idnamepopulation列。要查看对应的SQL语句,可以使用supabase db diff --schema public命令。这将显示创建表和列所需的SQL语句。supabase db diff的输出结果类似这样:

1
2
3
4
5
6
7
8
Diffing schemas: publicFinished supabase db diff on branch main.create table "public"."cities" ( "id" bigint primary key generated always as identity, "name" text, "population" bigint);

或者,您也可以直接从表编辑器中查看表定义:

SQL定义

然后可以将这些SQL复制到新的迁移文件中,并运行supabase db reset来应用变更。

最后一步是将这些变更部署到实际的Supabase项目中。

部署项目

您一直在本地开发项目,通过迁移对表进行修改。现在是时候将项目部署到Supabase平台,开始扩展到数百万用户了!前往Supabase创建一个新项目进行部署。

登录Supabase CLI

1
supabase login

关联项目

使用supabase link将您的项目与远程项目关联。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
supabase link --project-ref <项目ID># 可以从项目仪表板URL获取<项目ID>:https://supabase.com/dashboard/project/<项目ID>supabase db pull# 捕获您在完成上述步骤之前对远程数据库所做的任何变更# 如果您尚未对远程数据库进行任何更改,请跳过此步骤`supabase/migrations` 目录现在包含一个名为 `<timestamp>_remote_schema.sql` 的迁移文件。该迁移文件记录了使本地数据库与远程 Supabase 项目模式匹配所需的所有变更。检查生成的迁移文件,确认无误后,将这些变更应用到本地实例:```bash# 将新迁移应用到本地数据库:supabase migration up# 完全重置本地数据库:supabase db reset

部署数据库变更

使用 db push 命令部署所有本地数据库迁移:

1
supabase db push

访问 Supabase 上的实时项目,您将看到新增的 employees 表,包含您在上文第二个迁移中添加的 department 列。

部署边缘函数

如果项目使用了边缘函数,可以使用 functions deploy 命令进行部署:

1
supabase functions deploy <function_name>

本地使用 Auth 功能

要在本地使用 Auth 功能,请更新运行 supabase init 后生成的 supabase/config.toml 文件。添加您需要的任何身份提供商,并将 enabled 设置为 true

1
2
3
4
5
[auth.external.github]enabled = trueclient_id = "env(SUPABASE_AUTH_GITHUB_CLIENT_ID)"secret = "env(SUPABASE_AUTH_GITHUB_SECRET)"redirect_uri = "http://localhost:54321/auth/v1/callback"

作为最佳实践,所有密钥值都应从环境变量加载。您可以将它们添加到项目根目录的 .env 文件中,CLI 会自动替换这些值。

1
2
SUPABASE_AUTH_GITHUB_CLIENT_ID="redacted"SUPABASE_AUTH_GITHUB_SECRET="redacted"

要使这些更改生效,您需要重新运行 supabase stopsupabase start 命令。

如果您在 auth 模式上定义了额外的触发器或 RLS 策略,可以将它们作为迁移文件拉取到本地。

1
supabase db pull --schema auth

同步存储桶

您可以通过指定 storage 模式将存储桶上的 RLS 策略拉取到本地。例如:

1
supabase db pull --schema storage

存储桶和对象本身是存储表中的行,因此它们不会出现在您的模式中。您可以通过 supabase/config.toml 文件定义它们。例如:

1
2
3
4
5
[storage.buckets.images]public = falsefile_size_limit = "50MiB"allowed_mime_types = ["image/png", "image/jpeg"]objects_path = "./images"

这将通过一个命令将 supabase/images 目录中的文件上传到项目中名为 images 的存储桶。

1
supabase seed buckets

使用 --schema 同步指定模式

您可以通过 --schema 选项同步特定数据库模式,命令如下:

1
supabase db pull --schema <schema_name>

限制与注意事项

本地开发环境的功能不如 Supabase 平台完整,主要差异包括:

  • 无法通过仪表板更新项目设置,必须使用本地配置文件进行修改
  • CLI 版本决定了本地使用的 Studio 版本,因此请确保保持 Supabase CLI 为最新版本。我们会持续添加新功能和修复错误