罗罗编程学习记录
本页内容 展开查看

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 脚本的区别在于:版本顺序集中管理、可回滚、可在部署流水线中自动执行。

原理流程

  1. 开发者用 migrate/create 生成迁移类模板,填写 up()/down()。
  2. 提交后团队成员执行 migrate/up,命令读取历史表,依次执行未记录的迁移。
  3. 每个迁移成功后向历史表写入版本号与批次号。
  4. 需要回滚时执行 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() 中放弃反向恢复,要么通过备份表保留数据后再回滚,需在注释中说明不可回滚的原因。

原理流程

  1. up() 调用基类提供的 Schema 方法执行 DDL 或数据更新。
  2. 命令校验 up() 返回成功(无异常、返回值不为 false 时视为成功)。
  3. 回滚时命令按批次逆序调用 down()。
  4. 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 等具体类型。

原理流程

  1. 迁移方法接收表名、列定义、索引名等参数。
  2. 方法生成 yii\db\Command,交由当前 db 组件的 Schema 构建方言 SQL。
  3. 通过事务执行命令(是否包裹事务见 06.5.3.9-005)。
  4. 命令执行成功后迁移继续下一步。

代码或图示

$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 表名声明、查询中应统一使用占位写法,避免硬编码前缀。

原理流程

  1. 写迁移时使用 {{%example}} 占位。
  2. Schema 层读取 db 组件的 tablePrefix。
  3. 占位符替换为物理表名,并用当前方言的标识符引号包裹。
  4. 最终 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 语句会隐式提交,失败后无法靠事务撤销。

原理流程

  1. 命令开始执行单个迁移类前尝试开启事务。
  2. up() 内 DML 与可事务化的 DDL 随事务提交或回滚。
  3. 遇到隐式提交的 DDL 后,事务边界被数据库打破。
  4. 回滚命令对不可事务化 DDL 无能为力,只能靠 down() 显式反向操作或备份恢复。

代码或图示

事务边界(可回滚范围)
  数据更新 DML            —— 事务可回滚
  PostgreSQL DDL          —— 事务可回滚
  MySQL 多数 DDL          —— 隐式提交,事务不可回滚
  数据删除/截断           —— 需备份表兜底

常见误区

  • 以为开了事务,加列失败就一定自动还原:MySQL 隐式提交后部分结构改动已经落库。
  • 把大表 DDL 放进迁移事务长时间持有锁:应结合在线变更策略评估锁与耗时。

追问

  • 如何确认当前方言 DDL 事务行为?答:对照数据库官方文档的 DDL 事务支持说明,并在预发环境用测试库验证 down() 结果。
  • 大表加列怎么办?答:评估锁表时间与在线 DDL 工具,必要时分步加列、回填、双写过渡,不要假设迁移事务能保护线上大表。

06.5.3.9-006 迁移历史表记录了哪些信息?

一句话结论

历史表保存已执行迁移的版本号(迁移类名/前缀)、所属批次号与应用时间;命令据此判断哪些迁移未执行、回滚时按批次定位逆序集合。

概念解释

默认历史表名(如 migration,具体名称可在迁移控制器配置中覆盖,待确认)通常含字段:版本(字符串,唯一)、批次(整数)、应用时间戳。批次号把同一次 up 执行的多个迁移归为一组,down 按最近整批回滚,保证回滚边界与发布批次一致。

原理流程

  1. 迁移成功后向历史表插入一行:版本号、批次号、时间。
  2. 下次 up 时扫描迁移目录,与历史表比对出未记录版本。
  3. down 读取最大批次号对应的全部版本。
  4. 逆序调用这些版本的 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 成对逻辑是否正确。命令还支持指定目标版本、限制数量等选项,具体选项名以当前版本命令帮助为准。

原理流程

  1. up:扫描目录 → 比对历史表 → 按版本顺序执行 up()。
  2. down:取最近批次(或 -n 指定数量)→ 逆序执行 down()。
  3. redo:对最近批次先执行 down() 再执行 up()。
  4. 每步成功后更新历史表。

