supabase-migration-deep-dive

Supabase 迁移深入解析

概述

Supabase 迁移是由 CLI 管理的带时间戳的 SQL 文件，用于跟踪不同环境中的架构变更。本技能涵盖完整的迁移生命周期——创建迁移、零停机架构变更、批量回填、版本管理、回滚和 TypeScript 类型生成，使用真实的 CLI 命令以及来自 @supabase/supabase-js 的 createClient。

适用场景： 创建新的数据库迁移、在不停机的情况下修改生产架构、添加列后回填现有数据、管理开发/预发布/生产环境中的迁移历史、回滚失败的迁移，或重新生成 TypeScript 类型。

先决条件

• 已安装 Supabase CLI：npm install -g supabase 或 npx supabase --version
• 项目中已安装 @supabase/supabase-js v2+
• 本地 Supabase 正在运行：npx supabase start
• 了解 PostgreSQL DDL 和事务行为

说明

步骤 1：创建和管理迁移

将每个迁移创建为带时间戳的 SQL 文件，编写 DDL，在本地重置后进行测试，然后使用 db push 将其逐步应用到各个环境：

npx supabase migration new add_profiles_table   # create timestamped SQL file
npx supabase migration list                      # show applied/pending status
npx supabase db reset                            # apply + seed locally (destructive)
npx supabase gen types typescript --local > lib/database.types.ts
npx supabase link --project-ref "<ref>" && npx supabase db push   # promote to remote

在同一个文件中编写 DDL，以启用 RLS、添加策略、索引和触发器，从而确保应用迁移后架构完整。如需查看完整的迁移示例（包含一个带有 RLS 策略的 profiles 表、电子邮件索引、注册触发器和 updated_at 触发器），以及本地测试和向预发布/生产环境升级的命令，请参阅创建迁移。

步骤 2：零停机迁移模式

生产环境的架构变更必须避免锁定表。核心规则：在 Postgres 11+ 中，添加带默认值的可空列不会造成锁定；在 -- supabase:disable-transaction 迁移中使用 CREATE INDEX CONCURRENTLY 创建索引；重命名列或更改列类型时，应分两个阶段进行（添加新列、回填、通过同步触发器同步，然后删除旧列），而不是原地执行 ALTER COLUMN。安全添加列的示例如下：

-- Nullable column with a default does NOT lock the table in Postgres 11+
ALTER TABLE public.orders ADD COLUMN status text DEFAULT 'pending';
-- Then, in a separate -- supabase:disable-transaction migration:
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_status ON public.orders(status);

完整内容包括：使用同步触发器分两阶段重命名列、通过添加-回填-切换安全更改类型，以及在迁移期间采样查询延迟的 SDK 健康检查。详见零停机模式。

步骤 3：数据回填、版本管理和回滚

请参阅数据回填、版本管理和回滚，了解使用 SDK 进行批量回填的模式、跨环境的架构版本管理、三种回滚策略（补偿迁移、修复、功能标志），以及迁移后的类型重新生成。

输出

此技能可提供：

• 迁移创建工作流 — 使用 npx supabase migration new 创建说明性 SQL 文件并在本地测试
• 零停机模式 — 安全添加列、分两阶段重命名、并发创建索引
• 批量回填 — 基于 SDK 的逐行更新，带进度日志和速率限制
• 架构版本管理 — 使用 supabase migration list 和 db diff 比较环境
• 回滚策略 — 补偿迁移、migration repair 和通过功能标志控制的架构变更
• 类型重新生成 — 每次架构变更后运行 supabase gen types typescript
• 迁移升级 — 从本地到预发布再到生产环境的 db push 工作流

错误处理

错误	原因	解决方案
migration has already been applied	重新运行已存在的迁移	使用 supabase migration list 检查状态；切勿修改已应用的迁移
cannot run inside a transaction block	在事务中使用 CREATE INDEX CONCURRENTLY	在迁移文件顶部添加注释 -- supabase:disable-transaction
迁移后出现 column does not exist	迁移尚未应用或类型已过期	运行 supabase db push，然后运行 supabase gen types typescript
回填期间出现 deadlock detected	同一行上发生并发更新	减小批次大小；添加带指数退避的重试逻辑
大型表出现 statement timeout	迁移耗时超过超时时间	在迁移中增大 statement_timeout：SET statement_timeout = '300s';
migration repair 失败	版本号错误	使用 supabase migration list 中的准确版本号（时间戳前缀）
db diff 显示意外更改	手动通过 SQL Editor 修改导致架构偏差	运行 supabase db pull，将手动更改记录为迁移
迁移后类型不匹配	生成的类型与新架构不匹配	删除 database.types.ts，并使用 --local 或 --linked 重新生成

示例

实际新增列的创建-写入-测试-推送工作流：

npx supabase migration new add_tags_to_projects
cat > supabase/migrations/20260322150000_add_tags_to_projects.sql << 'SQL'
ALTER TABLE public.projects ADD COLUMN tags text[] DEFAULT '{}';
CREATE INDEX idx_projects_tags ON public.projects USING GIN(tags);
SQL
npx supabase db reset
npx supabase gen types typescript --local > lib/database.types.ts
npx supabase link --project-ref <staging-ref> && npx supabase db push

参见示例，了解三个完整的实操示例：完整的本地到生产环境迁移工作流、使用 SDK 跟踪进度的批量回填，以及使用 CHECK 约束而非 ALTER TYPE 安全迁移枚举。

资源

• 数据库迁移 — Supabase 文档
• Supabase CLI 迁移命令
• supabase db push — Supabase 文档
• supabase gen types — Supabase 文档
• 零停机时间 PostgreSQL 迁移
• supabase db diff — Supabase 文档

后续步骤

• 如需了解迁移后的高级故障排查，请参见 supabase-advanced-troubleshooting
• 如需了解多环境迁移晋级，请参见 supabase-multi-env-setup
• 如需了解架构更改后的性能调优，请参见 supabase-performance-tuning