Class yii\db\Migration

继承yii\db\Migration » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\db\MigrationInterface
Uses Traitsyii\db\SchemaBuilderTrait
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/Migration.php

Migration(迁移) 是表示数据库迁移的基类.

Migration 被设计为与yii migrate命令一起使用.

迁移的每个子类代表一个单独的数据库迁移, 该迁移由子类名称标识.

在每次迁移中, 应重写 up() 方法以包含"upgrading"(升级)数据库的逻辑; 以及包含"downgrading"(降级)逻辑的 down() 方法. yii migrate命令管理应用程序中的所有可用迁移.

如果数据库支持事务处理, 则还可以重写 safeUp()safeDown(), 以便在升级或降级过程中如果发生任何错误, 可以整体还原整个迁移.

Note: 某些 DBMS 中的某些 DB 查询无法放入事务中. 有关这些示例, 请参阅 implicit commit. 如果是这种情况, 你仍然应该改为实现up()down().

Migration 提供了一套方便的方法来处理数据库数据和结构. 例如, insert() 方法可用于将一行数据轻松插入到数据库表中; createTable() 方法可用于创建数据库表. 与 yii\db\Command 中的相同方法相比, 这些方法将显示额外的信息, 这些信息显示了方法参数和执行时间, 这在应用迁移时可能很有用.

有关 Migration 的更多详细信息和用法信息, 请参阅 guide article on Migration.

公共属性

隐藏继承的属性

属性类型描述定义在
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$compact boolean 指示是否应压缩控制台输出. yii\db\Migration
$db yii\db\Connection|array|string 此迁移应使用的数据库连接对象或数据库连接的应用程序组件标识. yii\db\Migration
$maxSqlOutputLength integer SQL 输出的最大字符数. yii\db\Migration

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
addColumn() 构建并执行一条添加新列的 SQL 语句. yii\db\Migration
addCommentOnColumn() 构建并执行一条 SQL 语句, 以便为列添加注释. yii\db\Migration
addCommentOnTable() 构建一条 SQL 语句, 为表添加注释. yii\db\Migration
addForeignKey() 构建用于将外键约束添加到指定表的 SQL 语句. yii\db\Migration
addPrimaryKey() 构建并执行一条用于创建主键的 SQL 语句. yii\db\Migration
alterColumn() 构建并执行一条更改列定义的 SQL 语句. yii\db\Migration
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
batchInsert() 创建并执行批处理 INSERT SQL 语句. yii\db\Migration
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
bigInteger() 创建一个 bigint 列. yii\db\SchemaBuilderTrait
bigPrimaryKey() 创建一个大的主键列. yii\db\SchemaBuilderTrait
binary() 创建一个 binary 列. yii\db\SchemaBuilderTrait
boolean() 创建一个 boolean 列. yii\db\SchemaBuilderTrait
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
char() 创建一个 char 列. yii\db\SchemaBuilderTrait
className() 返回此类的完全限定名称. yii\base\BaseObject
createIndex() 构建并执行一条用于创建新索引的 SQL 语句. yii\db\Migration
createTable() 构建并执行一条用于创建新的数据库表的 SQL 语句. yii\db\Migration
date() 创建一个 date 列. yii\db\SchemaBuilderTrait
dateTime() 创建一个 datetime 列. yii\db\SchemaBuilderTrait
decimal() 创建一个 decimal 列. yii\db\SchemaBuilderTrait
delete() 创建并执行 DELETE SQL 语句. yii\db\Migration
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
double() 创建一个 double 列. yii\db\SchemaBuilderTrait
down() 此方法包含删除此迁移时要执行的逻辑. yii\db\Migration
dropColumn() 构建并执行一条删除列的 SQL 语句. yii\db\Migration
dropCommentFromColumn() 构建并执行 SQL 语句, 以便从列中删除注释. yii\db\Migration
dropCommentFromTable() 构建用于从表中删除注释的 SQL 语句. yii\db\Migration
dropForeignKey() 构建用于删除外键约束的 SQL 语句. yii\db\Migration
dropIndex() 构建并执行一条用于删除索引的 SQL 语句. yii\db\Migration
dropPrimaryKey() 构建并执行一条用于删除主键的 SQL 语句. yii\db\Migration
dropTable() 构建并执行一条用于删除数据库表的 SQL 语句. yii\db\Migration
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
execute() 执行一条 SQL 语句. yii\db\Migration
float() 创建一个 float 列. yii\db\SchemaBuilderTrait
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化迁移. yii\db\Migration
insert() 创建并执行 INSERT SQL 语句. yii\db\Migration
integer() 创建一个 integer 列. yii\db\SchemaBuilderTrait
json() 创建一个 JSON 列. yii\db\SchemaBuilderTrait
money() 创建一个 money 列. yii\db\SchemaBuilderTrait
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
primaryKey() 创建一个主键列. yii\db\SchemaBuilderTrait
renameColumn() 构建并执行一条用于重命名列的 SQL 语句. yii\db\Migration
renameTable() 构建并执行一条用于重命名数据库表的 SQL 语句. yii\db\Migration
safeDown() 此方法包含删除此迁移时要执行的逻辑. yii\db\Migration
safeUp() 此方法包含应用此迁移时要执行的逻辑. yii\db\Migration
smallInteger() 创建一个 smallint 列. yii\db\SchemaBuilderTrait
string() 创建一个 string 列. yii\db\SchemaBuilderTrait
text() 创建一个 text 列. yii\db\SchemaBuilderTrait
time() 创建一个 time 列. yii\db\SchemaBuilderTrait
timestamp() 创建一个 timestamp 列. yii\db\SchemaBuilderTrait
tinyInteger() 创建一个 tinyint 列. 如果 DBMS 不支持 tinyint, 则将使用 smallint. yii\db\SchemaBuilderTrait
trigger() 触发事件. yii\base\Component
truncateTable() 构建并执行一条清空表数据的 SQL 语句. yii\db\Migration
up() 此方法包含应用此迁移时要执行的逻辑. yii\db\Migration
update() 创建并执行 DELETE SQL 语句. yii\db\Migration
upsert() 创建并执行命令以将行插入到数据库表(如果不存在)(匹配唯一约束), 或者更新行(如果存在). yii\db\Migration

