React / 系统课时

管理数据库迁移

管理数据库迁移

数据库结构会随着功能持续变化,直接手改线上表既难追踪也难复现。本节用按顺序执行的 SQL 迁移文件,把一次字段新增完整走通,并建立“版本可追溯、执行可重复、部署可验证”的迁移流程。

学习目标

  • 理解迁移文件为什么必须进入版本控制
  • 编写并执行一次可验证的结构变更
  • 识别生产迁移中的兼容性、锁表与回滚边界

把结构变化记录成迁移文件

迁移文件的核心作用不是“保存最新建表 SQL”,而是记录数据库从旧状态到新状态经历了什么。文件名应带可排序前缀,团队只追加新迁移,不修改已经在共享环境执行过的历史文件。

一次典型发布包含三类对象:旧版应用、迁移程序和数据库结构。安全顺序要求迁移后的数据库在短时间内同时兼容旧代码与新代码,否则滚动发布时就可能出现一部分实例成功、一部分实例报错。

数据库迁移与应用发布顺序

编写一次向后兼容的变更

假设已有 post 表,现在要加入发布状态。第一步先添加允许空值的字段并回填旧数据,再设置默认值和非空约束。这个顺序比“直接新增必填字段”更容易兼容已有数据。

将下面内容保存为 migrations/20260901_001_add_post_status.sql。这是完整迁移文件,适合教学环境和中小数据量表。

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 在任一语句失败时停止,避免错误被后续输出掩盖。

bash
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f migrations/20260901_001_add_post_status.sql

预期输出

text
BEGIN
ALTER TABLE
UPDATE <VALUE>
ALTER TABLE
ALTER TABLE
CREATE INDEX
COMMIT

其中 <VALUE> 表示被回填的行数,实际值取决于数据库已有数据。

再检查字段、默认值和非空约束是否已经生效。

sql
SELECT column_name, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'post'
  AND column_name = 'status';

预期结果

text
 column_name | is_nullable | column_default
-------------+-------------+----------------
 status      | NO          | 'draft'::text

不同 PostgreSQL 版本可能对默认值表达式做等价格式化,但 is_nullable 应为 NO,默认值应等价于 draft。

让迁移适合团队协作

迁移文件必须和应用代码一起提交,CI 或部署平台按固定顺序执行,而不是让开发者在生产数据库里临时敲 SQL。已经执行过的历史迁移应视为不可变;如果发现遗漏,用新的迁移文件修正,这样每个环境才能从同一历史重建到同一结构。

回滚不是删除迁移文件

迁移失败后,首先判断事务是否已经自动回滚,以及新应用是否已经开始依赖新结构。数据库结构一旦被新代码写入数据,简单执行反向 DDL 可能造成数据丢失。

更稳妥的策略是优先采用“向前修复”:追加一个新迁移恢复兼容性。只有在确认应用尚未依赖新结构、反向操作不会丢数据时,才执行回滚。迁移管理真正维护的是数据库演进历史,而不只是若干 SQL 文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理数据库迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通