Liam项目数据库迁移操作指南：Supabase分支管理与最佳实践

Liam项目数据库迁移操作指南：Supabase分支管理与最佳实践

liam Automatically generates beautiful and easy-to-read ER diagrams from your database. 项目地址: https://gitcode.com/gh_mirrors/li/liam

项目背景与架构概述

Liam项目采用Supabase作为后端数据库服务，并利用其分支功能实现高效的数据库迁移管理。这种架构设计将数据库变更与代码变更紧密结合，通过自动化流程确保开发、测试和生产环境的一致性。

核心迁移系统工作原理

Supabase分支系统与项目代码仓库深度集成，形成了一套自动化迁移流水线：

1. 自动触发机制：当代码合并到主分支时，系统会自动检测并执行位于frontend/internal-packages/db/supabase/migrations目录下的迁移脚本
2. 顺序执行：迁移脚本严格按照时间戳顺序执行，确保数据库变更的有序性
3. 环境一致性：从开发到生产的全流程保持数据库结构的一致性

关键约束条件与应对策略

在实际部署过程中，必须考虑以下关键约束并采取相应措施：

部署顺序不确定性

• 现象：应用部署（包括前端应用和后端任务）与数据库迁移完成顺序无法保证
• 解决方案：设计迁移时必须确保向后兼容，应用代码需要同时兼容新旧数据库结构

多分支并发开发

• 现象：不同功能分支可能同时修改数据库结构
• 解决方案：
  • 频繁合并主分支变更
  • 建立严格的代码评审机制
  • 使用预览分支进行充分测试

迁移文件创建规范

命名规则

迁移文件必须遵循严格的命名约定，采用YYYYMMDDHHmmss_简短描述.sql格式：

• 时间部分使用UTC时间戳
• 描述部分使用小写字母和下划线
• 示例：20240906123045_create_profiles.sql

文件位置

所有迁移文件必须放置在指定目录：frontend/internal-packages/db/supabase/migrations

SQL编写最佳实践

基本规范

• 全部SQL关键字使用小写
• 每个迁移必须包含详尽的注释说明
• 必须使用事务包装（BEGIN/COMMIT）
• 遵循项目定义的数据库设计模式

特殊操作注意事项

对于高风险操作（如删除、修改列等），需要：

1. 添加显眼的警告注释
2. 说明操作的影响范围
3. 提供回滚方案

NOT NULL约束添加指南

添加NOT NULL约束是常见的数据库变更操作，需要特别注意：

1. 分步实施：

   • 先添加可空列
   • 填充现有数据
   • 最后添加约束

2. 数据完整性：

   • 对于外键引用，确保引用完整性
   • 提供合理的默认值或派生值

3. 事务保护： 整个过程必须在单个事务中完成，确保原子性

迁移后验证流程

完成迁移后必须执行以下验证步骤：

1. 生成类型定义：

   cd frontend/internal-packages/db && pnpm supabase:gen
   

   该命令会同时更新数据库模式文件和TypeScript类型定义

2. 功能测试：

   • 验证应用在新旧数据库结构下的兼容性
   • 特别关注数据敏感操作

3. 测试用例更新：

   • 更新受影响的单元测试和集成测试
   • 确保类型检查通过

生产环境最佳实践

1. 小步快跑：保持每次迁移小而专注，降低风险
2. 预览测试：充分利用Supabase的预览分支功能
3. 监控预警：建立完善的监控机制，及时发现部署问题
4. 文档同步：确保数据库变更文档及时更新

通过遵循这些指南和实践，Liam项目可以确保数据库变更过程的安全性和可靠性，同时保持开发效率。

liam Automatically generates beautiful and easy-to-read ER diagrams from your database. 项目地址: https://gitcode.com/gh_mirrors/li/liam