PHP Class yii\db\Migration

Migration is designed to be used together with the "yii migrate" command. Each child class of Migration represents an individual database migration which is identified by the child class name. Within each migration, the Migration::up method should be overridden to contain the logic for "upgrading" the database; while the Migration::down method for the "downgrading" logic. The "yii migrate" command manages all available migrations in an application. If the database supports transactions, you may also override Migration::safeUp and Migration::safeDown so that if anything wrong happens during the upgrading or downgrading, the whole migration can be reverted in a whole. Migration provides a set of convenient methods for manipulating database data and schema. For example, the Migration::insert method can be used to easily insert a row of data into a database table; the Migration::createTable method can be used to create a database table. Compared with the same methods in Command, these methods will display extra information showing the method parameters and execution time, which may be useful when applying migrations. For more details and usage information on Migration, see the guide article on Migration.
Since: 2.0
Author: Qiang Xue ([email protected])
Inheritance: extends yii\base\Component, implements yii\db\MigrationInterface, use trait SchemaBuilderTrait
Exibir arquivo Open project: yiisoft/yii2 Class Usage Examples

Public Properties

Property Type Description
$db the DB connection object or the application component ID of the DB connection that this migration should work with. Starting from version 2.0.2, this can also be a configuration array for creating the object. Note that when a Migration object is created by the migrate command, this property will be overwritten by the command. If you do not want to use the DB connection provided by the command, you may override the Migration::init method like the following: php public function init() { $this->db = 'db2'; parent::init(); }

Public Methods

Method Description
addColumn ( string $table, string $column, string $type ) Builds and executes a SQL statement for adding a new DB column.
addCommentOnColumn ( string $table, string $column, string $comment ) Builds and execute a SQL statement for adding comment to column
addCommentOnTable ( string $table, string $comment ) Builds a SQL statement for adding comment to table
addForeignKey ( string $name, string $table, string | array $columns, string $refTable, string | array $refColumns, string $delete = null, string $update = null ) Builds a SQL statement for adding a foreign key constraint to an existing table.
addPrimaryKey ( string $name, string $table, string | array $columns ) Builds and executes a SQL statement for creating a primary key.
alterColumn ( string $table, string $column, string $type ) Builds and executes a SQL statement for changing the definition of a column.
batchInsert ( string $table, array $columns, array $rows ) Creates and executes an batch INSERT SQL statement.
createIndex ( string $name, string $table, string | array $columns, boolean $unique = false ) Builds and executes a SQL statement for creating a new index.
createTable ( string $table, array $columns, string $options = null ) Builds and executes a SQL statement for creating a new DB table.
delete ( string $table, array | string $condition = '', array $params = [] ) Creates and executes a DELETE SQL statement.
down ( ) : boolean This method contains the logic to be executed when removing this migration.
dropColumn ( string $table, string $column ) Builds and executes a SQL statement for dropping a DB column.
dropCommentFromColumn ( string $table, string $column ) Builds and execute a SQL statement for dropping comment from column
dropCommentFromTable ( string $table ) Builds a SQL statement for dropping comment from table
dropForeignKey ( string $name, string $table ) Builds a SQL statement for dropping a foreign key constraint.
dropIndex ( string $name, string $table ) Builds and executes a SQL statement for dropping an index.
dropPrimaryKey ( string $name, string $table ) Builds and executes a SQL statement for dropping a primary key.
dropTable ( string $table ) Builds and executes a SQL statement for dropping a DB table.
execute ( string $sql, array $params = [] ) Executes a SQL statement.
init ( ) Initializes the migration.
insert ( string $table, array $columns ) Creates and executes an INSERT SQL statement.
renameColumn ( string $table, string $name, string $newName ) Builds and executes a SQL statement for renaming a column.
renameTable ( string $table, string $newName ) Builds and executes a SQL statement for renaming a DB table.
safeDown ( ) : boolean This method contains the logic to be executed when removing this migration.
safeUp ( ) : boolean This method contains the logic to be executed when applying this migration.
truncateTable ( string $table ) Builds and executes a SQL statement for truncating a DB table.
up ( ) : boolean This method contains the logic to be executed when applying this migration.
update ( string $table, array $columns, array | string $condition = '', array $params = [] ) Creates and executes an UPDATE SQL statement.

Protected Methods

Method Description
getDb ( )

Method Details

addColumn() public method

Builds and executes a SQL statement for adding a new DB column.
public addColumn ( string $table, string $column, string $type )
$table string the table that the new column will be added to. The table name will be properly quoted by the method.
$column string the name of the new column. The name will be properly quoted by the method.
$type string the column type. The [[QueryBuilder::getColumnType()]] method will be invoked to convert abstract column type (if any) into the physical one. Anything that is not recognized as abstract type will be kept in the generated SQL. For example, 'string' will be turned into 'varchar(255)', while 'string not null' will become 'varchar(255) not null'.

