Like source code, the structure of a database is evolving as we develop and maintain
Like source code, the structure of a database evolves as a database-driven application is developed and maintained. For example, during development, a new table may be added; Or, after the application goes live, it may be discovered that an additional index is required. It is important to keep track of these structural database changes (called **migration**), just as changes to the source code is tracked using version control. If the source code and the database become out of sync, bugs will occur, or the whole application might break. For this reason, Yii provides a database migration
a database-driven application. For example, during development, we may want to
tool that can keep track of database migration history, apply new migrations, or revert existing ones.
add a new table; or after the application is put into production, we may realize
the need of adding an index on a column. It is important to keep track of these
structural database changes (called **migration**) like we do with our source
code. If the source code and the database are out of sync, it is very likely
the whole system may break. For this reason, Yii provides a database migration
tool that can keep track of database migration history, apply new migrations,
or revert existing ones.
The following steps show how we can use database migration during development:
The following steps show how database migration is used by a team during development:
1. Tim creates a new migration (e.g. create a new table)
1. Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.).
2. Tim commits the new migration into source control system (e.g. GIT, Mercurial)
2. Tim commits the new migration into the source control system (e.g. Git, Mercurial).
3. Doug updates from source control system and receives the new migration
3. Doug updates his repository from the source control system and receives the new migration.
4. Doug applies the migration to his local development database
4. Doug applies the migration to his local development database, thereby syncing his database to reflect the changes Tim made.
Yii supports database migration via the `yii migrate` command line tool. This tool supports:
Yii supports database migration via the `yii migrate` command line tool. This
* Creating new migrations
tool supports creating new migrations, applying/reverting/redoing migrations, and
* Applying, reverting, and redoing migrations
showing migration history and new migrations.
* Showing migration history and new migrations
Creating Migrations
Creating Migrations
-------------------
-------------------
To create a new migration (e.g. create a news table), we run the following command:
To create a new migration, run the following command:
```
```
yii migrate/create <name>
yii migrate/create <name>
```
```
The required `name` parameter specifies a very brief description of the migration
The required `name` parameter specifies a very brief description of the migration. For example, if the migration creates a new table named *news*, you'd use the command:
(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
yii migrate/create create_news_table
```
```
The above command will create under the `protected/migrations` directory a new
As you'll shortly see, the `name` parameter
file named `m101129_185401_create_news_table.php` which contains the following
is used as part of a PHP class name in the migration. Therefore, it should only contain letters,
initial code:
digits and/or underscore characters.
The above command will create a new
file named `m101129_185401_create_news_table.php`. This file will be created within the `protected/migrations` directory. Initially, the migration file will be generated with the following code:
@@ -60,19 +54,20 @@ class m101129_185401_create_news_table extends \yii\db\Migration
...
@@ -60,19 +54,20 @@ class m101129_185401_create_news_table extends \yii\db\Migration
}
}
```
```
Notice that the class name is the same as the file name which is of the pattern
Notice that the class name is the same as the file name, and follows the pattern
`m<timestamp>_<name>`, where `<timestamp>` refers to the UTC timestamp (in the
`m<timestamp>_<name>`, where:
format of `yymmdd_hhmmss`) when the migration is created, and `<name>` is taken
from the command's `name` parameter.
*`<timestamp>` refers to the UTC timestamp (in the
format of `yymmdd_hhmmss`) when the migration is created,
*`<name>` is taken from the command's `name` parameter.
The `up()` method should contain the code implementing the actual database
In the class, the `up()` method should contain the code implementing the actual database
migration, while the `down()` method may contain the code reverting what is
migration. In other words, the `up()` method executes code that actually changes the database. The `down()` method may contain code that reverts the changes made by `up()`.
done in `up()`.
Sometimes, it is impossible to implement `down()`. For example, if we delete
Sometimes, it is impossible for the `down()` to undo the database migration. For example, if the migration deletes
table rows in `up()`, we will not be able to recover them in `down()`. In this
table rows or an entire table, that data cannot be recovered in the `down()` method. In such
case, the migration is called irreversible, meaning we cannot roll back to
cases, the migration is called irreversible, meaning the database cannot be rolled back to
a previous state of the database. In the above generated code, the `down()`
a previous state. When a migration is irreversible, as in the above generated code, the `down()`
method returns `false` to indicate that the migration cannot be reverted.
method returns `false` to indicate that the migration cannot be reverted.
As an example, let's show the migration about creating a news table.
As an example, let's show the migration about creating a news table.