受保护的方法

隐藏继承的方法

方法描述定义在
beginCommand() 准备要执行的命令, 并输出到控制台. yii\db\Migration
endCommand() 在执行名完成后, 并将经过的时间输出到控制台. yii\db\Migration
getDb() yii\db\Migration

属性详情

$compact public 属性 (可用自版本: 2.0.13)

指示是否应压缩控制台输出. 如果将其设置为true, 则迁移中运行的单个命令将不会输出到控制台. 默认为false, 换句话说, 默认情况下输出为完整信息.

public boolean $compact false
$db public 属性

此迁移应使用的数据库连接对象或数据库连接的应用程序组件标识. 从版本2.0.2开始, 这也可以是用于创建对象的配置数组.

Note: 当通过migrate命令创建迁移对象时, 该属性将被命令覆盖. 如果你不想使用该命令提供的数据库连接, 则可以像下面那样重写 init() 方法:

public function init()
{
    $this->db = 'db2';
    parent::init();
}
$maxSqlOutputLength public 属性 (可用自版本: 2.0.13)

SQL 输出的最大字符数. 对于减少长语句和使控制台输出更紧凑很有用.

方法详情

addColumn() public 方法

构建并执行一条添加新列的 SQL 语句.

public void addColumn ( $table, $column, $type )
$table string

新列将添加到的表. 该方法将正确的引用表名.

$column string

新列的名称. 该方法将正确引用该名称.

$type string

列类型. 将调用 yii\db\QueryBuilder::getColumnType() 方法将抽象列类型(如果有)转换为实际类型. 任何未被识别为抽象类型的内容都将保留在生成的 SQL 中. 例如, string将变为varchar(255), 而string not null将变为varchar(255) not null.

addCommentOnColumn() public 方法 (可用自版本: 2.0.8)

构建并执行一条 SQL 语句, 以便为列添加注释.

public void addCommentOnColumn ( $table, $column, $comment )
$table string

要对其列进行注释的表. 该方法将正确的引用表名.

$column string

要注释的列的名称. 该方法将正确的引用列名.

$comment string

要添加的注释文本. 该方法将正确引用该注释.

addCommentOnTable() public 方法 (可用自版本: 2.0.8)

构建一条 SQL 语句, 为表添加注释.

public void addCommentOnTable ( $table, $comment )
$table string

要添加注释的表. 该方法将正确的引用表名.

$comment string

要添加的注释文本. 该方法将正确引用该注释.

addForeignKey() public 方法

构建用于将外键约束添加到指定表的 SQL 语句.

该方法将正确引用表名和列名.

public void addForeignKey ( $name, $table, $columns, $refTable, $refColumns, $delete null, $update null )
$name string

外键约束的名称.

$table string

外键约束将被添加到的表.

$columns string|array

将约束添加到的列名称. 如果有多个列, 请用逗号分隔或使用数组.

$refTable string

外键引用的表.

$refColumns string|array

外键引用的列名称. 如果有多个列, 请用逗号分隔或使用数组.

$delete string

ON DELETE 选项. 大多数 DBMS 支持以下选项: RESTRICT, CASCADE, NO ACTION, SET DEFAULT, SET NULL

$update string

ON UPDATE 选项. 大多数 DBMS 支持以下选项: RESTRICT, CASCADE, NO ACTION, SET DEFAULT, SET NULL

