Class dmstr\console\controllers\MigrateController

Inheritancedmstr\console\controllers\MigrateController » yii\console\Controller
Available since version1.0

Manages application and extension migrations (dmstr/yii2-migrate-command).

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

Hide inherited properties

PropertyTypeDescriptionDefined By
$db \yii\db\Connection|string The DB connection object or the application component ID of the DB connection. dmstr\console\controllers\MigrateController
$defaultAction string The default command action. dmstr\console\controllers\MigrateController
$disableLookup boolean Lookup all application migration paths dmstr\console\controllers\MigrateController
$interactive boolean Whether to execute the migration in an interactive mode. dmstr\console\controllers\MigrateController
$migrationLookup array Additional aliases of migration directories dmstr\console\controllers\MigrateController
$migrationPath string The directory storing the migration classes. dmstr\console\controllers\MigrateController
$migrationTable string The name of the table for keeping applied migration information. dmstr\console\controllers\MigrateController
$templateFile string The template file for generating new migrations. dmstr\console\controllers\MigrateController

Public Methods

Hide inherited methods

MethodDescriptionDefined By
actionCreate() Creates a new migration. dmstr\console\controllers\MigrateController
actionDown() Downgrades the application by reverting old migrations. dmstr\console\controllers\MigrateController
actionHistory() Displays the migration history. dmstr\console\controllers\MigrateController
actionMark() Modifies the migration history to the specified version. dmstr\console\controllers\MigrateController
actionNew() Displays the un-applied new migrations. dmstr\console\controllers\MigrateController
actionRedo() Redoes the last few migrations. dmstr\console\controllers\MigrateController
actionTo() Upgrades or downgrades till the specified version. dmstr\console\controllers\MigrateController
actionUp() Upgrades the application by applying new migrations. dmstr\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. dmstr\console\controllers\MigrateController
options() dmstr\console\controllers\MigrateController

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
createMigration() Creates a new migration instance. dmstr\console\controllers\MigrateController
createMigrationHistoryTable() Creates the migration history table. dmstr\console\controllers\MigrateController
getMigrationHistory() Returns the migration history. dmstr\console\controllers\MigrateController
getNewMigrations() Returns the migrations that are not applied. dmstr\console\controllers\MigrateController
migrateDown() Downgrades with the specified migration class. dmstr\console\controllers\MigrateController
migrateToTime() Migrates to the specified apply time in the past. dmstr\console\controllers\MigrateController
migrateToVersion() Migrates to the certain version. dmstr\console\controllers\MigrateController
migrateUp() Upgrades with the specified migration class. dmstr\console\controllers\MigrateController

Constants

Hide inherited constants

ConstantValueDescriptionDefined By
BASE_MIGRATION 'm000000_000000_base' The name of the dummy migration that marks the beginning of the whole migration history. dmstr\console\controllers\MigrateController

Property Details

$db public property

The DB connection object or the application component ID of the DB connection.

public \yii\db\Connection|string $db 'db'
$defaultAction public property

The default command action.

public string $defaultAction 'up'
$disableLookup public property

Lookup all application migration paths

public boolean $disableLookup false
$interactive public property

Whether to execute the migration in an interactive mode.

public boolean $interactive true
$migrationLookup public property

Additional aliases of migration directories

public array $migrationLookup = []
$migrationPath public property

The directory storing the migration classes. This can be either a path alias or a directory.

public string $migrationPath '@app/migrations'
$migrationTable public property

The name of the table for keeping applied migration information.

public string $migrationTable '{{%migration}}'
$templateFile public property

The template file for generating new migrations. This can be either a path alias (e.g. "@app/migrations/template.php") or a file path.

public string $templateFile '@yii/views/migration.php'

Method Details

actionCreate() public method

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
public 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.

actionDown() public method

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
public 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.

actionHistory() public method

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
public 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.

actionMark() public method

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
public 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.

actionNew() public method

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
public 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.

actionRedo() public method

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
public 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.

actionTo() public method

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
public 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.

actionUp() public method

Upgrades the application by applying new migrations.

For example,

yii migrate     # apply all new migrations
yii migrate 3   # apply the first 3 new migrations
public void actionUp ( $limit 0 )
$limit integer

The number of new migrations to be applied. If 0, it means applying all available new migrations.

beforeAction() public method

This method is invoked right before an action is to be executed (after all possible filters.) It checks the existence of the $migrationPath.

public 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

createMigration() protected method

Creates a new migration instance.

protected \yii\db\Migration createMigration ( $class, $alias )
$class string

The migration class name

$alias
return \yii\db\Migration

The migration instance

createMigrationHistoryTable() protected method

Creates the migration history table.

protected void createMigrationHistoryTable ( )
getMigrationHistory() protected method

Returns the migration history.

protected array getMigrationHistory ( $limit )
$limit integer

The maximum number of records in the history to be returned

return array

The migration history

getNewMigrations() protected method

Returns the migrations that are not applied.

protected array getNewMigrations ( )
return array

List of new migrations, (key: migration version; value: alias)

migrateDown() protected method

Downgrades with the specified migration class.

protected boolean migrateDown ( $class, $alias )
$class string

The migration class name

$alias
return boolean

Whether the migration is successful

migrateToTime() protected method

Migrates to the specified apply time in the past.

protected void migrateToTime ( $time )
$time integer

UNIX timestamp value.

migrateToVersion() protected method

Migrates to the certain version.

protected void migrateToVersion ( $version )
$version string

Name in the full format.

throws \yii\console\Exception

if the provided version cannot be found.

migrateUp() protected method

Upgrades with the specified migration class.

protected boolean migrateUp ( $class, $alias )
$class string

The migration class name

$alias
return boolean

Whether the migration is successful

options() public method

public void options ( $actionId )
$actionId