代码或图示

# 典型控制台调用(命令名称以框架安装的命令注册为准)
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,类名与文件名对应。时间戳前缀保证多人并行开发时迁移顺序可排序;提交到仓库后,历史顺序以文件前缀与历史表记录为准。已被环境执行过的迁移不得再修改内容。

原理流程

  1. 执行 create 命令并给出描述(如 create_example_table)。
  2. 生成器按当前时间生成前缀与类骨架。
  3. 开发者填写 up()/down() 与必要的数据回填。
  4. 提交后由 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 以类型映射表为准。

原理流程

  1. 迁移方法调用类型表达式构造类型对象。
  2. Schema 层读取当前方言的 typeMap。
  3. 按方言把类型对象转成物理类型字符串。
  4. 拼接长度、精度、正负号、默认值等子句生成 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) 生成索引;唯一索引保证列组合不重复。组合索引遵循最左前缀原则,字段顺序要与高频查询的等值条件、排序方向匹配。索引应随表结构变更一起进迁移,避免线上手工补索引遗漏。

原理流程

  1. 在 up() 中写 createIndex() 并给出索引名与列数组。
  2. 回滚时在 down() 调用 dropIndex($name, $table) 对称删除。
  3. Schema 层生成方言索引 DDL。
  4. 索引随表一起纳入版本控制。

代码或图示

$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(),顺序与正向相反。是否启用物理外键取决于团队约定:高并发分库场景常由应用层维护关联一致性。

原理流程

  1. 父子表都已在迁移中创建。
  2. 调用 addForeignKey() 生成外键约束。
  3. down() 先删外键,再按逆序删表。
  4. 数据库校验参照完整性,违反约束时写入被拒绝。

代码或图示

$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 ... 小批量推进,每批提交;大批量回填配合只读窗口或在线工具。回填逻辑要幂等,重复执行不产生错误结果。

原理流程

  1. 结构迁移先上线:加列、加索引,允许旧代码写入。
  2. 数据迁移按批次扫描主键区间,逐批更新。
  3. 每批记录进度(或靠可重跑的 WHERE 条件保证幂等)。
  4. 回填完成后再在后续迁移中收紧非空约束或切换默认值。

代码或图示

$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 缓存失效(清缓存或重启进程/等待过期)。多实例部署时各实例缓存都要刷新,不能只清一台。

