本地开发

声明式数据库模式

集中管理数据库模式并生成版本化迁移。

概述

声明式模式提供了一种对开发者友好的方式来维护模式迁移。

迁移传统上是命令式管理的（您需要提供如何具体更改数据库的指令）。这可能导致相关信息分散在多个迁移文件中。而使用声明式模式，您只需声明期望的数据库状态，系统会自动为您生成相应的指令。

模式迁移

模式迁移是使用数据定义语言(DDL)编写的SQL语句。它们被版本化存储在您的supabase/migrations目录中，以确保本地和远程环境之间的模式一致性。

声明您的数据库模式

1

创建第一个模式文件

在 supabase/schemas 目录下创建一个 SQL 文件，定义 employees 表。

1
2
3
4
create table "employees" (  "id" integer not null,  "name" text);
2

生成迁移文件

通过对比声明的模式来生成迁移文件。

1
supabase db diff -f create_employees_table
3

启动本地数据库并应用迁移

启动本地数据库，然后应用迁移文件以在本地仪表盘中查看模式变更。

1
supabase start && supabase migration up

更新数据库架构

1

停止本地数据库

在更新架构文件前，请先停止本地开发环境。

1
supabase stop
2

添加新列

编辑 supabase/schemas/employees.sql 文件，为 employees 表添加新列。

1
2
3
4
5
create table "employees" (  "id" integer not null,  "name" text,  "age" smallint not null);
3

生成新迁移

将现有迁移与声明的架构进行差异对比。

1
supabase db diff -f add_age
4

检查生成的迁移

确认生成的迁移只包含一个增量变更。

1
alter table "public"."employees" add column "age" smallint not null;
5

应用待处理迁移

启动本地数据库并应用待处理的迁移。

1
supabase start && supabase migration up

部署您的模式变更

1

登录 Supabase CLI

通过 Supabase CLI 登录。

1
supabase login
2

关联远程项目

按照屏幕提示关联您的远程项目。

1
supabase link
3

部署数据库变更

将您的变更推送到远程数据库。

1
supabase db push

管理依赖关系

随着数据库模式的发展，您可能会开始使用更高级的实体，如视图和函数。这些实体在使用纯迁移文件管理时非常冗长，因为任何变更都需要重新创建整个实体。通过声明式模式，您现在可以直接就地编辑它们，这使得代码审查变得更加容易。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
create table "employees" (  "id" integer not null,  "name" text,  "age" smallint not null);create view "profiles" as  select id, name from "employees";create function "get_age"(employee_id integer) RETURNS smallint  LANGUAGE "sql"AS $$  select age  from employees  where id = employee_id;$$;

默认情况下，您的模式文件会按字典顺序执行。当多个表之间存在外键关系时，顺序非常重要，因为必须先创建父表。例如，您的 supabase 目录最终可能具有以下结构。

1
2
3
4
5
6
7
8
9
.└── supabase/    ├── schemas/    │   ├── employees.sql    │   └── managers.sql    └── migrations/        ├── 20241004112233_create_employees_table.sql        ├── 20241005112233_add_employee_age.sql        └── 20241006112233_add_managers_table.sql

对于只有少量表的小型项目，默认的模式顺序可能已经足够。但随着项目规模扩大，您可能需要更精细地控制模式应用的顺序。要在 config.toml 中指定自定义的应用顺序，您可以显式声明它们。任何通配符模式都会被评估、去重并按字典顺序排序。例如，以下模式确保 employees.sql 始终优先执行。

1
2
3
4
5
[db.migrations]schema_paths = [  "./schemas/employees.sql",  "./schemas/*.sql",]

导入生产环境架构

要在现有项目上设置声明式架构，您可以通过运行以下命令导入生产环境架构：

1
supabase db dump > supabase/schemas/prod.sql

之后，您可以开始将架构分解为更小的文件并生成迁移。您可以一次性完成此操作，也可以在修改架构时逐步进行。

回滚架构变更

在开发过程中，您可能希望回滚迁移以将新的架构变更保留在单个迁移文件中。这可以通过将本地数据库重置到先前版本来实现。

1
supabase db reset --version 20241005112233

重置后，您可以编辑架构并重新生成新的迁移文件。请注意，您不应重置已部署到生产环境的版本。

如果需要回滚已部署的迁移，您应该首先还原对架构文件的更改。然后可以生成包含向下迁移的新迁移文件。这确保您的生产环境迁移始终向前滚动。

已知注意事项

用于生成架构差异的migra差异工具能够跟踪大多数数据库变更。但在某些边缘情况下可能会失败。

如果您需要使用以下任何实体，请记住通过版本化迁移来添加它们。

数据操作语言

  • 诸如insert、update、delete等DML语句不会被架构差异捕获

视图所有权

RLS策略

其他实体