addPrimaryKey() public 方法

构建并执行一条用于创建主键的 SQL 语句.

该方法将正确引用表名和列名.

public void addPrimaryKey ( $name, $table, $columns )
$name string

主键约束的名称.

$table string

主键约束将添加到的表.

$columns string|array

主键字段, 用逗号分隔的字符串或列数组.

alterColumn() public 方法

构建并执行一条更改列定义的 SQL 语句.

public void alterColumn ( $table, $column, $type )
$table string

要更改其列的表. 该方法将正确的引用表名.

$column string

要更改的列名称. 该方法将正确引用该名称.

$type string

新的列类型. 将调用 yii\db\QueryBuilder::getColumnType() 方法将抽象列类型(如果有)转换为实际类型. 任何未被识别为抽象类型的内容都将保留在生成的 SQL 中. 例如, string将变为varchar(255), 而string not null将变为varchar(255) not null.

batchInsert() public 方法

创建并执行批处理 INSERT SQL 语句.

该方法将正确的转义列名, 并绑定要插入的值.

public void batchInsert ( $table, $columns, $rows )
$table string

新行将插入的表.

$columns array

列名列表.

$rows array

要批量插入到表中的行.

beginCommand() protected 方法 (可用自版本: 2.0.13)

准备要执行的命令, 并输出到控制台.

protected float beginCommand ( $description )
$description string

命令的描述, 将输出到控制台.

return float

执行命令之前的时间, 用于计算经过的时间.

createIndex() public 方法

构建并执行一条用于创建新索引的 SQL 语句.

public void createIndex ( $name, $table, $columns, $unique false )
$name string

索引名称. 该方法将正确引用该名称.

$table string

将为其创建新索引的表. 该方法将正确的引用表名.

$columns string|array