addCommentOnColumn() public method

Builds and execute a SQL statement for adding comment to column
Since: 2.0.8
public addCommentOnColumn ( string $table, string $column, string $comment )
$table string the table whose column is to be commented. The table name will be properly quoted by the method.
$column string the name of the column to be commented. The column name will be properly quoted by the method.
$comment string the text of the comment to be added. The comment will be properly quoted by the method.

addCommentOnTable() public method

Builds a SQL statement for adding comment to table
Since: 2.0.8
public addCommentOnTable ( string $table, string $comment )
$table string the table whose column is to be commented. The table name will be properly quoted by the method.
$comment string the text of the comment to be added. The comment will be properly quoted by the method.

addForeignKey() public method

The method will properly quote the table and column names.
public addForeignKey ( string $name, string $table, string | array $columns, string $refTable, string | array $refColumns, string $delete = null, string $update = null )
$name string the name of the foreign key constraint.
$table string the table that the foreign key constraint will be added to.
$columns string | array the name of the column to that the constraint will be added on. If there are multiple columns, separate them with commas or use an array.
$refTable string the table that the foreign key references to.
$refColumns string | array the name of the column that the foreign key references to. If there are multiple columns, separate them with commas or use an array.
$delete string the ON DELETE option. Most DBMS support these options: RESTRICT, CASCADE, NO ACTION, SET DEFAULT, SET NULL
$update string the ON UPDATE option. Most DBMS support these options: RESTRICT, CASCADE, NO ACTION, SET DEFAULT, SET NULL

addPrimaryKey() public method

The method will properly quote the table and column names.
public addPrimaryKey ( string $name, string $table, string | array $columns )
$name string the name of the primary key constraint.
$table string the table that the primary key constraint will be added to.
$columns string | array comma separated string or array of columns that the primary key will consist of.

alterColumn() public method

Builds and executes a SQL statement for changing the definition of a column.
public alterColumn ( string $table, string $column, string $type )
$table string the table whose column is to be changed. The table name will be properly quoted by the method.
$column string the name of the column to be changed. The name will be properly quoted by the method.
$type string the new column type. The [[QueryBuilder::getColumnType()]] method will be invoked to convert abstract column type (if any) into the physical one. Anything that is not recognized as abstract type will be kept in the generated SQL. For example, 'string' will be turned into 'varchar(255)', while 'string not null' will become 'varchar(255) not null'.

batchInsert() public method

The method will properly escape the column names, and bind the values to be inserted.
public batchInsert ( string $table, array $columns, array $rows )
$table string the table that new rows will be inserted into.
$columns array the column names.
$rows array the rows to be batch inserted into the table

createIndex() public method

Builds and executes a SQL statement for creating a new index.
public createIndex ( string $name, string $table, string | array $columns, boolean $unique = false )
$name string the name of the index. The name will be properly quoted by the method.
$table string the table that the new index will be created for. The table name will be properly quoted by the method.
$columns string | array the column(s) that should be included in the index. If there are multiple columns, please separate them by commas or use an array. Each column name will be properly quoted by the method. Quoting will be skipped for column names that include a left parenthesis "(".
$unique boolean whether to add UNIQUE constraint on the created index.

createTable() public method

The columns in the new table should be specified as name-definition pairs (e.g. 'name' => 'string'), where name stands for a column name which will be properly quoted by the method, and definition stands for the column type which can contain an abstract DB type. The [[QueryBuilder::getColumnType()]] method will be invoked to convert any abstract type into a physical one. If a column is specified with definition only (e.g. 'PRIMARY KEY (name, type)'), it will be directly put into the generated SQL.
public createTable ( string $table, array $columns, string $options = null )
$table string the name of the table to be created. The name will be properly quoted by the method.
$columns array the columns (name => definition) in the new table.
$options string additional SQL fragment that will be appended to the generated SQL.

delete() public method

Creates and executes a DELETE SQL statement.
public delete ( string $table, array | string $condition = '', array $params = [] )
$table string the table where the data will be deleted from.
$condition array | string the conditions that will be put in the WHERE part. Please refer to [[Query::where()]] on how to specify conditions.
$params array the parameters to be bound to the query.

down() public method

The default implementation throws an exception indicating the migration cannot be removed. Child classes may override this method if the corresponding migrations can be removed.
public down ( ) : boolean
return boolean return a false value to indicate the migration fails and should not proceed further. All other return values mean the migration succeeds.

dropColumn() public method

