YII 类库手册
> YII 类库手册 > CDbMigration
包 system.db
继承 abstract class CDbMigration » CComponent
源自 1.1.6
版本 $Id: CDbMigration.PHP 3514 2011-12-27 20:28:26Z alexander.makarow $
源码
CDbMigration是表示一个数据库迁移的基类。

CDbMigration被设计为和“yiic migrate”命令一起使用。

每一个 CDbMigration 的子类表示一个单个数据库迁移， 它通过子类名称识别。

在每一个迁移内部， up 方法包含了 "upgrading"逻辑 在应用程序中使用数据库；当 down 方法包含 "downgrading" 逻辑时。 "yiic migrate" 命令管理在一个应用程序中所有可用的迁移。

CDbMigration提供了一套便利的方法来操纵数据库数据和schema。 例如，insert 方法能很容易的在一个数据库表中插入一行数据。 createTable 方法能用作创建一个数据库。 和CDbCommand中的相同方法比较，这些方法将显示附加信息, 如方法参数和执行时间， 它们在应用迁移时是非常有用的。

公共属性

属性 类型 描述 定义在
dbConnection CDbConnection 返回当前活动的数据库连接。 CDbMigration

公共方法

方法 描述 定义在
__call() 如果类中没有调的方法名，则调用这个方法。 CComponent
__get() 返回一个属性值、一个事件处理程序列表或一个行为名称。 CComponent
__isset() 检查一个属性是否为null。 CComponent
__set() 设置一个组件的属性值。 CComponent
__unset() 设置一个组件的属性为null。 CComponent
addColumn() 建立并执行一条sql语句为增加一个新的数据库列。 CDbMigration
addForeignKey() 建立一个SQL语句添加到现有表的一个外键约束。 CDbMigration
alterColumn() 建立并执行一条SQL语句为改变一个列的定义。 CDbMigration
asa() 返回这个名字的行为对象。 CComponent
attachBehavior() 附加一个行为到组件。 CComponent
attachBehaviors() 附加一个行为列表到组件。 CComponent
attachEventHandler() 为事件附加一个事件处理程序。 CComponent
canGetProperty() 确定属性是否可读。 CComponent
canSetProperty() 确定属性是否可写。 CComponent
createIndex() 建立并执行SQL语句为创建新的索引。 CDbMigration
createTable() 建立并执行一条SQL语句为插入一条新的数据表。 CDbMigration
delete() 创建和执行一条 DELETE SQL 语句。 CDbMigration
detachBehavior() 从组件中分离一个行为。 CComponent
detachBehaviors() 从组件中分离所有行为。 CComponent
detachEventHandler() 分离一个存在的事件处理程序。 CComponent
disableBehavior() 禁用一个附加行为。 CComponent
disableBehaviors() 禁用组件附加的所有行为。 CComponent
down() 当删除此迁移时，此方法包含要执行的逻辑。 CDbMigration
dropColumn() 创建并执行一条SQL语句为删除一个数据库列。 CDbMigration
dropForeignKey() 建立一条SQL语句为删除外键约束。 CDbMigration
dropIndex() 建立并执行一条删除一条SQL索引的语句。 CDbMigration
dropTable() 建立并执行一条SQL语句为删除一个数据库表。 CDbMigration
enableBehavior() 启用一个附加行为。 CComponent
enableBehaviors() 启用组件附加的所有行为。 CComponent
evaLuateExpression() 计算一个PHP表达式，或根据组件上下文执行回调。 CComponent
execute() 执行一条SQL语句。 CDbMigration
getDbConnection() 返回当前活动的数据库连接。 CDbMigration
getEventHandlers() 返回一个事件的附加处理程序列表。 CComponent
hasEvent() 确定一个事件是否定义。 CComponent
hasEventHandler() 检查事件是否有附加的处理程序。 CComponent
hasProperty() 确定属性是否被定义。 CComponent
insert() 创建和执行一条 INSERT SQL 语句。 CDbMigration
raiseEvent() 发起一个事件。 CComponent
refreshTableSchema() 刷新架构缓存表。 CDbMigration
renameColumn() 建立并执行一条SQL语句为重命名一列。 CDbMigration
renameTable() 建立并执行一条SQL语句为重命名数据表。 CDbMigration
safeDown() 当删除此迁移时，此方法包含要执行的逻辑。 CDbMigration
safeUp() 当应用此迁移时，此方法包含要执行的逻辑。 CDbMigration
setDbConnection() 设置当前活动的数据库连接。 CDbMigration
truncateTable() 建立并执行SQL语句为截断一个数据库表。 CDbMigration
up() 当应用此迁移时，此方法包含要执行的逻辑。 CDbMigration
update() 创建和执行一条 UPDATE SQL 语句。 CDbMigration

