使用模式迁移进行本地开发
使用Supabase CLI和模式迁移进行本地开发。
Supabase 是一个灵活的平台,让您可以自由选择项目的构建方式。您可以直接使用 Dashboard 快速启动和运行,也可以采用完整的本地开发环境。我们建议您在本地进行开发,然后将变更部署到 Supabase 平台 上关联的项目。
使用 CLI 在本地运行 Supabase 技术栈进行开发。您可以通过集成的 Studio Dashboard 进行修改,然后将变更记录到模式迁移文件中,这些文件可以保存到版本控制系统中。
或者,如果您熟悉迁移文件和 SQL,可以直接编写自己的迁移脚本,在本地数据库中进行测试后再共享您的变更。
数据库迁移
数据库变更通过"迁移(migration)"进行管理。数据库迁移是一种常用的方式,用于跟踪数据库随时间的变化。
本指南将创建一个名为employees
的表,并演示如何对其进行修改。
向迁移文件添加SQL
这将创建一个新迁移文件:supabase/migrations/<时间戳> _create_employees_table.sql。
在该文件中添加创建employees
表的SQL
20250101000000_create_employees_table.sql
123456create table employees ( id bigint primary key generated always as identity, name text, email text, created_at timestamptz default now());
应用迁移
现在您已经有了迁移文件,可以运行此迁移来创建employees
表。
此处使用reset
命令将数据库重置为当前迁移状态
Terminal
1supabase db reset
修改employees表
现在您可以在仪表板中查看新建的employees
表。
接下来,通过添加部门列来修改employees
表。为此创建一个新的迁移文件。
Terminal
1supabase migration new add_department_to_employees_table
向表添加新列
这将创建一个新迁移文件:supabase/migrations/<时间戳> _add_department_to_employees_table.sql。
在该文件中添加创建新部门列的SQL
20250101000001_add_department_to_employees_table.sql
12alter table if exists public.employeesadd department text default 'Hooli';
添加示例数据
既然您现在使用迁移脚本来管理数据库,那么最好有一些种子数据,以便每次重置数据库时使用。
为此,您可以在 supabase/seed.sql
中创建一个种子脚本。
填充数据表
通过 supabase/seed.sql
文件向 employees
表插入数据。
supabase/seed.sql
123456insert into public.employees (name)values ('Erlich Bachman'), ('Richard Hendricks'), ('Monica Hall');
重置数据库
重置数据库(应用当前迁移)并填充种子数据
Terminal
1supabase db reset
现在您应该在控制面板中看到 employees
表以及种子数据了!所有的数据库变更都被记录在代码中,您可以随时重置到已知状态,包括完整的种子数据。
差异对比变更
如果您熟悉SQL并擅长创建表和列,这个工作流程非常理想。如果不熟悉,您仍然可以使用仪表板创建表和列,然后通过CLI对比差异并生成迁移。
创建一个名为cities
的新表,包含id
、name
和population
列。要查看对应的SQL语句,可以使用supabase db diff --schema public
命令。这将显示创建表和列所需的SQL语句。supabase db diff
的输出结果类似这样:
12345678Diffing 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复制到新的迁移文件中,并运行supabase db reset
来应用变更。
最后一步是将这些变更部署到实际的Supabase项目中。
部署项目
您一直在本地开发项目,通过迁移对表进行修改。现在是时候将项目部署到Supabase平台,开始扩展到数百万用户了!前往Supabase创建一个新项目进行部署。
登录Supabase CLI
1supabase login
关联项目
使用supabase link
将您的项目与远程项目关联。
123456789101112131415161718192021supabase 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
命令部署所有本地数据库迁移:
1supabase db push
访问 Supabase 上的实时项目,您将看到新增的 employees
表,包含您在上文第二个迁移中添加的 department
列。
部署边缘函数
如果项目使用了边缘函数,可以使用 functions deploy
命令进行部署:
1supabase functions deploy <function_name>
本地使用 Auth 功能
要在本地使用 Auth 功能,请更新运行 supabase init
后生成的 supabase/config.toml
文件。添加您需要的任何身份提供商,并将 enabled 设置为 true
。
12345[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 会自动替换这些值。
12SUPABASE_AUTH_GITHUB_CLIENT_ID="redacted"SUPABASE_AUTH_GITHUB_SECRET="redacted"
要使这些更改生效,您需要重新运行 supabase stop
和 supabase start
命令。
如果您在 auth
模式上定义了额外的触发器或 RLS 策略,可以将它们作为迁移文件拉取到本地。
1supabase db pull --schema auth
同步存储桶
您可以通过指定 storage
模式将存储桶上的 RLS 策略拉取到本地。例如:
1supabase db pull --schema storage
存储桶和对象本身是存储表中的行,因此它们不会出现在您的模式中。您可以通过 supabase/config.toml
文件定义它们。例如:
12345[storage.buckets.images]public = falsefile_size_limit = "50MiB"allowed_mime_types = ["image/png", "image/jpeg"]objects_path = "./images"
这将通过一个命令将 supabase/images
目录中的文件上传到项目中名为 images
的存储桶。
1supabase seed buckets
使用 --schema
同步指定模式
您可以通过 --schema
选项同步特定数据库模式,命令如下:
1supabase db pull --schema <schema_name>
关于 --schema
的注意事项
如果本地 supabase/migrations
目录为空,db pull
命令将忽略 --schema
参数。
解决方法是可以执行两次拉取:
12supabase db pullsupabase db pull --schema <schema_name>
限制与注意事项
本地开发环境的功能不如 Supabase 平台完整,主要差异包括:
- 无法通过仪表板更新项目设置,必须使用本地配置文件进行修改
- CLI 版本决定了本地使用的 Studio 版本,因此请确保保持 Supabase CLI 为最新版本。我们会持续添加新功能和修复错误