Class console\controllers\MigrateController
| Inheritance | console\controllers\MigrateController » yii\console\Controller |
|---|---|
| Available since version | 1.0 |
Manages application and extension migrations.
Spin-off from https://github.com/yiisoft/yii2/pull/3273/files
A migration means a set of persistent changes to the application environment that is shared among different developers. For example, in an application backed by a database, a migration may refer to a set of changes to the database, such as creating a new table, adding a new table column.
This command provides support for tracking the migration history, upgrading or downloading with migrations, and creating new migration skeletons.
The migration history is stored in a database table named as $migrationTable. The table will be automatically created the first time this command is executed, if it does not exist. You may also manually create it as follows:
CREATE TABLE migration (
version varchar(180) PRIMARY KEY,
version alias(180),
apply_time integer
)
You may configure additional migration paths using the application param yii.migrations
Below are some common usages of this command:
# creates a new migration named 'create_user_table'
yii migrate/create create_user_table
# applies ALL new migrations
yii migrate
# reverts the last applied migration
yii migrate/down
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $applyPath | string | The directory using for applying migration | console\controllers\MigrateController |
| $db | \yii\db\Connection|string | The DB connection object or the application component ID of the DB connection. | console\controllers\MigrateController |
| $defaultAction | string | The default command action. | console\controllers\MigrateController |
| $interactive | boolean | Whether to execute the migration in an interactive mode. | console\controllers\MigrateController |
| $migrationLookup | array | Additional aliases of migration directories | console\controllers\MigrateController |
| $migrationPath | string | The directory storing the migration classes. | console\controllers\MigrateController |
| $migrationTable | string | The name of the table for keeping applied migration information. | console\controllers\MigrateController |
| $templateFile | string | The template file for generating new migrations. | console\controllers\MigrateController |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| actionCreate() | Creates a new migration. | console\controllers\MigrateController |
| actionDown() | Downgrades the application by reverting old migrations. | console\controllers\MigrateController |
| actionHistory() | Displays the migration history. | console\controllers\MigrateController |
| actionMark() | Modifies the migration history to the specified version. | console\controllers\MigrateController |
| actionNew() | Displays the un-applied new migrations. | console\controllers\MigrateController |
| actionRedo() | Redoes the last few migrations. | console\controllers\MigrateController |
| actionTo() | Upgrades or downgrades till the specified version. | console\controllers\MigrateController |
| actionUp() | Upgrades the application by applying new migrations. | console\controllers\MigrateController |
| beforeAction() | This method is invoked right before an action is to be executed (after all possible filters.) It checks the existence of the $migrationPath. | console\controllers\MigrateController |
| options() | console\controllers\MigrateController |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| createMigration() | Creates a new migration instance. | console\controllers\MigrateController |
| createMigrationHistoryTable() | Creates the migration history table. | console\controllers\MigrateController |
| getMigrationHistory() | Returns the migration history. | console\controllers\MigrateController |
| getNewMigrations() | Returns the migrations that are not applied. | console\controllers\MigrateController |
| migrateDown() | Downgrades with the specified migration class. | console\controllers\MigrateController |
| migrateToTime() | Migrates to the specified apply time in the past. | console\controllers\MigrateController |
| migrateToVersion() | Migrates to the certain version. | console\controllers\MigrateController |
| migrateUp() | Upgrades with the specified migration class. | console\controllers\MigrateController |
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| BASE_MIGRATION | 'm000000_000000_base' | The name of the dummy migration that marks the beginning of the whole migration history. | console\controllers\MigrateController |
Property Details
The directory using for applying migration
The DB connection object or the application component ID of the DB connection.
The default command action.
Whether to execute the migration in an interactive mode.
Additional aliases of migration directories
The directory storing the migration classes. This can be either a path alias or a directory.
The name of the table for keeping applied migration information.
The template file for generating new migrations. This can be either a path alias (e.g. "@app/migrations/template.php") or a file path.
Method Details
Creates a new migration.
This command creates a new migration using the available migration template. After using this command, developers should modify the created migration skeleton by filling up the actual migration logic.
yii migrate/create create_user_table
| void actionCreate( $name ) | ||
| $name | string | The name of the new migration. This should only contain letters, digits and/or underscores. |
| throws | \yii\console\Exception | if the name argument is invalid. |
|---|---|---|
Downgrades the application by reverting old migrations.
For example,
yii migrate/down # revert the last migration
yii migrate/down 3 # revert the last 3 migrations
| void actionDown( $limit = 1 ) | ||
| $limit | integer | The number of migrations to be reverted. Defaults to 1, meaning the last applied migration will be reverted. |
| throws | \yii\console\Exception | if the number of the steps specified is less than 1. |
|---|---|---|
Displays the migration history.
This command will show the list of migrations that have been applied so far. For example,
yii migrate/history # showing the last 10 migrations
yii migrate/history 5 # showing the last 5 migrations
yii migrate/history 0 # showing the whole history
| void actionHistory( $limit = 10 ) | ||
| $limit | integer | The maximum number of migrations to be displayed. If it is 0, the whole migration history will be displayed. |
| throws | \yii\console\Exception | |
|---|---|---|
Modifies the migration history to the specified version.
No actual migration will be performed.
yii migrate/mark 101129_185401 # using timestamp
yii migrate/mark m101129_185401_create_user_table # using full name
| void actionMark( $version ) | ||
| $version | string | The version at which the migration history should be marked. This can be either the timestamp or the full name of the migration. |
| throws | \yii\console\Exception | if the version argument is invalid or the version cannot be found. |
|---|---|---|
Displays the un-applied new migrations.
This command will show the new migrations that have not been applied. For example,
yii migrate/new # showing the first 10 new migrations
yii migrate/new 5 # showing the first 5 new migrations
yii migrate/new 0 # showing all new migrations
| void actionNew( $limit = 10 ) | ||
| $limit | integer | The maximum number of new migrations to be displayed. If it is 0, all available new migrations will be displayed. |
Redoes the last few migrations.
This command will first revert the specified migrations, and then apply them again. For example,
yii migrate/redo # redo the last applied migration
yii migrate/redo 3 # redo the last 3 applied migrations
| void actionRedo( $limit = 1 ) | ||
| $limit | integer | The number of migrations to be redone. Defaults to 1, meaning the last applied migration will be redone. |
| throws | \yii\console\Exception | if the number of the steps specified is less than 1. |
|---|---|---|
Upgrades or downgrades till the specified version.
Can also downgrade versions to the certain apply time in the past by providing a UNIX timestamp or a string parseable by the strtotime() function. This means that all the versions applied after the specified certain time would be reverted.
This command will first revert the specified migrations, and then apply them again. For example,
yii migrate/to 101129_185401 # using timestamp
yii migrate/to m101129_185401_create_user_table # using full name
yii migrate/to 1392853618 # using UNIX timestamp
yii migrate/to "2014-02-15 13:00:50" # using strtotime() parseable string
| void actionTo( $version ) | ||
| $version | string | Either the version name or the certain time value in the past that the application should be migrated to. This can be either the timestamp, the full name of the migration, the UNIX timestamp, or the parseable datetime string. |
| throws | \yii\console\Exception | if the version argument is invalid. |
|---|---|---|
Upgrades the application by applying new migrations.
For example,
yii migrate # apply all new migrations
yii migrate 3 # apply the first 3 new migrations
| void actionUp( $limit = 0 ) | ||
| $limit | integer | The number of new migrations to be applied. If 0, it means applying all available new migrations. |
This method is invoked right before an action is to be executed (after all possible filters.) It checks the existence of the $migrationPath.
| boolean beforeAction( $action ) | ||
| $action | \yii\base\Action | The action to be executed. |
| return | boolean | Whether the action should continue to be executed. |
|---|---|---|
| throws | \yii\console\Exception | if db component isn't configured |
Creates a new migration instance.
| \yii\db\Migration createMigration( $class, $alias ) | ||
| $class | string | The migration class name |
| $alias | ||
| return | \yii\db\Migration | The migration instance |
|---|---|---|
Creates the migration history table.
| void createMigrationHistoryTable( ) |
Returns the migration history.
| array getMigrationHistory( $limit ) | ||
| $limit | integer | The maximum number of records in the history to be returned |
| return | array | The migration history |
|---|---|---|
Returns the migrations that are not applied.
| array getNewMigrations( ) | ||
| return | array | List of new migrations, (key: migration version; value: alias) |
|---|---|---|
Downgrades with the specified migration class.
| boolean migrateDown( $class, $alias ) | ||
| $class | string | The migration class name |
| $alias | ||
| return | boolean | Whether the migration is successful |
|---|---|---|
Migrates to the specified apply time in the past.
| void migrateToTime( $time ) | ||
| $time | integer | UNIX timestamp value. |
Migrates to the certain version.
| void migrateToVersion( $version ) | ||
| $version | string | Name in the full format. |
| throws | \yii\console\Exception | if the provided version cannot be found. |
|---|---|---|
Upgrades with the specified migration class.
| boolean migrateUp( $class, $alias ) | ||
| $class | string | The migration class name |
| $alias | ||
| return | boolean | Whether the migration is successful |
|---|---|---|
| void options( $actionId ) | ||
| $actionId | ||