原理流程

  1. 首次访问表结构时,Schema 层把元数据写入缓存。
  2. 迁移变更表结构后缓存条目过期或仍在有效期内。
  3. 未清缓存时,框架按旧元数据组装 SQL 或校验属性。
  4. 清缓存(或等待 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 选项决定默认连接;跨库迁移需显式拿到对应连接执行命令。分库后历史表分别记录在各自库中,批次号互不影响。

原理流程

  1. components 注册多个连接,各有 ID 与连接参数。
  2. 迁移目录按业务域或数据库划分。
  3. 命令指定 db 组件 ID 与迁移目录执行。
  4. 各库历史表独立记录版本与批次。

代码或图示

// 迁移内使用指定连接(示意)
$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 残留属性会导致查询写入错误。发布顺序建议:先上结构迁移,再上模型代码;回滚时先回代码再回结构。

原理流程

  1. 迁移定义新列与约束。
  2. 更新 AR:可安全赋值属性、规则、标签、关联。
  3. 业务代码使用新字段。
  4. 旧列废弃时先停止写入与读取,再由后续迁移删除。

代码或图示

// 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 生态中数据填充与迁移职责同样分离,具体工具以对应包为准。

原理流程

  1. 判断基准数据是否为结构演进的一部分。
  2. 在迁移 up() 中按主键/唯一键条件插入。
  3. down() 按需删除对应基准数据。
  4. 环境差异数据不写入迁移。

代码或图示

$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 或重建库看到效果,但线上与其他同事环境仍是旧结构。唯一例外是尚未在任何共享环境执行过、且可协调所有人重置本地库的未发布迁移。

原理流程

  1. 迁移首次在环境执行后写入历史表。
  2. 后续 up 跳过已记录版本。
  3. 修改旧文件对已部署环境无效。
  4. 结构错误通过新迁移纠正(补列、改列、删列、补索引)。

代码或图示

错误做法:编辑 m261118_000001_xxx.php 改 up()
正确做法:新增 m261119_000001_fix_xxx.php 描述增量变更

常见误区

  • 为了“保持迁移干净”重写旧文件:已部署环境结构与文件脱节。
  • 回滚生产旧迁移后修改再重跑:高风险操作,应走备份与新迁移流程。

追问

  • 未推送共享仓库的本地迁移能改吗?答:可以,前提是协作者都未执行;推送后即冻结。
  • 旧迁移写了错误索引怎么补?答:新增迁移 dropIndex 旧索引、createIndex 正确索引,并在注释说明原因。

06.5.3.9-018 如何组织模块或扩展自带的迁移?

一句话结论

模块/扩展在自己的目录下维护迁移类与历史表配置,主应用通过命令扫描列表或专属命令执行;模块迁移只改本模块拥有的表,不直接修改其他业务域表结构。

概念解释

模块化项目中,各域迁移目录可独立配置。模块升级时按其迁移记录演进自己的表;跨模块结构变更由上层应用迁移协调。模块迁移的表名同样使用前缀占位,避免与主应用表冲突。

原理流程

  1. 模块目录放置迁移类与说明。
  2. 主应用迁移配置纳入模块路径,或提供模块控制台命令。
  3. 部署时先执行基础模块迁移,再执行业务模块迁移。
  4. 各模块历史表独立记录版本。

代码或图示

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 按包拆分后,迁移能力属于数据库相关包,应用模板负责把迁移命令接入控制台。迁移“版本记录 + 上下行方法 + 方言抽象”的设计思想延续,但方法签名、配置键与历史表命名可能调整。

原理流程

  1. 识别项目实际使用的 2.x 维护分支或 3.0 包版本。
  2. 对照对应文档确认基类命名空间、命令名与配置项。
  3. 迁移类结构按包要求编写 up/down。
  4. 不确定的方法签名在最小示例中实测后再写入文档。

代码或图示

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 规则同步、多实例缓存刷新、模块边界清晰。涉及不确定的默认值与命令选项,标注待确认并在预发环境验证。

原理流程

  1. 提交前通读迁移:表名占位、类型方言化、down 对称。
  2. 评估数据量:大表改结构与回填分批方案。
  3. 检查模型同步:规则、标签、关联一致。
  4. 部署流程包含 Schema 缓存刷新步骤。
  5. 上线后核对历史表批次与表结构一致。

代码或图示

迁移交付检查
[ ] up/down 成对,破坏性变更已注明
[ ] 表名使用 {{%}} 占位,类型方言无关
[ ] 索引/外键顺序在 up 与 down 中对称
[ ] 回填分批、幂等、不依赖请求上下文
[ ] AR 规则与标签已同步
[ ] 部署步骤含 Schema 缓存刷新
[ ] 未修改任何历史迁移

常见误区

  • 认为迁移上线一次成功就结束:回滚路径与缓存刷新同样要在发布流程里演练。
  • 把性能问题留给事后优化:大表 DDL 与回填必须在设计阶段评估锁与耗时。

追问

  • 迁移在 CI 中如何验证?答:用隔离数据库执行 up 后再 down 一轮,验证反向操作可执行;CI 环境数据库类型尽量贴近生产方言。
  • 迁移报错中断后怎么恢复?答:先查看历史表已记录到哪个版本,修复迁移问题后从断点继续;已部分执行的 DDL 按方言事务能力评估人工补救。