索引中应包含的列. 如果有多个列, 请用逗号分隔或使用数组. 该方法将正确引用每个列名. 对于包含左括号(的列名, 将跳过引用.

$unique boolean

是否在创建的索引上添加 UNIQUE 约束.

createTable() public 方法

构建并执行一条用于创建新的数据库表的 SQL 语句.

新表中的列应指定为name-definition对(eg. 'name' => 'string'), 其中name表示将由方法正确引用的列名, 而definition表示列类型, 可以包含抽象的数据库类型.

将调用 yii\db\QueryBuilder::getColumnType() 方法以将任何抽象类型转换为实际类型.

如果仅使用定义来指定列(eg. PRIMARY KEY (name, type)), 则该列将直接放入生成的 SQL 中.

public void createTable ( $table, $columns, $options null )
$table string

要创建的表的名称. 该方法将正确引用该名称.

$columns array

新表中的列定义(name => definition).

$options string

将附加到生成的 SQL 的其它 SQL 片段.

delete() public 方法

创建并执行 DELETE SQL 语句.

public void delete ( $table, $condition '', $params = [] )
$table string

将从中删除数据的表.

$condition array|string

将在 WHERE 部分放置的条件. 有关如何执行条件的信息, 请参阅 yii\db\Query::where().

$params array

要绑定到查询的参数.

down() public 方法

此方法包含删除此迁移时要执行的逻辑.

默认实现会抛出一个异常, 指示无法删除迁移. 如果可以删除相应的迁移, 则子类可能会重写此方法.

public boolean down ( )
return boolean

返回一个false值来表示迁移失败, 因此不应继续进行. 所有其它返回值表示迁移成功.

dropColumn() public 方法

构建并执行一条删除列的 SQL 语句.

public void dropColumn ( $table, $column )
$table string

要删除其列的表名. 该方法将正确引用该名称.

$column string

要删除的列的名称. 该方法将正确引用该名称.

dropCommentFromColumn() public 方法 (可用自版本: 2.0.8)

构建并执行 SQL 语句, 以便从列中删除注释.

public void dropCommentFromColumn ( $table, $column )
$table string

要对其列进行注释的表. 该方法将正确的引用表名.

$column string

要注释的列的名称. 该方法将正确的引用列名.

dropCommentFromTable() public 方法 (可用自版本: 2.0.8)

构建用于从表中删除注释的 SQL 语句.

public void dropCommentFromTable ( $table )
$table string

要对其列进行注释的表. 该方法将正确的引用表名.

dropForeignKey() public 方法

构建用于删除外键约束的 SQL 语句.

public void dropForeignKey ( $name, $table )
$name string

要删除的外键约束的名称. 该方法将正确引用该名称.

$table string

要删除其外键约束的表. 该方法将正确引用该名称.

dropIndex() public 方法

构建并执行一条用于删除索引的 SQL 语句.

public void dropIndex ( $name, $table )
$name string

要删除的索引名称. 该方法将正确引用该名称.

$table string

要删除其索引的表. 该方法将正确引用该名称.

dropPrimaryKey() public 方法

构建并执行一条用于删除主键的 SQL 语句.

public void dropPrimaryKey ( $name, $table )
$name string

要删除的主键约束的名称.

$table string

将要从中删除主键约束的表.

dropTable() public 方法

构建并执行一条用于删除数据库表的 SQL 语句.

public void dropTable ( $table )
$table string

要删除的表. 该方法将正确引用该名称.

endCommand() protected 方法 (可用自版本: 2.0.13)

在执行名完成后, 并将经过的时间输出到控制台.

protected void endCommand ( $time )
$time float

命令执行前的时间.

execute() public 方法

执行一条 SQL 语句.

此方法使用 $db 执行指定的 SQL 语句.

public void execute ( $sql, $params = [] )
$sql string

要执行的 SQL 语句.

$params array

SQL 执行的输入参数(name => value). 有关更多详细信息, 请参阅 yii\db\Command::execute().

getDb() protected 方法 (可用自版本: 2.0.6)

protected void getDb ( )
init() public 方法

初始化迁移.

如果为null, 则该方法将把 $db 设置成应用程序db组件.

public void init ( )
insert() public 方法

创建并执行 INSERT SQL 语句.

该方法将正确的转义列名, 并绑定要插入的值.

public void insert ( $table, $columns )
$table string

新行将插入的表.

$columns array

要插入到表中的列数据(name => value).

renameColumn() public 方法

构建并执行一条用于重命名列的 SQL 语句.

public void renameColumn ( $table, $name, $newName )
$table string

要重命名其列的表. 该方法将正确引用该名称.

$name string

列的旧名称. 该方法将正确引用该名称.

$newName string

列的新名称. 该方法将正确引用该名称.

renameTable() public 方法

构建并执行一条用于重命名数据库表的 SQL 语句.

public void renameTable ( $table, $newName )
$table string

要重命名的表. 该方法将正确引用该名称.

$newName string

新表名. 该方法将正确引用该名称.

safeDown() public 方法

此方法包含删除此迁移时要执行的逻辑.

此方法与 down() 的不同之处在于, 此处实现的 DB 逻辑将包含在数据库事务中. 如果 DB 逻辑需要在事务内, 则子类可以实现此方法, 而不是 down().

Note: 并非所有的 DBMS 都支持事务. 而且某些 DB 查询无法放入事务中. 有关某些示例, 请参考 implicit commit.

public boolean safeDown ( )
return boolean

返回一个false值来表示迁移失败, 因此不应继续进行. 所有其它返回值表示迁移成功.

safeUp() public 方法

此方法包含应用此迁移时要执行的逻辑.

此方法与 up() 的不同之处在于, 此处实现的 DB 逻辑将包含在数据库事务中. 如果 DB 逻辑需要在事务内, 则子类可以实现此方法, 而不是 up().

Note: 并非所有的 DBMS 都支持事务. 而且某些 DB 查询无法放入事务中. 有关某些示例, 请参考 implicit commit.

public boolean safeUp ( )
return boolean

返回一个false值来表示迁移失败, 因此不应继续进行. 所有其它返回值表示迁移成功.

truncateTable() public 方法

构建并执行一条清空表数据的 SQL 语句.

public void truncateTable ( $table )
$table string

要清空的表. 该方法将正确引用该名称.

up() public 方法

此方法包含应用此迁移时要执行的逻辑.

子类可以重写此方法以提供实际的迁移逻辑.

public boolean up ( )
return boolean

返回一个false值来表示迁移失败, 因此不应继续进行. 所有其它返回值表示迁移成功.

update() public 方法

创建并执行 DELETE SQL 语句.

该方法将正确转义列名称并绑定要更新的值.

public void update ( $table, $columns, $condition '', $params = [] )
$table string

要更新的表.

$columns array

要更新的列数据(name => value).

$condition array|string

将在 WHERE 部分放置的条件. 有关如何执行条件的信息, 请参阅 yii\db\Query::where().

$params array

要绑定到查询的参数.

upsert() public 方法 (可用自版本: 2.0.14)

创建并执行命令以将行插入到数据库表(如果不存在)(匹配唯一约束), 或者更新行(如果存在).

该方法将正确的转义列名, 并绑定要插入的值.

public $this upsert ( $table, $insertColumns, $updateColumns true, $params = [] )
$table string

新行将插入/更新的表.

$insertColumns array|yii\db\Query

要插入到表中的列数据(name => value), 或执行 INSERT INTO ... SELECT SQL 语句的 yii\db\Query 示例.

$updateColumns array|boolean

如果已存在, 要更新的列数据(name => value). 如果设置为true, 则列数据将被更新以匹配插入列数据. 如果设置为false, 则如果列数据已经存在, 将不执行任何更新.

$params array

要绑定到命令的参数.

return $this

迁移对象本身.