React / 系统课时
管理数据库迁移
管理数据库迁移
数据库结构会随着功能持续变化,直接手改线上表既难追踪也难复现。本节用按顺序执行的 SQL 迁移文件,把一次字段新增完整走通,并建立“版本可追溯、执行可重复、部署可验证”的迁移流程。
学习目标
- 理解迁移文件为什么必须进入版本控制
- 编写并执行一次可验证的结构变更
- 识别生产迁移中的兼容性、锁表与回滚边界
把结构变化记录成迁移文件
迁移文件的核心作用不是“保存最新建表 SQL”,而是记录数据库从旧状态到新状态经历了什么。文件名应带可排序前缀,团队只追加新迁移,不修改已经在共享环境执行过的历史文件。
一次典型发布包含三类对象:旧版应用、迁移程序和数据库结构。安全顺序要求迁移后的数据库在短时间内同时兼容旧代码与新代码,否则滚动发布时就可能出现一部分实例成功、一部分实例报错。

编写一次向后兼容的变更
假设已有 post 表,现在要加入发布状态。第一步先添加允许空值的字段并回填旧数据,再设置默认值和非空约束。这个顺序比“直接新增必填字段”更容易兼容已有数据。
将下面内容保存为 migrations/20260901_001_add_post_status.sql。这是完整迁移文件,适合教学环境和中小数据量表。
BEGIN;
ALTER TABLE post
ADD COLUMN status TEXT;
UPDATE post
SET status = 'draft'
WHERE status IS NULL;
ALTER TABLE post
ALTER COLUMN status SET DEFAULT 'draft',
ALTER COLUMN status SET NOT NULL;
ALTER TABLE post
ADD CONSTRAINT post_status_check
CHECK (status IN ('draft', 'published'));
CREATE INDEX idx_post_status ON post(status);
COMMIT;该文件的生效结果是:旧记录统一得到 draft,新记录缺省为 draft,非法状态会被数据库拒绝,并新增按状态过滤所需的索引。
执行迁移并立即验证
在项目根目录设置好 DATABASE_URL 后执行迁移。ON_ERROR_STOP=1 会让 psql 在任一语句失败时停止,避免错误被后续输出掩盖。
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f migrations/20260901_001_add_post_status.sql预期输出
BEGIN
ALTER TABLE
UPDATE <VALUE>
ALTER TABLE
ALTER TABLE
CREATE INDEX
COMMIT其中 <VALUE> 表示被回填的行数,实际值取决于数据库已有数据。
再检查字段、默认值和非空约束是否已经生效。
SELECT column_name, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'post'
AND column_name = 'status';预期结果
column_name | is_nullable | column_default
-------------+-------------+----------------
status | NO | 'draft'::text不同 PostgreSQL 版本可能对默认值表达式做等价格式化,但 is_nullable 应为 NO,默认值应等价于 draft。
让迁移适合团队协作
迁移文件必须和应用代码一起提交,CI 或部署平台按固定顺序执行,而不是让开发者在生产数据库里临时敲 SQL。已经执行过的历史迁移应视为不可变;如果发现遗漏,用新的迁移文件修正,这样每个环境才能从同一历史重建到同一结构。
回滚不是删除迁移文件
迁移失败后,首先判断事务是否已经自动回滚,以及新应用是否已经开始依赖新结构。数据库结构一旦被新代码写入数据,简单执行反向 DDL 可能造成数据丢失。
更稳妥的策略是优先采用“向前修复”:追加一个新迁移恢复兼容性。只有在确认应用尚未依赖新结构、反向操作不会丢数据时,才执行回滚。迁移管理真正维护的是数据库演进历史,而不只是若干 SQL 文件。