06.5.3.9 数据库迁移与 Schema
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.3 Yii
06.5.3.9-001 Yii 中数据库迁移解决什么问题?命令入口是什么?
一句话结论
迁移用带版本号的 PHP 类文件管理数据库结构与初始数据变更,替代手工改表;2.x 通过控制台 migrate 控制器执行 up/down,每次执行记录到迁移历史表,保证团队与多环境变更可追溯、可重复。
概念解释
迁移把 Schema 变更纳入版本控制:每个迁移是一个继承迁移基类的类,文件名前缀带时间戳或序号,命令按历史表中未执行过的记录顺序向上应用,也可按批次向下回滚。它与直接执行 SQL 脚本的区别在于:版本顺序集中管理、可回滚、可在部署流水线中自动执行。
原理流程
- 开发者用
migrate/create生成迁移类模板,填写up()/down()。 - 提交后团队成员执行
migrate/up,命令读取历史表,依次执行未记录的迁移。 - 每个迁移成功后向历史表写入版本号与批次号。
- 需要回滚时执行
migrate/down,按批次反向调用已执行迁移的down()。
代码或图示
// 迁移类骨架(示意,类名以生成器产出为准)
use yii\db\Migration;
class m261119_000001_create_example_table extends Migration
{
public function up() { /* 建表与索引 */ }
public function down() { /* 反向操作 */ }
}
常见误区
- 把迁移当一次性 SQL 脚本,跑完就删:历史表与代码库记录脱节,新环境无法重建结构。
- 在迁移里写依赖运行时业务状态的逻辑:迁移应只依赖数据库结构与固定数据,不依赖页面请求上下文。
追问
- 迁移与 fixture 有什么区别?答:迁移管理结构演进与必要的初始数据;fixture 主要为测试准备数据集,两者用途不同。
- 3.0 是否沿用同一套迁移命令?答:3.0 迁移位于独立
yiisoft/db-migration类包,命令入口与类签名以对应包文档为准;具体类名与默认历史表名待确认。
06.5.3.9-002 迁移类的 up() 与 down() 分别承担什么职责?
一句话结论
up() 描述向前变更(建表、加列、加索引、回填数据),down() 描述对称的反向变更(删表、删列、删索引);up 成功执行后才记录历史,down 用于撤销该批次变更。
概念解释
规范的迁移成对编写:down() 应当能把 up() 造成的结构改动还原。并非所有变更都可无损回滚(如删列、改类型、删数据),这类迁移要么在 down() 中放弃反向恢复,要么通过备份表保留数据后再回滚,需在注释中说明不可回滚的原因。
原理流程
up()调用基类提供的 Schema 方法执行 DDL 或数据更新。- 命令校验
up()返回成功(无异常、返回值不为false时视为成功)。 - 回滚时命令按批次逆序调用
down()。 down()中同样可能抛异常,此时回滚中断,需人工处理。
代码或图示
public function up()
{
$this->createTable('{{%example}}', [
'id' => $this->primaryKey(),
'title' => $this->string(128)->notNull(),
]);
}
public function down()
{
$this->dropTable('{{%example}}');
}
常见误区
- 只写
up()不写down():回滚时该迁移无法撤销,问题排查成本高。 - 在
down()里重放业务逻辑:反向操作应只恢复结构,不重新生成线上数据。
追问
up()返回false会怎样?答:命令把该迁移视为失败,不写入历史表,后续迁移也不再继续应用(具体中断行为以当前框架版本为准,待确认)。- 破坏性变更如何处理回滚?答:先把待删数据备份到备份表,
down()从备份表恢复;无法恢复时明确标注该迁移不可回滚。
06.5.3.9-003 迁移基类提供哪些常用 Schema 操作方法?
一句话结论
基类封装了方言无关的建表、删表、加列、改列、删列、加索引、删索引、加外键等方法,方法内部把类型与标识符翻译成当前数据库方言的 SQL。
概念解释
常用方法包括 createTable()、dropTable()、addColumn()、dropColumn()、alterColumn()、renameColumn()、addIndex()、dropIndex()、addForeignKey()、dropForeignKey()、createIndex()。列类型通过 $this->primaryKey()、$this->integer()、$this->string() 等类型表达式声明,再由 Schema 层映射到 MySQL/PostgreSQL 等具体类型。
原理流程
- 迁移方法接收表名、列定义、索引名等参数。
- 方法生成
yii\db\Command,交由当前 db 组件的 Schema 构建方言 SQL。 - 通过事务执行命令(是否包裹事务见 06.5.3.9-005)。
- 命令执行成功后迁移继续下一步。
代码或图示
$this->addColumn('{{%example}}', 'status', $this->integer()->notNull()->defaultValue(0));
$this->createIndex('idx-example-status', '{{%example}}', 'status');
常见误区
- 直接拼接原生 DDL 字符串:绕过方言抽象,换数据库时列类型与引号规则失效。
- 索引名不按表前缀规范命名:多库迁移时索引名冲突难以排查。
追问
- 列定义链式方法有哪些?答:
notNull()、null()、defaultValue()、unique()、comment()、unsigned()等,可用范围以当前版本 Schema 构建器文档为准。 - 原生 SQL 怎么办?答:可用
$this->execute($sql)执行特定方言语句,但应隔离方言差异并在注释标注适用数据库。
06.5.3.9-004 表名与列名中的双花括号 {{%}} 起什么作用?
一句话结论
{{%表名}} 是带表前缀占位符的写法:生成 SQL 时 % 被替换为 db 组件配置的 tablePrefix,便于同一套代码在不同前缀的数据库间部署。
概念解释
配置中设置 tablePrefix(如 tbl_)后,{{%example}} 展开为带前缀的物理表名;不带 % 的 {{example}} 只做引号包裹,不追加前缀。迁移、AR 表名声明、查询中应统一使用占位写法,避免硬编码前缀。
原理流程
- 写迁移时使用
{{%example}}占位。 - Schema 层读取 db 组件的
tablePrefix。 - 占位符替换为物理表名,并用当前方言的标识符引号包裹。
- 最终 SQL 中表名与配置前缀一致。
代码或图示
// 配置片段:'tablePrefix' => 'app_'
$this->createTable('{{%example}}', [
'id' => $this->primaryKey(),
]);
// 实际物理表名:app_example
常见误区
- 迁移里写死带前缀的表名:改前缀后迁移与配置不一致。
- 混用
{{%}}与裸表名:同一表在不同语句中前缀表现不一致,导致找不到表。
追问
- AR 类如何配合表前缀?答:
tableName()返回{{%example}}占位形式,由 AR 与 Schema 层统一展开。 - 不配置前缀会怎样?答:
%被空串替换,占位写法仍正常工作,可平滑启用前缀。
06.5.3.9-005 迁移是否在事务中执行?哪些数据库 DDL 不能回滚?
一句话结论
2.x 迁移命令默认在事务内执行单个迁移类(可通过属性或配置调整),但 MySQL 的 InnoDB 对多数 DDL 是隐式提交或不支持事务回滚,PostgreSQL 的 DDL 则可随事务回滚;因此迁移回滚能力受数据库方言限制,不能假设所有 DDL 都能事务撤销。
概念解释
迁移基类提供事务相关开关(如控制是否使用事务的属性,具体属性名与默认值以当前版本文档为准,待确认)。事务能保证数据类变更(DML)的原子性;结构类变更(DDL)能否回滚取决于数据库:PostgreSQL 支持事务内 DDL 回滚,MySQL 多数 DDL 语句会隐式提交,失败后无法靠事务撤销。
原理流程
- 命令开始执行单个迁移类前尝试开启事务。
up()内 DML 与可事务化的 DDL 随事务提交或回滚。- 遇到隐式提交的 DDL 后,事务边界被数据库打破。
- 回滚命令对不可事务化 DDL 无能为力,只能靠
down()显式反向操作或备份恢复。
代码或图示
事务边界(可回滚范围)
数据更新 DML —— 事务可回滚
PostgreSQL DDL —— 事务可回滚
MySQL 多数 DDL —— 隐式提交,事务不可回滚
数据删除/截断 —— 需备份表兜底
常见误区
- 以为开了事务,加列失败就一定自动还原:MySQL 隐式提交后部分结构改动已经落库。
- 把大表 DDL 放进迁移事务长时间持有锁:应结合在线变更策略评估锁与耗时。
追问
- 如何确认当前方言 DDL 事务行为?答:对照数据库官方文档的 DDL 事务支持说明,并在预发环境用测试库验证
down()结果。 - 大表加列怎么办?答:评估锁表时间与在线 DDL 工具,必要时分步加列、回填、双写过渡,不要假设迁移事务能保护线上大表。
06.5.3.9-006 迁移历史表记录了哪些信息?
一句话结论
历史表保存已执行迁移的版本号(迁移类名/前缀)、所属批次号与应用时间;命令据此判断哪些迁移未执行、回滚时按批次定位逆序集合。
概念解释
默认历史表名(如 migration,具体名称可在迁移控制器配置中覆盖,待确认)通常含字段:版本(字符串,唯一)、批次(整数)、应用时间戳。批次号把同一次 up 执行的多个迁移归为一组,down 按最近整批回滚,保证回滚边界与发布批次一致。
原理流程
- 迁移成功后向历史表插入一行:版本号、批次号、时间。
- 下次
up时扫描迁移目录,与历史表比对出未记录版本。 down读取最大批次号对应的全部版本。- 逆序调用这些版本的
down(),成功后删除对应历史记录。
代码或图示
历史表(示意字段)
+----------------------+-------+---------------------+
| version | batch| apply_time |
+----------------------+-------+---------------------+
| m261119_000001_xxx | 1 | 2026-11-19 10:00:00 |
+----------------------+-------+---------------------+
常见误区
- 手工删历史表记录:命令会认为迁移未执行而重复应用,产生建表失败或数据错乱。
- 多人同时改同一迁移文件内容:已记录版本不重新执行,修改不会生效,应新增迁移。
追问
- 历史表名如何配置?答:在迁移控制器配置中指定历史表相关选项,具体配置键名以当前版本文档为准,待确认。
- 回滚后历史记录如何处理?答:
down成功后删除该版本对应行;回滚失败的行保留,避免命令误判状态。
06.5.3.9-007 migrate/up、migrate/down、migrate/redo 各做什么?
一句话结论
up 应用全部未执行迁移;down 回滚最近一批(或指定数量)已执行迁移;redo 先 down 再 up 同一批,用于本地调试迁移逻辑。
概念解释
up 是常规部署动作;down 用于撤销最近发布批次,按批次逆序;redo 在不离开当前环境的情况下重放最近一批迁移,验证 up/down 成对逻辑是否正确。命令还支持指定目标版本、限制数量等选项,具体选项名以当前版本命令帮助为准。
原理流程
up:扫描目录 → 比对历史表 → 按版本顺序执行up()。down:取最近批次(或-n指定数量)→ 逆序执行down()。redo:对最近批次先执行down()再执行up()。- 每步成功后更新历史表。
代码或图示
# 典型控制台调用(命令名称以框架安装的命令注册为准)
yii migrate/up
yii migrate/down 1
yii migrate/redo
常见误区
- 在生产直接
down回滚结构变更:未验证过的反向操作可能丢数据,应先在预发演练。 - 用
redo代替新增迁移修复已上线问题:已上线迁移不可改,修复要走新迁移。
追问
- 能否只回滚某一个旧版本?答:常规回滚按批次逆序进行;跳过中间版本需要额外方案,不推荐依赖命令单跳回滚。
- 命令如何指定数据库连接?答:通过命令的 db 连接选项选择 db 组件 ID,多库项目分别迁移。
06.5.3.9-008 如何创建一个新的迁移文件?命名有什么约定?
一句话结论
用 migrate/create 生成带时间戳前缀的迁移类,类名与文件名后缀描述变更内容;命令按前缀顺序排序执行,新迁移应追加到末尾,不插入到已执行历史之前。
概念解释
生成的文件名形如 m<YYMMDD>_<HHMMSS>_<描述>.php,类名与文件名对应。时间戳前缀保证多人并行开发时迁移顺序可排序;提交到仓库后,历史顺序以文件前缀与历史表记录为准。已被环境执行过的迁移不得再修改内容。
原理流程
- 执行 create 命令并给出描述(如
create_example_table)。 - 生成器按当前时间生成前缀与类骨架。
- 开发者填写
up()/down()与必要的数据回填。 - 提交后由
up命令按前缀纳入执行顺序。
代码或图示
# 生成命令(示意)
yii migrate/create create_example_table
# 产出文件
m261119_100001_create_example_table.php
常见误区
- 手工复制旧迁移改类名却忘记改历史前缀:顺序错乱,回滚批次边界混乱。
- 修改已上线迁移的
up():旧环境不会重放,新环境与线上结构不一致。
追问
- 迁移目录如何配置?答:在迁移控制器配置中指定迁移路径别名,模块可提供独立迁移目录。
- 模块迁移如何纳入主命令?答:通过配置把模块迁移目录加入扫描列表,或在模块发布时执行对应命令。
06.5.3.9-009 列类型表达式如何映射到数据库方言?
一句话结论
类型表达式(primaryKey、integer、string、text、datetime、decimal、boolean 等)由 Schema 层按当前数据库的类型映射表翻译成具体物理类型,同一套迁移可在不同方言间复用。
概念解释
常用映射:string(n) 映射变长字符串,text 映射长文本,integer/bigInteger/smallInteger 映射整数族,decimal(p,s) 映射定点数,date/time/datetime 映射时间类型,boolean 在不支持原生布尔的方言上映射为小整数。具体长度与是否 unsigned 以类型映射表为准。
原理流程
- 迁移方法调用类型表达式构造类型对象。
- Schema 层读取当前方言的
typeMap。 - 按方言把类型对象转成物理类型字符串。
- 拼接长度、精度、正负号、默认值等子句生成 DDL。
代码或图示
$this->createTable('{{%article}}', [
'id' => $this->primaryKey(),
'title' => $this->string(255)->notNull(),
'body' => $this->text(),
'price' => $this->decimal(10, 2)->defaultValue(0),
'is_on' => $this->boolean()->defaultValue(false),
]);
常见误区
- 写死 MySQL 专属类型(如
tinyint(1)):换 PostgreSQL 时类型不兼容。 - 依赖某方言的默认长度:跨库部署时字符串长度与容量预期不一致。
追问
- 如何查看当前方言类型映射?答:读取 db 组件 Schema 的类型映射配置,或在预发库用
SHOW CREATE TABLE(MySQL)等方言命令核对实际物理类型。 - 枚举类型怎么处理?答:跨库优先用整数状态码加字典说明;数据库原生枚举绑定特定方言,迁移可移植性差。
06.5.3.9-010 如何在迁移中定义普通索引与唯一索引?
一句话结论
用 createIndex() 声明索引,第三个参数指定是否唯一;索引名按规范命名,覆盖单列或多列组合,字段顺序遵循查询条件与排序需求。
概念解释
createIndex($name, $table, $columns, $unique = false) 生成索引;唯一索引保证列组合不重复。组合索引遵循最左前缀原则,字段顺序要与高频查询的等值条件、排序方向匹配。索引应随表结构变更一起进迁移,避免线上手工补索引遗漏。
原理流程
- 在
up()中写createIndex()并给出索引名与列数组。 - 回滚时在
down()调用dropIndex($name, $table)对称删除。 - Schema 层生成方言索引 DDL。
- 索引随表一起纳入版本控制。
代码或图示
$this->createIndex('idx-article-status', '{{%article}}', ['status', 'created_at']);
$this->createIndex('uk-article-slug', '{{%article}}', 'slug', true);
常见误区
- 索引名重复或过于通用:多张表同名索引在多库环境难以定位。
- 为每个单列单独建索引:重复覆盖组合索引前缀,浪费写入开销。
追问
- 唯一索引与应用层唯一性校验如何配合?答:唯一索引是兜底约束,应用层校验用于给用户友好报错;两者都不能省略。
- 多列索引顺序如何定?答:等值条件列在前、排序与范围列在后;具体顺序用执行计划验证(参见 06.5.3.8-016)。
06.5.3.9-011 外键约束如何在迁移中定义?有哪些注意事项?
一句话结论
addForeignKey() 声明主外键关系并指定级联行为;被引用列必须先有索引或唯一约束,删表时需先删外键再删主表,否则反向迁移顺序出错。
概念解释
外键方法参数包含约束名、子表、子表列、父表、父表列、onDelete/onUpdate 级联策略(RESTRICT、CASCADE、SET NULL 等)。反向 down() 先 dropForeignKey() 再 dropTable(),顺序与正向相反。是否启用物理外键取决于团队约定:高并发分库场景常由应用层维护关联一致性。
原理流程
- 父子表都已在迁移中创建。
- 调用
addForeignKey()生成外键约束。 down()先删外键,再按逆序删表。- 数据库校验参照完整性,违反约束时写入被拒绝。
代码或图示
$this->addForeignKey(
'fk-comment-article_id',
'{{%comment}}', 'article_id',
'{{%article}}', 'id',
'CASCADE', 'CASCADE'
);
常见误区
down()先删父表再删外键:数据库拒绝删表,回滚中断。- 依赖外键做业务状态约束:跨服务或软删除场景下物理外键反而阻碍数据维护。
追问
- 软删除场景适合外键吗?答:软删除不物理删行,级联删除不会触发;关联一致性需应用层处理,外键价值有限。
- 外键级联策略如何选?答:子表随主表消亡用
CASCADE;主表保留、子表可空用SET NULL;默认拒绝删除用RESTRICT。
06.5.3.9-012 数据迁移与历史数据回填如何设计才安全?
一句话结论
结构变更与数据回填尽量拆成独立迁移;回填按主键分批小步执行,避免长事务与大锁,回填前评估数据量、索引与回滚方案,不可在迁移里假设线上数据已经规范。
概念解释
常见回填场景:新列默认值补齐、枚举值归一化、冗余字段反查填充。安全做法:先加可空列并给默认值,再分批 UPDATE ... WHERE id BETWEEN ... 小批量推进,每批提交;大批量回填配合只读窗口或在线工具。回填逻辑要幂等,重复执行不产生错误结果。
原理流程
- 结构迁移先上线:加列、加索引,允许旧代码写入。
- 数据迁移按批次扫描主键区间,逐批更新。
- 每批记录进度(或靠可重跑的 WHERE 条件保证幂等)。
- 回填完成后再在后续迁移中收紧非空约束或切换默认值。
代码或图示
$batchSize = 500;
$lastId = 0;
do {
$rows = (new \yii\db\Query())
->select(['id'])->from('{{%example}}')
->where(['>', 'id', $lastId])->orderBy(['id' => SORT_ASC])
->limit($batchSize)->all();
foreach ($rows as $row) {
$this->update('{{%example}}', ['flag' => 1], ['id' => $row['id']]);
}
$lastId = end($rows)['id'] ?? $lastId;
} while (count($rows) === $batchSize);
常见误区
- 一条
UPDATE改全表:大事务长锁,主从延迟与锁等待风险高。 - 回填与加非空约束放在同一迁移:旧数据未补齐时约束直接失败。
- 回填逻辑依赖请求时的会话与权限:迁移运行在控制台上下文,拿不到用户身份。
追问
- 回填失败如何续跑?答:用可重跑的条件(只处理未回填行)设计 WHERE,中断后重新执行即可继续。
- 结构与数据必须同时变怎么办?答:评估灰度方案:双写过渡、新列并行填充、切换读取、最后清理旧列,分多个迁移与发布窗口完成。
06.5.3.9-013 迁移后为什么要清理 Schema 缓存?
一句话结论
db 组件可开启 Schema 缓存缓存表结构元数据;迁移改表后缓存中的结构已过期,不清缓存会导致 AR/Query 读到旧列信息,出现未知列或类型不符错误。
概念解释
Schema 缓存与业务数据缓存是两套机制:前者缓存表名、列名、类型、主键等元数据,后者缓存查询结果。部署新迁移后需让 Schema 缓存失效(清缓存或重启进程/等待过期)。多实例部署时各实例缓存都要刷新,不能只清一台。
原理流程
- 首次访问表结构时,Schema 层把元数据写入缓存。
- 迁移变更表结构后缓存条目过期或仍在有效期内。
- 未清缓存时,框架按旧元数据组装 SQL 或校验属性。
- 清缓存(或等待 TTL、重启)后重新拉取最新结构。
代码或图示
// 示意:部署后清理 Schema 缓存(具体调用方式以 db 组件缓存 API 为准,待确认)
Yii::$app->db->schema->refresh();
常见误区
- 把 Schema 缓存当成业务缓存去主动预热:它按元数据变更失效,不承担结果缓存职责。
- 只清数据缓存忘记清 Schema 缓存:加列后报“未知属性/未知列”。
追问
- 如何临时关闭 Schema 缓存排查?答:本地调试时关闭 db 组件的 schemaCache 配置,对比是否为缓存过期问题。
- 生产能否直接
refresh()全量 Schema?答:可在部署窗口执行;注意多实例都要刷新,避免部分实例旧缓存。
06.5.3.9-014 多数据库项目如何组织各库迁移?
一句话结论
每个数据库连接对应一个 db 组件 ID,迁移命令通过连接选项选择目标库;模块/业务域可维护独立迁移目录,按库分别执行 up/down,避免一套迁移同时改多个不相关的库。
概念解释
配置中注册多个 db 组件(如 db、dbLog),迁移方法可通过 $this->db 指定连接。命令的 db 选项决定默认连接;跨库迁移需显式拿到对应连接执行命令。分库后历史表分别记录在各自库中,批次号互不影响。
原理流程
components注册多个连接,各有 ID 与连接参数。- 迁移目录按业务域或数据库划分。
- 命令指定 db 组件 ID 与迁移目录执行。
- 各库历史表独立记录版本与批次。
代码或图示
// 迁移内使用指定连接(示意)
$this->db = 'dbLog';
$this->createTable('{{%log_event}}', [
'id' => $this->primaryKey(),
'message' => $this->string(255),
]);
常见误区
- 一个迁移里写跨库外键:分库后物理外键无法跨库约束,关联一致性需应用层保证。
- 迁移目录混放:回滚某库时误执行其他库的结构变更。
追问
- 跨库查询怎么办?答:跨库关联在应用层聚合,或使用只读副本/数仓;不要假设同一实例可跨库 join。
- 模块自带迁移如何随主项目执行?答:把模块迁移目录纳入命令扫描配置,或提供模块专属命令在部署流程中调用。
06.5.3.9-015 迁移与 ActiveRecord 类的字段定义如何保持同步?
一句话结论
迁移是表结构的事实来源;AR 类按表结构声明属性、规则与标签,改表后同步更新 AR 的 rules()、attributeLabels() 与关联定义,避免模型与库结构漂移。
概念解释
AR 不反射全部数据库列做运行时校验,而是在类中显式声明可安全赋值属性与规则。加列后若 AR 规则未包含新列,批量赋值会被过滤;删列后 AR 残留属性会导致查询写入错误。发布顺序建议:先上结构迁移,再上模型代码;回滚时先回代码再回结构。
原理流程
- 迁移定义新列与约束。
- 更新 AR:可安全赋值属性、规则、标签、关联。
- 业务代码使用新字段。
- 旧列废弃时先停止写入与读取,再由后续迁移删除。
代码或图示
// AR 中与新列保持一致的规则片段(示意)
public function rules()
{
return [
[['title', 'status'], 'required'],
['status', 'integer'],
['summary', 'string', 'max' => 500],
];
}
常见误区
- 迁移加列后只改数据库不改 AR:新字段无法批量赋值,表单提交静默丢失。
- 先删列再停代码引用:线上报错“未知列”,发布顺序应反向。
追问
- 模型字段是否需要逐个声明属性?答:AR 映射表列,运行时可读取表元数据;但批量赋值白名单与规则必须在类中显式配置(参见 06.5.3.7-003)。
- 如何发现模型与库结构漂移?答:对比迁移记录与表结构,配合 Gii 重新生成模型检查差异;持续集成中可加结构校验步骤。
06.5.3.9-016 初始数据(种子数据)应该写在迁移里吗?
一句话结论
配置字典、固定枚举对应表等必须随结构存在的基准数据可写在迁移中;业务运营数据、演示数据应走 fixture、数据填充命令或后台录入,不混入结构迁移。
概念解释
迁移中的种子数据要幂等:用条件判断存在性再插入,避免重复执行产生重复行。种子数据不依赖环境差异(如域名、上传路径),环境专属数据走本地配置或填充脚本。3.0 生态中数据填充与迁移职责同样分离,具体工具以对应包为准。
原理流程
- 判断基准数据是否为结构演进的一部分。
- 在迁移
up()中按主键/唯一键条件插入。 down()按需删除对应基准数据。- 环境差异数据不写入迁移。
代码或图示
$exists = (new \yii\db\Query())
->from('{{%dict_status}}')->where(['code' => 'draft'])->exists();
if (!$exists) {
$this->insert('{{%dict_status}}', ['code' => 'draft', 'name' => '草稿']);
}
常见误区
- 迁移里插入账号、配置项等环境敏感数据:多环境数据不一致,回滚也无法清理干净。
- 种子数据不做存在判断:重复执行报唯一键冲突。
追问
- 演示/测试数据放哪里?答:测试用 fixture;本地演示数据用独立控制台命令填充,不进线上迁移流程。
- 基准数据变更怎么改?答:新增迁移做
update或条件插入,不修改历史迁移中的旧数据行。
06.5.3.9-017 为什么已提交的迁移不能再修改?
一句话结论
历史迁移只在未执行的环境重放;已执行环境不会重新运行它,修改文件不会生效,反而造成各环境结构与代码记录不一致,因此修正必须新增迁移。
概念解释
历史表记录已执行版本,命令跳过这些版本。开发者修改旧迁移的 up() 后,本地可能靠 redo 或重建库看到效果,但线上与其他同事环境仍是旧结构。唯一例外是尚未在任何共享环境执行过、且可协调所有人重置本地库的未发布迁移。
原理流程
- 迁移首次在环境执行后写入历史表。
- 后续
up跳过已记录版本。 - 修改旧文件对已部署环境无效。
- 结构错误通过新迁移纠正(补列、改列、删列、补索引)。
代码或图示
错误做法:编辑 m261118_000001_xxx.php 改 up()
正确做法:新增 m261119_000001_fix_xxx.php 描述增量变更
常见误区
- 为了“保持迁移干净”重写旧文件:已部署环境结构与文件脱节。
- 回滚生产旧迁移后修改再重跑:高风险操作,应走备份与新迁移流程。
追问
- 未推送共享仓库的本地迁移能改吗?答:可以,前提是协作者都未执行;推送后即冻结。
- 旧迁移写了错误索引怎么补?答:新增迁移
dropIndex旧索引、createIndex正确索引,并在注释说明原因。
06.5.3.9-018 如何组织模块或扩展自带的迁移?
一句话结论
模块/扩展在自己的目录下维护迁移类与历史表配置,主应用通过命令扫描列表或专属命令执行;模块迁移只改本模块拥有的表,不直接修改其他业务域表结构。
概念解释
模块化项目中,各域迁移目录可独立配置。模块升级时按其迁移记录演进自己的表;跨模块结构变更由上层应用迁移协调。模块迁移的表名同样使用前缀占位,避免与主应用表冲突。
原理流程
- 模块目录放置迁移类与说明。
- 主应用迁移配置纳入模块路径,或提供模块控制台命令。
- 部署时先执行基础模块迁移,再执行业务模块迁移。
- 各模块历史表独立记录版本。
代码或图示
modules/
example/
migrations/
m261119_000001_init_example.php
常见误区
- 模块迁移直接改主应用用户表:边界耦合,模块无法独立升级。
- 模块升级与主应用迁移混在同一目录:回滚与追溯无法按模块拆分。
追问
- 模块表被主应用业务引用怎么办?答:模块对外提供稳定结构与接口;主应用需要扩展字段时通过关联表或自身迁移处理。
- 扩展安装时如何自动建表?答:按扩展约定在安装/升级流程执行其迁移命令,自动行为以扩展文档为准。
06.5.3.9-019 Yii 3.0 的迁移机制与 2.x 有何对照与差异?
一句话结论
3.0 迁移拆到独立数据库类包,迁移类与命令通过容器装配,目录与历史表概念沿用,但类命名空间、基类与命令注册方式与 2.x 不同;具体 API 签名需以 yiisoft/db-migration 包文档为准,标注待确认项不要凭 2.x 记忆照搬。
概念解释
2.x 迁移基类在框架核心命名空间下,命令随控制台应用注册;3.0 按包拆分后,迁移能力属于数据库相关包,应用模板负责把迁移命令接入控制台。迁移“版本记录 + 上下行方法 + 方言抽象”的设计思想延续,但方法签名、配置键与历史表命名可能调整。
原理流程
- 识别项目实际使用的 2.x 维护分支或 3.0 包版本。
- 对照对应文档确认基类命名空间、命令名与配置项。
- 迁移类结构按包要求编写
up/down。 - 不确定的方法签名在最小示例中实测后再写入文档。
代码或图示
2.x:yii\db\Migration + 核心 migrate 命令
3.0:独立迁移包 + 容器装配的命令(具体类名待确认)
常见误区
- 把 2.x 迁移类直接复制到 3.0 项目:命名空间与基类方法可能已变更。
- 凭记忆填写 3.0 配置键:应以当前安装包的官方文档与示例配置为准。
追问
- 如何确认 3.0 迁移包当前 API?答:查看已安装包的
composer.json版本与包内类签名,对照官方文档;本机未装 vendor 时不声称实测结果。 - 迁移思路哪些可复用?答:成对上下行、批次历史、方言抽象、分批回填、不改历史迁移等工程约定在两代之间通用。
06.5.3.9-020 迁移环节有哪些高频踩坑与检查清单?
一句话结论
高频问题集中在:只写上行不写回滚、大表一次性回填、改历史迁移、Schema 缓存未清、跨库假设外键;交付前按“结构可回滚、回填可分批、模型已同步、缓存会刷新、历史不修改”逐项检查。
概念解释
检查清单覆盖:迁移命名与顺序、up/down 对称、类型方言无关、索引外键顺序、回填分批幂等、与 AR 规则同步、多实例缓存刷新、模块边界清晰。涉及不确定的默认值与命令选项,标注待确认并在预发环境验证。
原理流程
- 提交前通读迁移:表名占位、类型方言化、
down对称。 - 评估数据量:大表改结构与回填分批方案。
- 检查模型同步:规则、标签、关联一致。
- 部署流程包含 Schema 缓存刷新步骤。
- 上线后核对历史表批次与表结构一致。
代码或图示
迁移交付检查
[ ] up/down 成对,破坏性变更已注明
[ ] 表名使用 {{%}} 占位,类型方言无关
[ ] 索引/外键顺序在 up 与 down 中对称
[ ] 回填分批、幂等、不依赖请求上下文
[ ] AR 规则与标签已同步
[ ] 部署步骤含 Schema 缓存刷新
[ ] 未修改任何历史迁移
常见误区
- 认为迁移上线一次成功就结束:回滚路径与缓存刷新同样要在发布流程里演练。
- 把性能问题留给事后优化:大表 DDL 与回填必须在设计阶段评估锁与耗时。
追问
- 迁移在 CI 中如何验证?答:用隔离数据库执行
up后再down一轮,验证反向操作可执行;CI 环境数据库类型尽量贴近生产方言。 - 迁移报错中断后怎么恢复?答:先查看历史表已记录到哪个版本,修复迁移问题后从断点继续;已部分执行的 DDL 按方言事务能力评估人工补救。