属性详细

dbConnection 属性
public CDbConnection getDbConnection()
public void setDbConnection(CDbConnection $db)

返回当前活动的数据库连接。 默认情况下，‘db’的应用组件将返回并激活。 你能调用 setDbConnection 切换到一个不同的数据库连接。 方法如 insert, createTable 将使用这个数据库连接 去执行DB查询。

方法详细

addColumn() 方法
public void addColumn(string $table, string $column, string $type)
$table string 新列将被增加到的表。该表名会被此方法恰当的引用。
$column string 新列的名称。该名称会被此方法恰当的引用。
$type string 表类型。 getColumnType 方法将被触发转换抽象类型（若有）为实际类型。 任何无法识别为抽象类型将被保存在生成的SQL中。 例如, ‘string’将被转换成‘varchar(255)’，同时‘string not null’将变成‘varchar(255) not null’。 

public function addColumn($table, $column, $type)
{
    echo "    > add column $column $type to table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->addColumn($table, $column, $type);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为增加一个新的数据库列。

addForeignKey() 方法
public void addForeignKey(string $name, string $table, string $columns, string $refTable, string $refColumns, string $delete=NULL, string $update=NULL)
$name string 外键约束的名称。
$table string 外键约束被添加到的表。
$columns string 约束将被增加到的列的名称。如果有多个列用逗号分开它们。
$refTable string 外键引用的表。
$refColumns string 该外键引用的列的名称。如果有多个列用逗号分开它们。
$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 

public function addForeignKey($name, $table, $columns, $refTable, $refColumns, $delete=null, $update=null)
{
    echo "    > add foreign key $name: $table ($columns) references $refTable ($refColumns) ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->addForeignKey($name, $table, $columns, $refTable, $refColumns, $delete, $update);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立一个SQL语句添加到现有表的一个外键约束。 该方法将正确引用表和列的名称。

alterColumn() 方法
public void alterColumn(string $table, string $column, string $type)
$table string 要被改变的表的名称。该表名会被此方法恰当的引用。
$column string 要被改变的列的名称。该名称会被此方法恰当的引用。
$type string 新列的类型。 getColumnType 方法将被触发转换抽象类型（若有）为实际类型。 任何无法识别为抽象类型将被保存在生成的SQL中。 例如，‘string’将这成‘varchar(255)’，同时‘string not null’将变成‘varchar(255) not null’。 

public function alterColumn($table, $column, $type)
{
    echo "    > alter column $column in table $table to $type ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->alterColumn($table, $column, $type);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为改变一个列的定义。

createIndex() 方法
public void createIndex(string $name, string $table, string $column, boolean $unique=false)
$name string 索引名称. 该名称会被此方法恰当的引用。
$table string 要为其创建新索引的表。该表名将会被此方法恰当的引用。
$column string 该列（或多列）将被包含在索引中。如果有多列请用逗号分开它们。 该列名将会被此方法恰当的引用。
$unique boolean 是否在创建的索引中增加 UNIQUE 约束。 

public function createIndex($name, $table, $column, $unique=false)
{
    echo "    > create".($unique ? ' unique':'')." index $name on $table ($column) ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->createIndex($name, $table, $column, $unique);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行SQL语句为创建新的索引。

createTable() 方法
public void createTable(string $table, array $columns, string $options=NULL)
$table string 要创建的表的名称。此名称将被此方法恰当的引用。
$columns array 新表中的列 (name=>definition) 。
$options string 附加的SQL片段，将被附加到生成的SQL。 

public function createTable($table, $columns, $options=null)
{
    echo "    > create table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->createTable($table, $columns, $options);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为插入一条新的数据表。

新表的列应该定义名称对(例如 'name'=>'string'), 这里 name 代表一个列名，它将被此方法恰当的引用，definition 代表列的类型，它包含一个抽象的数据库类型。 getColumnType 方法将被触发转换任何抽象类型为实际类型。

如果一个列的指定仅带有 (例如 'PRIMARY KEY (name, type)')， 它将被直接插入到生成的SQL。

delete() 方法
public void delete(string $table, mixed $conditions='', array $params=array ( ))
$table string 要删除的数据所在的表。
$conditions mixed 放在 WHERE 部分的条件。 请参考 CDbCommand::where 关于怎样指定条件。
$params array 绑定到该查询的条件。 

public function delete($table, $conditions='', $params=array())
{
    echo "    > delete from $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->delete($table, $conditions, $params);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

创建和执行一条 DELETE SQL 语句。

down() 方法
public boolean down()
{return} boolean 

public function down()
{
    $transaction=$this->getDbConnection()->beginTransaction();
    try
    {
        if($this->safeDown()===false)
        {
            $transaction->rollBack();
            return false;
        }
        $transaction->commit();
    }
    catch(Exception $e)
    {
        echo "Exception: ".$e->getMessage().' ('.$e->getFile().':'.$e->getLine().")\n";
        echo $e->getTraceAsString()."\n";
        $transaction->rollBack();
        return false;
    }
}

当删除此迁移时，此方法包含要执行的逻辑。 默认实现将引发异常指示无法删除迁移。 如果可以删除相应的迁移，子类可以重写此方法。

dropColumn() 方法
public void dropColumn(string $table, string $column)
$table string 列将被删除的表。该名称会被此方法恰当的引用。
$column string 列将被删除的表的名称。该名称会被此方法恰当的引用。 

public function dropColumn($table, $column)
{
    echo "    > drop column $column from table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->dropColumn($table, $column);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

创建并执行一条SQL语句为删除一个数据库列。

dropForeignKey() 方法
public void dropForeignKey(string $name, string $table)
$name string 要删除的外键约束的名称。该名称会被此方法恰当的引用。
$table string 外键将被删除的表。该名称会被此方法恰当的引用。 

public function dropForeignKey($name, $table)
{
    echo "    > drop foreign key $name from table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->dropForeignKey($name, $table);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立一条SQL语句为删除外键约束。

dropIndex() 方法
public void dropIndex(string $name, string $table)
$name string 要删除索引的名称。该名称会被此方法恰当的引用。
$table string 索引要被删除的表。该名称会被此方法恰当的引用。 

public function dropIndex($name, $table)
{
    echo "    > drop index $name ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->dropIndex($name, $table);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条删除一条SQL索引的语句。

dropTable() 方法
public void dropTable(string $table)
$table string 要删除的表。表名将被此方法恰当的引用。 

public function dropTable($table)
{
    echo "    > drop table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->dropTable($table);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为删除一个数据库表。

execute() 方法 （可用自 v1.1.7）
public void execute(string $sql, array $params=array ( ))
$sql string 要执行的 SQL 语句。
$params array 执行SQL语句的输入参数 (name=>value) 。 参见CDbCommand::execute 获取更多细节。 

public function execute($sql, $params=array())
{
    echo "    > execute SQL: $sql ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand($sql)->execute($params);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

执行一条SQL语句。 此方法使用 dbConnection 执行指定的SQL语句。

getDbConnection() 方法
public CDbConnection getDbConnection()
{return} CDbConnection 返回当前活动的数据库连接。 

public function getDbConnection()
{
    if($this->_db===null)
    {
        $this->_db=Yii::app()->getComponent('db');
        if(!$this->_db instanceof CDbConnection)
            throw new CException(Yii::t('yii', 'The "db" application component must be configured to be a CDbConnection object.'));
    }
    return $this->_db;
}

返回当前活动的数据库连接。 默认情况下，‘db’的应用组件将返回并激活。 你能调用 setDbConnection 切换到一个不同的数据库连接。 方法如 insert, createTable 将使用这个数据库连接 去执行DB查询。

insert() 方法
public void insert(string $table, array $columns)
$table string 新行将被插入的表。
$columns array 被插入到此表的列数据 (name=>value) 。 

public function insert($table, $columns)
{
    echo "    > insert into $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->insert($table, $columns);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

创建和执行一条 INSERT SQL 语句。 这个方法将正确转义列名称，并绑定要插入的值。

refreshTableSchema() 方法 （可用自 v1.1.9）
public void refreshTableSchema(string $table)
$table string 要刷新表的名称 

public function refreshTableSchema($table)
{
    echo "    > refresh table $table schema cache ...";
    $time=microtime(true);
    $this->getDbConnection()->getSchema()->getTable($table,true);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

刷新架构缓存表。

renameColumn() 方法
public void renameColumn(string $table, string $name, string $newName)
$table string 列将被重命名的表。该名称会被此方法恰当的引用。
$name string 旧的列名。该名称会被此方法恰当的引用。
$newName string 新的列名。该名称会被此方法恰当的引用。 

public function renameColumn($table, $name, $newName)
{
    echo "    > rename column $name in table $table to $newName ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->renameColumn($table, $name, $newName);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为重命名一列。

renameTable() 方法
public void renameTable(string $table, string $newName)
$table string 要重命名的表。表名将被此方法恰当的引用。
$newName string 新的表名。表名将被此方法恰当的引用。 

public function renameTable($table, $newName)
{
    echo "    > rename table $table to $newName ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->renameTable($table, $newName);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行一条SQL语句为重命名数据表。

safeDown() 方法 （可用自 v1.1.7）
public boolean safeDown()
{return} boolean 

public function safeDown()
{
}

当删除此迁移时，此方法包含要执行的逻辑。 这个方法不同于 up 因为这里是数据库逻辑的实现 被封闭在一个数据库事务内。 如果DB逻辑需要在一个事务内实现，子类可以实现这个方法， 而不是放在 up。

safeUp() 方法 （可用自 v1.1.7）
public boolean safeUp()
{return} boolean 

public function safeUp()
{
}

当应用此迁移时，此方法包含要执行的逻辑。 这个方法不同于 up 因为这里数据库逻辑的实现 被封闭在一个数据库事务内。 如果DB逻辑需要在一个事务内实现，子类可以实现这个方法， 而不是放在 up。

setDbConnection() 方法
public void setDbConnection(CDbConnection $db)
$db CDbConnection 该数据库连接组件 

public function setDbConnection($db)
{
    $this->_db=$db;
}

设置当前活动的数据库连接。 此数据库连接将被这些方法使用，如 insert, createTable.

truncateTable() 方法
public void truncateTable(string $table)
$table string 要截断的表。表名将被此方法恰当的引用。 

public function truncateTable($table)
{
    echo "    > truncate table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->truncateTable($table);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

建立并执行SQL语句为截断一个数据库表。

up() 方法
public boolean up()
{return} boolean 

public function up()
{
    $transaction=$this->getDbConnection()->beginTransaction();
    try
    {
        if($this->safeUp()===false)
        {
            $transaction->rollBack();
            return false;
        }
        $transaction->commit();
    }
    catch(Exception $e)
    {
        echo "Exception: ".$e->getMessage().' ('.$e->getFile().':'.$e->getLine().")\n";
        echo $e->getTraceAsString()."\n";
        $transaction->rollBack();
        return false;
    }
}

当应用此迁移时，此方法包含要执行的逻辑。 子类可以实现此方法以提供实际的迁移逻辑。

update() 方法
public void update(string $table, array $columns, mixed $conditions='', array $params=array ( ))
$table string 要更新的表。
$columns array 要更新的列数据 (name=>value) 。
$conditions mixed 放在 WHERE 部分的条件。 请参考 CDbCommand::where 关于怎样指定条件。
$params array 绑定到该查询的条件。 

public function update($table, $columns, $conditions='', $params=array())
{
    echo "    > update $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand()->update($table, $columns, $conditions, $params);
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

创建和执行一条 UPDATE SQL 语句。 这个方法将正确转义列名称，并绑定要更新的值。

上一篇：
下一篇：