|
|
|
@ -28,25 +28,24 @@ Creating Migrations
|
|
|
|
|
|
|
|
|
|
To create a new migration (e.g. create a news table), we run the following command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/create <name> |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The required `name` parameter specifies a very brief description of the migration |
|
|
|
|
(e.g. `create_news_table`). As we will show in the following, the `name` parameter |
|
|
|
|
is used as part of a PHP class name. Therefore, it should only contain letters, |
|
|
|
|
digits and/or underscore characters. |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/create create_news_table |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The above command will create under the `protected/migrations` directory a new |
|
|
|
|
file named `m101129_185401_create_news_table.php` which contains the following |
|
|
|
|
initial code: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
[php] |
|
|
|
|
```php |
|
|
|
|
class m101129_185401_create_news_table extends \yii\db\Migration |
|
|
|
|
{ |
|
|
|
|
public function up() |
|
|
|
@ -59,7 +58,7 @@ class m101129_185401_create_news_table extends \yii\db\Migration
|
|
|
|
|
return false; |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
Notice that the class name is the same as the file name which is of the pattern |
|
|
|
|
`m<timestamp>_<name>`, where `<timestamp>` refers to the UTC timestamp (in the |
|
|
|
@ -78,8 +77,7 @@ method returns `false` to indicate that the migration cannot be reverted.
|
|
|
|
|
|
|
|
|
|
As an example, let's show the migration about creating a news table. |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
[php] |
|
|
|
|
```php |
|
|
|
|
class m101129_185401_create_news_table extends \yii\db\Migration |
|
|
|
|
{ |
|
|
|
|
public function up() |
|
|
|
@ -96,7 +94,7 @@ class m101129_185401_create_news_table extends \yii\db\Migration
|
|
|
|
|
$this->db->createCommand()->dropTable('tbl_news')->execute(); |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The base class [\yii\db\Migration] exposes a database connection via `db` |
|
|
|
|
property. You can use it for manipulating data and schema of a database. |
|
|
|
@ -112,8 +110,7 @@ DB transactions.
|
|
|
|
|
We could explicitly start a DB transaction and enclose the rest of the DB-related |
|
|
|
|
code within the transaction, like the following: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
[php] |
|
|
|
|
```php |
|
|
|
|
class m101129_185401_create_news_table extends \yii\db\Migration |
|
|
|
|
{ |
|
|
|
|
public function up() |
|
|
|
@ -138,7 +135,7 @@ class m101129_185401_create_news_table extends \yii\db\Migration
|
|
|
|
|
|
|
|
|
|
// ...similar code for down() |
|
|
|
|
} |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
> Note: Not all DBMS support transactions. And some DB queries cannot be put |
|
|
|
|
> into a transaction. In this case, you will have to implement `up()` and |
|
|
|
@ -152,9 +149,9 @@ Applying Migrations
|
|
|
|
|
To apply all available new migrations (i.e., make the local database up-to-date), |
|
|
|
|
run the following command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The command will show the list of all new migrations. If you confirm to apply |
|
|
|
|
the migrations, it will run the `up()` method in every new migration class, one |
|
|
|
@ -169,18 +166,18 @@ application component.
|
|
|
|
|
Sometimes, we may only want to apply one or a few new migrations. We can use the |
|
|
|
|
following command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/up 3 |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
This command will apply the 3 new migrations. Changing the value 3 will allow |
|
|
|
|
us to change the number of migrations to be applied. |
|
|
|
|
|
|
|
|
|
We can also migrate the database to a specific version with the following command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/to 101129_185401 |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
That is, we use the timestamp part of a migration name to specify the version |
|
|
|
|
that we want to migrate the database to. If there are multiple migrations between |
|
|
|
@ -195,9 +192,9 @@ Reverting Migrations
|
|
|
|
|
To revert the last one or several applied migrations, we can use the following |
|
|
|
|
command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/down [step] |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
where the optional `step` parameter specifies how many migrations to be reverted |
|
|
|
|
back. It defaults to 1, meaning reverting back the last applied migration. |
|
|
|
@ -212,9 +209,9 @@ Redoing Migrations
|
|
|
|
|
Redoing migrations means first reverting and then applying the specified migrations. |
|
|
|
|
This can be done with the following command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/redo [step] |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
where the optional `step` parameter specifies how many migrations to be redone. |
|
|
|
|
It defaults to 1, meaning redoing the last migration. |
|
|
|
@ -226,10 +223,10 @@ Showing Migration Information
|
|
|
|
|
Besides applying and reverting migrations, the migration tool can also display |
|
|
|
|
the migration history and the new migrations to be applied. |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/history [limit] |
|
|
|
|
yii migrate/new [limit] |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
where the optional parameter `limit` specifies the number of migrations to be |
|
|
|
|
displayed. If `limit` is not specified, all available migrations will be displayed. |
|
|
|
@ -246,9 +243,9 @@ version without actually applying or reverting the relevant migrations. This
|
|
|
|
|
often happens when developing a new migration. We can use the following command |
|
|
|
|
to achieve this goal. |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/mark 101129_185401 |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
This command is very similar to `yii migrate/to` command, except that it only |
|
|
|
|
modifies the migration history table to the specified version without applying |
|
|
|
@ -290,17 +287,17 @@ line:
|
|
|
|
|
|
|
|
|
|
To specify these options, execute the migrate command using the following format |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/up --option1=value1 --option2=value2 ... |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
For example, if we want to migrate for a `forum` module whose migration files |
|
|
|
|
are located within the module's `migrations` directory, we can use the following |
|
|
|
|
command: |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
yii migrate/up --migrationPath=ext.forum.migrations |
|
|
|
|
~~~ |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Configure Command Globally |
|
|
|
|