本文详解 Beego 中使用 bee migrate 进行结构化数据库迁移的全流程，涵盖迁移脚本生成、SQL 编写规范、执行与回滚操作，并提供生产环境注意事项。
本文详解 beego 中使用 `bee migrate` 进行结构化数据库迁移的全流程，涵盖迁移脚本生成、sql 编写规范、执行与回滚操作，并提供生产环境注意事项。
Beego 原生支持基于时间戳的数据库迁移机制，通过 bee 工具链实现轻量、可控的 Schema 演进。与 Django 的 South 或 Alembic 不同，Beego 迁移不依赖 ORM 自动推导，而是由开发者显式编写 SQL 语句，兼顾灵活性与可审计性。
一、生成迁移脚本
使用 bee generate migration 命令创建带时间戳的迁移文件（位于 database/migrations/ 目录下）：
bee generate migration add_age_to_user
输出示例：
2024/05/10 10:22:33 [INFO] Using 'add_age_to_user' as migration name 2024/05/10 10:22:33 [INFO] Migration file generated: ./database/migrations/20240510_102233_add_age_to_user.go 2024/05/10 10:22:33 [SUCC] generate successfully created!
生成的 Go 文件结构固定，包含 Up()（正向迁移）和 Down()（逆向回滚）两个核心方法，均接收 *migration.Migration 实例，可通过 m.SQL() 执行原生 SQL。
二、编写安全的迁移逻辑
以「为 user 表新增 age 字段（INT 类型，默认值为 0）」为例，需同时考虑正向变更与可逆性：
// database/migrations/20240510_102233_add_age_to_user.go
package main
import (
"github.com/astaxie/beego/migration"
)
type AddAgeToUser_20240510_102233 struct {
migration.Migration
}
func init() {
m := &AddAgeToUser_20240510_102233{}
m.Created = "20240510_102233"
migration.Register("AddAgeToUser_20240510_102233", m)
}
func (m *AddAgeToUser_20240510_102233) Up() {
// MySQL 示例：添加字段（注意指定 DEFAULT 和 NOT NULL 策略）
m.SQL("ALTER TABLE `user` ADD COLUMN `age` INT NOT NULL DEFAULT 0 AFTER `name`")
}
func (m *AddAgeToUser_20240510_102233) Down() {
// 安全回滚：仅删除字段（MySQL 5.7+ 支持）
m.SQL("ALTER TABLE `user` DROP COLUMN `age`")
}✅ 关键实践建议：
- ✅ 总是为 NOT NULL 字段提供 DEFAULT 值，避免因存量数据导致 ALTER 失败；
- ✅ 在 Up() 中优先使用幂等 SQL（如 ADD COLUMN IF NOT EXISTS 不被 MySQL 原生支持，需自行判断表结构）；
- ✅ Down() 必须真正可逆——删除字段、索引或表前，确认无业务依赖；
- ✅ 避免在迁移中执行耗时 DML（如 UPDATE 百万行），应拆分为独立脚本或后台任务。
三、执行与验证迁移
运行 bee migrate 并传入数据库连接字符串（支持 MySQL、PostgreSQL、SQLite3）：
# MySQL 示例（推荐使用环境变量或配置文件管理敏感信息） bee migrate -conn="root:pass@tcp(127.0.0.1:3306)/myapp?charset=utf8mb4&parseTime=True" # 查看迁移状态（不执行，仅预览） bee migrate -status -conn="..."
执行成功后，Beego 会自动在目标数据库中创建 migration 表（如 beego_migration），记录已应用的迁移版本及时间戳，确保多次执行 bee migrate 不会重复应用。
四、生产环境注意事项
- ? 禁止直接修改已提交的迁移文件：一旦迁移到生产环境，对应 .go 文件即为不可变事实。若需修正，应新建迁移（如 fix_age_column_default），而非编辑旧文件。
- ? 统一管理连接配置：建议将 -conn 参数替换为 -config=conf/app.conf，并在 app.conf 中定义 db.connection，提升安全性与可维护性。
- ? 本地 + 测试库双重验证：每次迁移前，先在本地 SQLite 或测试 MySQL 实例中完整跑通 Up → Down → Up 流程。
- ? 备份先行：生产环境执行前，务必对目标库执行逻辑备份（如 mysqldump），并确认备份可恢复。
Beego 的迁移机制虽简洁，但正因其“显式即安全”的设计哲学，要求开发者对 SQL 语义与数据库兼容性保持敬畏。合理运用 m.SQL()、严谨编写 Up/Down、配合自动化流程，即可构建稳定可靠的数据库演进体系。