Builds and executes a SQL statement for dropping a DB column.
public dropColumn ( string $table, string $column )
$table string the table whose column is to be dropped. The name will be properly quoted by the method.
$column string the name of the column to be dropped. The name will be properly quoted by the method.

dropCommentFromColumn() public method

Builds and execute a SQL statement for dropping comment from column
Since: 2.0.8
public dropCommentFromColumn ( string $table, string $column )
$table string the table whose column is to be commented. The table name will be properly quoted by the method.
$column string the name of the column to be commented. The column name will be properly quoted by the method.

dropCommentFromTable() public method

Builds a SQL statement for dropping comment from table
Since: 2.0.8
public dropCommentFromTable ( string $table )
$table string the table whose column is to be commented. The table name will be properly quoted by the method.

dropForeignKey() public method

Builds a SQL statement for dropping a foreign key constraint.
public dropForeignKey ( string $name, string $table )
$name string the name of the foreign key constraint to be dropped. The name will be properly quoted by the method.
$table string the table whose foreign is to be dropped. The name will be properly quoted by the method.

dropIndex() public method

Builds and executes a SQL statement for dropping an index.
public dropIndex ( string $name, string $table )
$name string the name of the index to be dropped. The name will be properly quoted by the method.
$table string the table whose index is to be dropped. The name will be properly quoted by the method.

dropPrimaryKey() public method

Builds and executes a SQL statement for dropping a primary key.
public dropPrimaryKey ( string $name, string $table )
$name string the name of the primary key constraint to be removed.
$table string the table that the primary key constraint will be removed from.

dropTable() public method

Builds and executes a SQL statement for dropping a DB table.
public dropTable ( string $table )
$table string the table to be dropped. The name will be properly quoted by the method.

execute() public method

This method executes the specified SQL statement using [[db]].
public execute ( string $sql, array $params = [] )
$sql string the SQL statement to be executed
$params array input parameters (name => value) for the SQL execution. See [[Command::execute()]] for more details.

getDb() protected method

Since: 2.0.6
protected getDb ( )

init() public method

This method will set [[db]] to be the 'db' application component, if it is null.
public init ( )

insert() public method

The method will properly escape the column names, and bind the values to be inserted.
public insert ( string $table, array $columns )
$table string the table that new rows will be inserted into.
$columns array the column data (name => value) to be inserted into the table.

renameColumn() public method

Builds and executes a SQL statement for renaming a column.
public renameColumn ( string $table, string $name, string $newName )
$table string the table whose column is to be renamed. The name will be properly quoted by the method.
$name string the old name of the column. The name will be properly quoted by the method.
$newName string the new name of the column. The name will be properly quoted by the method.

renameTable() public method

Builds and executes a SQL statement for renaming a DB table.
public renameTable ( string $table, string $newName )
$table string the table to be renamed. The name will be properly quoted by the method.
$newName string the new table name. The name will be properly quoted by the method.

safeDown() public method

This method differs from Migration::down in that the DB logic implemented here will be enclosed within a DB transaction. Child classes may implement this method instead of Migration::down if the DB logic needs to be within a transaction.
public safeDown ( ) : boolean
return boolean return a false value to indicate the migration fails and should not proceed further. All other return values mean the migration succeeds.

safeUp() public method

This method differs from Migration::up in that the DB logic implemented here will be enclosed within a DB transaction. Child classes may implement this method instead of Migration::up if the DB logic needs to be within a transaction.
public safeUp ( ) : boolean
return boolean return a false value to indicate the migration fails and should not proceed further. All other return values mean the migration succeeds.

truncateTable() public method

Builds and executes a SQL statement for truncating a DB table.
public truncateTable ( string $table )
$table string the table to be truncated. The name will be properly quoted by the method.

up() public method

Child classes may override this method to provide actual migration logic.
public up ( ) : boolean
return boolean return a false value to indicate the migration fails and should not proceed further. All other return values mean the migration succeeds.

update() public method

The method will properly escape the column names and bind the values to be updated.
public update ( string $table, array $columns, array | string $condition = '', array $params = [] )
$table string the table to be updated.
$columns array the column data (name => value) to be updated.
$condition array | string the conditions that will be put in the WHERE part. Please refer to [[Query::where()]] on how to specify conditions.
$params array the parameters to be bound to the query.

Property Details

$db public_oe property

the DB connection object or the application component ID of the DB connection that this migration should work with. Starting from version 2.0.2, this can also be a configuration array for creating the object. Note that when a Migration object is created by the migrate command, this property will be overwritten by the command. If you do not want to use the DB connection provided by the command, you may override the Migration::init method like the following: php public function init() { $this->db = 'db2'; parent::init(); }
public $db