Skip to content

Y
yii2
Commit 3a7f6b13 by Nobuo Kihara
Options

docs/guide-ja/db-migrations.md - completed [ci skip]

parent e4c95ff0
Showing with 116 additions and 145 deletions
docs/guide-ja/README.md
...@@ -77,7 +77,7 @@ All Rights Reserved. ...@@ -77,7 +77,7 @@ All Rights Reserved.
* [データアクセスオブジェクト](db-dao.md): データベースへの接続、基本的なクエリ、トランザクション、および、スキーマ操作 * [データアクセスオブジェクト](db-dao.md): データベースへの接続、基本的なクエリ、トランザクション、および、スキーマ操作
* [クエリビルダ](db-query-builder.md): シンプルな抽象レイヤを使ってデータベースに対してクエリを行う * [クエリビルダ](db-query-builder.md): シンプルな抽象レイヤを使ってデータベースに対してクエリを行う
* [アクティブレコード](db-active-record.md): アクティブレコード ORM、レコードの読み出しと操作、リレーションの定義 * [アクティブレコード](db-active-record.md): アクティブレコード ORM、レコードの読み出しと操作、リレーションの定義
* **翻訳中** [マイグレーション](db-migrations.md): チーム開発環境においてデータベースにバージョンコントロールを適用 * [マイグレーション](db-migrations.md): チーム開発環境においてデータベースにバージョンコントロールを適用
* **TBD** [Sphinx](db-sphinx.md) * **TBD** [Sphinx](db-sphinx.md)
* **TBD** [Redis](db-redis.md) * **TBD** [Redis](db-redis.md)
* **TBD** [MongoDB](db-mongodb.md) * **TBD** [MongoDB](db-mongodb.md)
......
docs/guide-ja/db-migrations.md
...@@ -62,23 +62,21 @@ class m101129_185401_create_news_table extends \yii\db\Migration ...@@ -62,23 +62,21 @@ class m101129_185401_create_news_table extends \yii\db\Migration
} }
``` ```
Notice that the class name is the same as the file name, and follows the pattern クラス名はファイル名と同じであり、`m<timestamp>_<name>` というパターンに従います。ここで、
`m<timestamp>_<name>`, where:
* `<timestamp>` refers to the UTC timestamp (in the * `<timestamp>` は、マイグレーションが作成された (`yymmdd_hhmmss` という書式の) UTC タイムスタンプであり、
format of `yymmdd_hhmmss`) when the migration is created, * `<name>` は、コマンドの `name` パラメータから取られた文字列です。
* `<name>` is taken from the command's `name` parameter.
In the class, the `up()` method should contain the code implementing the actual database クラスの中では、`up()` メソッドが、実際のデータベースマイグレーションを実装するコードを含むべきメソッドです。
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()`. 言い換えると、`up()` メソッドが実際にデータベースを変更するコードを実行します。
`down()` メソッドは、`up()` によって加えられた変更を取り消すコードを含むことが出来ます。
Sometimes, it is impossible for the `down()` to undo the database migration. For example, if the migration deletes 場合によっては、`down()` がデータベースマイグレーションを取り消すことが出来ないことがあります。
table rows or an entire table, that data cannot be recovered in the `down()` method. In such 例えば、マイグレーションがテーブルの行やテーブル全体を削除した場合は、そのデータを `down()` メソッドで復旧することは出来ません。
cases, the migration is called irreversible, meaning the database cannot be rolled back to そのような場合には、マイグレーションは不可逆であると呼ばれ、データベースを以前の状態にロールバックすることは出来ません。
a previous state. When a migration is irreversible, as in the above generated code, the `down()` マイグレーションが不可逆である場合は、生成された上記のコードのように、`down()` メソッドは `false` を返して、マイグレーションが取り消せないものであることを示します。
method returns `false` to indicate that the migration cannot be reverted.
As an example, let's show the migration for creating a news table. 例として、新しいテーブルを作成するマイグレーションを示しましょう。
```php ```php
...@@ -103,30 +101,25 @@ class m101129_185401_create_news_table extends \yii\db\Migration ...@@ -103,30 +101,25 @@ class m101129_185401_create_news_table extends \yii\db\Migration
} }
``` ```
The base class [[\yii\db\Migration]] exposes a database connection via the `db` 基底クラスである [[\yii\db\Migration]] が、データベース接続を `db` プロパティによって提供しています。
property. You can use it for manipulating data and the schema of a database. これを使って、データベースのデータとスキーマを操作することが出来ます。
The column types used in this example are abstract types that will be replaced この例で使われているカラムのタイプは抽象的なタイプであり、Yii によって、あなたが使用するデータベース管理システムに応じて、対応するタイプに置き換えられます。
by Yii with the corresponding types depending on your database management system. 抽象的なタイプを使うと、データベースに依存しないマイグレーションを書くことが出来ます。
You can use them to write database independent migrations. 例えば、`pk` は、MySQL では `int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY` に置き換えられ、sqlite では `integer PRIMARY KEY AUTOINCREMENT NOT NULL` に置き換えられます。
For example `pk` will be replaced by `int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY` さらに詳細な説明と、利用可能なタイプについては、[[yii\db\QueryBuilder::getColumnType()]] のドキュメントを参照してください。
for MySQL and `integer PRIMARY KEY AUTOINCREMENT NOT NULL` for sqlite. また、カラムのタイプを定義するのに、[[yii\db\Schema]] で定義されている定数を使うことも出来ます。
See documentation of [[yii\db\QueryBuilder::getColumnType()]] for more details and a list
of available types. You may also use the constants defined in [[yii\db\Schema]] to
define column types.
> Note: You can add constraints and other custom table options at the end of the table description by > Note|注意: テーブル定義の最後に、単純な文字列として指定された、制約やその他の特別なテーブルオプションを追加することが出来ます。
> specifying them as a simple string. For example, in the above migration, after the `content` attribute definition > 例えば、上記のマイグレーションでは、`content` 属性の定義の後に、`'CONSTRAINT ...'` やその他の特別なオプションを書くことが出来ます。
> you can write `'CONSTRAINT ...'` or other custom options.
Transactional Migrations トランザクションを使うマイグレーション
------------------------ --------------------------------------
While performing complex DB migrations, we usually want to make sure that each 複雑な DB マイグレーションを実行するときは、通常、データベースの一貫性と整合性を保つために、個々のマイグレーションが全体として成功または失敗することを保証する必要があります。
migration succeeds or fail as a whole so that the database maintains its この目的を達成するために、DB トランザクションを利用することが出来ます。
consistency and integrity. In order to achieve this goal, we can exploit この目的のためには、`safeUp` と `safeDown` という特別なメソッドを使います。
DB transactions. We use the special methods `safeUp` and `safeDown` for these purposes.
```php ```php
...@@ -158,178 +151,160 @@ class m101129_185401_create_news_table extends \yii\db\Migration ...@@ -158,178 +151,160 @@ class m101129_185401_create_news_table extends \yii\db\Migration
} }
``` ```
When your code uses more then one query it is recommended to use `safeUp` and `safeDown`. 使用するクエリが一つだけでない場合は、`safeUp` と `safeDown` を使うことを推奨します。
> Note: Not all DBMS support transactions. And some DB queries cannot be put > Note|注意: 全ての DBMS がトランザクションをサポートしている訳ではありません。
> into a transaction. In this case, you will have to implement `up()` and > また、トランザクションに入れることが出来ない DB クエリもあります。
> `down()`, instead. In the case of MySQL, some SQL statements may cause > その場合には、代りに、`up()` と `down()` を実装しなければなりません。
> [implicit commit](http://dev.mysql.com/doc/refman/5.1/en/implicit-commit.html). > また、MySQL の場合は、[暗黙のコミット](http://dev.mysql.com/doc/refman/5.1/en/implicit-commit.html) を引き起こす SQL 文があります。
Applying Migrations マイグレーションを適用する
------------------- --------------------------
To apply all available new migrations (i.e., make the local database up-to-date), 利用できる全ての新しいマイグレーションを適用する (すなわち、ローカルのデータベースを最新の状態にする) ためには、次のコマンドを実行します。
run the following command:
``` ```
yii migrate yii migrate
``` ```
The command will show the list of all new migrations. If you confirm you want to apply コマンドを実行すると、すべての新しいマイグレーションが一覧表示されます。
the migrations, it will run the `up()` method in every new migration class, one マイグレーションを適用することを確認すると、クラス名のタイムスタンプの値の順に、一つずつ、すべての新しいマイグレーションクラスの `up()` メソッドが実行されます。
after another, in the order of the timestamp value in the class name.
マイグレーションを適用した後に、マイグレーションツールは `migration` という名前のデータベーステーブルに記録を残します。
これによって、ツールは、どのマイグレーションが適用済みで、どのマイグレーションが適用されていないかを特定することが出来ます。
`migration` テーブルが存在しない場合は、ツールは `db` [アプリケーションコンポーネント](structure-application-components.md)によって指定されたデータベースの中にテーブルを自動的に作成します。
After applying a migration, the migration tool will keep a record in a database 時として、新しいマイグレーションを一個また数個だけ適用したい場合があります。その場合は、次のコマンドを使うことが出来ます。
table named `migration`. This allows the tool to identify which migrations
have been applied and which have not. If the `migration` table does not exist,
the tool will automatically create it in the database specified by the `db`
[application component](structure-application-components.md).
Sometimes, we may only want to apply one or a few new migrations. We can use the
following command:
``` ```
yii migrate/up 3 yii migrate/up 3
``` ```
This command will apply the next 3 new migrations. Changing the value 3 will allow このコマンドは、次の新しいマイグレーションを 3 個適用します。3 という値を変更して、適用されるマイグレーションの数を変更することが出来ます。
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 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 最後に適用されたマイグレーションと指定されたマイグレーションの間に複数のマイグレーションがある場合は、それらのマイグレーションがすべて適用されます。
the last applied migration and the specified migration, all these migrations 指定されたマイグレーションが適用済みである場合は、その後に適用されたすべてのマイグレーションが取り消されます (次の節で説明します)。
will be applied. If the specified migration has been applied before, then all
migrations applied after it will be reverted (to be described in the next section).
Reverting Migrations マイグレーションを取り消す
-------------------- --------------------------
適用された最後のマイグレーション (一個または複数個) を取り消したい場合は、下記のコマンドを使うことが出来ます。
To revert the last migration step or several applied migrations, we can use the following
command:
``` ```
yii migrate/down [step] yii migrate/down [step]
``` ```
where the optional `step` parameter specifies how many migrations to be reverted ここで、オプションの `step` パラメータは何個のマイグレーションを取り消すかを指定するものです。
back. It defaults to 1, meaning only the last applied migration will be reverted back. デフォルト値は 1 で、適用された最後のマイグレーションだけが取り消すされることを意味します。
As we described before, not all migrations can be reverted. Trying to revert 前に説明したように、全てのマイグレーションが取り消せるとは限りません。
such migrations will throw an exception and stop the entire reverting process. 取り消せないマイグレーションを取り消そうとすると例外が投げられて、取り消しのプロセス全体が終了させられます。
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] yii migrate/redo [step]
``` ```
where the optional `step` parameter specifies how many migrations to be redone. ここで、オプションの `step` パラメータは何個のマイグレーションを再適用するかを指定するものです。
It defaults to 1, which means only the last migration will be redone. デフォルト値は 1 で、最後のマイグレーションだけが再適用されることを意味します。
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/history [limit]
yii migrate/new [limit] yii migrate/new [limit]
``` ```
where the optional parameter `limit` specifies the number of migrations to be ここで、オプションの `limit` パラメータは、何個のマイグレーションを表示するかを指定するものです。
displayed. If `limit` is not specified, all available migrations will be displayed. `limit` が指定されない場合は、利用可能な全てのマイグレーションが表示されます。
The first command shows the migrations that have been applied, while the second 最初のコマンドは適用済みのマイグレーションを表示し、第二のコマンドはまだ適用されていないマイグレーションを表示します。
command shows the migrations that have not been applied.
Modifying Migration History マイグレーション履歴を修正する
--------------------------- ------------------------------
Sometimes, we may want to modify the migration history to a specific migration 時として、実際には関係のあるマイグレーションを適用または取り消すことなく、マイグレーション履歴を特定のマイグレーションバージョンに修正したい場合があります。
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 yii migrate/mark 101129_185401
``` ```
This command is very similar to `yii migrate/to` command, except that it only このコマンドは `yii migrate/to` コマンドと非常によく似ていますが、マイグレーションを適用または取り消すことなく、マイグレーション履歴テーブルを指定されたバージョンに修正することだけを行うという点で違っています。
modifies the migration history table to the specified version without applying
or reverting the migrations.
Customizing Migration Command マイグレーションコマンドをカスタマイズする
----------------------------- ------------------------------------------
There are several ways to customize the migration command. マイグレーションコマンドをカスタマイズする方法がいくつかあります。
### Use Command Line Options ### コマンドラインオプションを使う
The migration command comes with a few options that can be specified on the command マイグレーションコマンドには、コマンドラインで指定できるいくつかのオプションがあります。
line:
* `interactive`: boolean, specifies whether to perform migrations in an * `interactive`: 真偽値。マイグレーションを対話モードで実行するかどうかを指定します。
interactive mode. Defaults to true, meaning the user will be prompted when デフォルト値は true で、指定されたマイグレーションを実行するときに、ユーザは何らかの入力を促されます。
performing a specific migration. You may set this to false so the このオプションを false にセットして、マイグレーションがバックグラウンドプロセスとして実行されるようにすることが出来ます。
migrations are performed as a background process.
* `migrationPath`: string, specifies the directory storing all migration class * `migrationPath`: 文字列。全てのマイグレーションクラスファイルを保存しているディレクトリを指定します。
files. This must be specified in terms of a path alias, and the corresponding このパスは、パスエイリアスの形式で指定されなければならず、また、対応するディレクトリが存在する必要があります。
directory must exist. If not specified, it will use the `migrations` このオプションが指定されない場合は、アプリケーションのベースパスの下の `migrations` サブディレクトリが使われます。
sub-directory under the application base path.
* `migrationTable`: string, specifies the name of the database table for storing * `migrationTable`: 文字列。マイグレーション履歴の情報を保存するためのデータベーステーブル名を指定します。
migration history information. It defaults to `migration`. The table デフォルト値は `migration` です。このテーブルは、`version varchar(255) primary key, apply_time integer` という構造を持ちます。
structure is `version varchar(255) primary key, apply_time integer`.
* `db`: string, specifies the ID of the database [application component](structure-application-components.md). * `db`: 文字列。データベース [アプリケーションコンポーネント](structure-application-components.md) の ID を指定します。
Defaults to 'db'. デフォルト値は 'db' です。
* `templateFile`: string, specifies the path of the file to be served as the code * `templateFile`: 文字列。マイグレーションクラスを生成するためのコードテンプレートとして使われるファイルのパスを指定します。
template for generating the migration classes. This must be specified in terms このパスは、パスエイリアスの形式で指定しなければなりません (例えば、`application.migrations.template`)。
of a path alias (e.g. `application.migrations.template`). If not set, an 指定されない場合は、内部テンプレートが使用されます。
internal template will be used. Inside the template, the token `{ClassName}` テンプレートの中の `{ClassName}` というトークンが実際のマイグレーションクラス名によって置き換えられます。
will be replaced with the actual migration class name.
To specify these options, execute the migrate command using the following format: これらのオプションを指定するためには、下記の書式を使って migrate コマンドを実行します。
``` ```
yii migrate/up --option1=value1 --option2=value2 ... yii migrate/up --option1=value1 --option2=value2 ...
``` ```
For example, if we want to migrate a `forum` module whose migration files 例えば、`forum` モジュールのためのマイグレーションを実行するときに、マイグレーションファイルがモジュールの `migrations` ディレクトリに置かれている場合には、下記のコマンドを使うことが出来ます。
are located within the module's `migrations` directory, we can use the following
command:
``` ```
yii migrate/up --migrationPath=@app/modules/forum/migrations yii migrate/up --migrationPath=@app/modules/forum/migrations
``` ```
### Configure Command Globally ### コマンドをグローバルに構成する
コマンドラインオプションを使ってマイグレーションコマンドをその場その場で構成することも出来ますが、場合によっては、一度にまとめてコマンドを構成しておきたいこともあります。
例えば、マイグレーションの履歴を保存するのに別のテーブルを使用したいとか、カスタマイズしたマイグレーションテンプレートを使用したいとかです。
そうするためには、コンソールアプリケーションの構成情報ファイルを以下のように修正します。
While command line options allow us to configure the migration command
on-the-fly, sometimes we may want to configure the command once for all.
For example, we may want to use a different table to store the migration history,
or we may want to use a customized migration template. We can do so by modifying
the console application's configuration file like the following,
```php ```php
'controllerMap' => [ 'controllerMap' => [
...@@ -340,26 +315,23 @@ the console application's configuration file like the following, ...@@ -340,26 +315,23 @@ the console application's configuration file like the following,
] ]
``` ```
Now if we run the `migrate` command, the above configurations will take effect これで、`migrate` コマンドを実行すると、上記の構成情報が効果を発揮して、毎回コマンドラインオプションを入力する必要がなくなります。
without requiring us to enter the command line options every time. Other command options その他のコマンドラインオプションも、このようにして構成することが出来ます。
can be also configured this way.
### Migrating with Multiple Databases ### 複数のデータベースのマイグレーション
By default, migrations will be applied to the database specified by the `db` [application component](structure-application-components.md). 既定では、マイグレーションは `db` [アプリケーションコンポーネント](structure-application-components.md) によって指定されるデータベースに対して適用されます。
You may change it by specifying the `--db` option, for example, これは、`--db` オプションを指定することによって変更することが出来ます。例えば、
``` ```
yii migrate --db=db2 yii migrate --db=db2
``` ```
The above command will apply *all* migrations found in the default migration path to the `db2` database. 上記のコマンドは、既定のマイグレーションパスに置かれている *全ての* マイグレーションを `db2` データベースに適用するものです。
If your application works with multiple databases, it is possible that some migrations should be applied アプリケーションが複数のデータベースを扱っている場合は、いくつかのマイグレーションはあるデータベースに適用されなければならず、他のマイグレーションは別のデータベースに適用されなければならない、ということがあり得ます。
to one database while some others should be applied to another database. In this case, it is recommended that そのような場合には、異なるデータベースごとに基底マイグレーションクラスを作成して、下記のように [[yii\db\Migration::init()]] メソッドをオーバーライドすることを推奨します。
you create a base migration class for each different database and override the [[yii\db\Migration::init()]]
method like the following,
```php ```php
public function init() public function init()
...@@ -369,17 +341,16 @@ public function init() ...@@ -369,17 +341,16 @@ public function init()
} }
``` ```
To create a migration that should be applied to a particular database, simply extend from the corresponding こうすると、特定のデータベースに適用されるべきマイグレーションを作成するためには、対応する基底マイグレーションクラスから拡張するだけで済みます。
base migration class. Now if you run the `yii migrate` command, each migration will be applied to its corresponding database. これで、`yii migrate` コマンドを実行すると、全てのマイグレーションはそれぞれ対応するデータベースに対して適用されるようになります。
> Info: Because each migration uses a hardcoded DB connection, the `--db` option of the `migrate` command will > Info|情報: それぞれのマイグレーションはハードコードされた DB 接続を使用しますので、`migrate` コマンドの `--db` オプションは効果を持ちません。
have no effect. Also note that the migration history will be stored in the default `db` database. また、マイグレーション履歴はデフォルトの `db` データベースに保存されることに注意してください。
If you want to support changing the DB connection via the `--db` option, you may take the following alternative `--db` オプションによる DB 接続の変更をサポートしたい場合は、次のような別の方法で複数のデータベースを扱うことが出来ます。
approach to work with multiple databases.
For each database, create a migration path and save all corresponding migration classes there. To apply migrations, それぞれのデータベースについて、マイグレーションパスを作成し、対応する全てのマイグレーションクラスをそこに保存します。
run the command as follows, マイグレーションを適用するためには、次のようなコマンドを実行します。
``` ```
yii migrate --migrationPath=@app/migrations/db1 --db=db1 yii migrate --migrationPath=@app/migrations/db1 --db=db1
...@@ -387,4 +358,4 @@ yii migrate --migrationPath=@app/migrations/db2 --db=db2 ...@@ -387,4 +358,4 @@ yii migrate --migrationPath=@app/migrations/db2 --db=db2
... ...
``` ```
> Info: The above approach stores the migration history in different databases specified via the `--db` option. > Info|情報: 上記の方法では、マイグレーション履歴は `--db` オプションによって指定された別々のデータベースに保存されます。
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment