mirror of
https://github.com/yiisoft/yii.git
synced 2026-03-04 15:24:07 +01:00
293 lines
15 KiB
Plaintext
293 lines
15 KiB
Plaintext
Миграции
|
||
========
|
||
|
||
> Note|Примечание: Миграции доступны с версии 1.1.6.
|
||
|
||
Как и исходный код, структура базы данных изменяется в процессе разработки
|
||
и поддержки приложения. К примеру, во время разработки может понадобиться
|
||
добавить новую таблицу или уже после размещения приложения на сервере добавить
|
||
индекс или столбец. При этом важно отслеживать изменения в структуре базы
|
||
данных (называемые **миграциями**) также, как мы делаем это для нашего исходного кода.
|
||
Если исходный код и база данных не соответствуют друг другу, скорее всего
|
||
всё приложение не будет работать. Именно поэтому в Yii есть поддержка миграций,
|
||
позволяющая отслеживать изменения в базе данных, применять миграции или откатывать
|
||
уже применённые.
|
||
|
||
Ниже приведён пошаговый процесс использования миграций при разрабоке:
|
||
|
||
1. Иван создаёт новую миграцию (например, создающую новую таблицу).
|
||
2. Иван заливает её в систему контроля версий (SVN, GIT или другую).
|
||
3. Андрей обновляется из системы контроля версий и получает новую миграцию.
|
||
4. Андрей применяет миграцию к своей локальной базе данных.
|
||
|
||
|
||
В Yii управление миграциями производится через консольную команду `yiic migrate`,
|
||
которая поддерживает создание новых миграций, применение, откат и повторное
|
||
применение миграций, просмотр истории миграций и новых миграций.
|
||
|
||
Создание миграций
|
||
-----------------
|
||
|
||
Для создания новой миграции (например, создающей таблицу для новостей), мы должны
|
||
ввести в консоли:
|
||
|
||
~~~
|
||
yiic migrate create <name>
|
||
~~~
|
||
|
||
Обязательный параметр `name` должен содержать очень краткое описание миграции
|
||
(такое, как, например, `create_news_table`). Как будет показано далее,
|
||
этот параметр используется как часть имени класса миграции, поэтому использовать
|
||
можно только буквы, цифры и знаки подчёркивания.
|
||
|
||
~~~
|
||
yiic migrate create create_news_table
|
||
~~~
|
||
|
||
Приведённая команда создаст в директории `protected/migrations` файл
|
||
`m101129_185401_create_news_table.php`, содержащий следующее:
|
||
|
||
~~~
|
||
[php]
|
||
class m101129_185401_create_news_table extends CDbMigration
|
||
{
|
||
public function up()
|
||
{
|
||
}
|
||
|
||
/*
|
||
public function down()
|
||
{
|
||
}
|
||
*/
|
||
}
|
||
~~~
|
||
|
||
Стоит отметить, что имя класса совпадает с именем файла и строится как
|
||
`m<timestamp>_<name>`, где `<timestamp>` — это время создания миграции в UTC
|
||
(в формате `yymmdd_hhmmss`), а `<name>` — то, что передано в параметре
|
||
`name` команды.
|
||
|
||
Метод `up()` должен содержать код, выполняющий миграцию, а метод `down()` может
|
||
содержать код, отменяющий сделанное в `up()`.
|
||
|
||
Иногда реализовать `down()` не получается. К примеру, если в `up()` из таблицы
|
||
удаляются данные, в `down()` вернуть их не получится. В этом случае миграция
|
||
называется необратимой, что означает невозможность возврата к предыдущему
|
||
состоянию базы данных.
|
||
|
||
Рассмотрим в качестве примера миграцию, создающую таблицу с новостями.
|
||
|
||
~~~
|
||
[php]
|
||
class m101129_185401_create_news_table extends CDbMigration
|
||
{
|
||
public function up()
|
||
{
|
||
$this->createTable('tbl_news', array(
|
||
'id' => 'pk',
|
||
'title' => 'string NOT NULL',
|
||
'content' => 'text',
|
||
));
|
||
}
|
||
|
||
public function down()
|
||
{
|
||
$this->dropTable('tbl_news');
|
||
}
|
||
}
|
||
~~~
|
||
|
||
Базовый класс [CDbMigration] предоставляет набор методов для работы с данными
|
||
и структурой базы данных. К примеру, при помощи [CDbMigration::createTable]
|
||
можно создать новую таблицу, а [CDbMigration::insert] добавит строку с данными.
|
||
Все эти методы используют подключение к базе данных, возвращаемое
|
||
[CDbMigration::getDbConnection()], что по умолчанию эквивалентно `Yii::app()->db`.
|
||
|
||
> Info|Информация: Как вы могли заметить, методы [CDbMigration] очень похожи на
|
||
методы [CDbCommand]. И это на самом деле так. Единственно отличие в том, что
|
||
методы [CDbMigration] подсчитывают затрачиваемое на их выполнение время и
|
||
выводят сообщения о параметрах методов.
|
||
|
||
|
||
Применение миграций
|
||
-------------------
|
||
|
||
Для того, чтобы применить все новые миграции (то есть привести локальную БД в
|
||
актуальное состояние), следует запустить следующую команду:
|
||
|
||
~~~
|
||
yiic migrate
|
||
~~~
|
||
|
||
Команда покажет список всех новых миграций и, в случае утвердительного ответа,
|
||
по очереди запустит метод `up()` в каждом классе миграции в порядке его создания.
|
||
|
||
После применения миграции в таблицу `tbl_migration` будет внесена соответствующая
|
||
запись. Это позволяет узнать, какие миграции уже применены, а какие нет.
|
||
Если таблица `tbl_migration` не существует, она будет создана автоматически в
|
||
базе данных, указанной в компоненте `db` приложения.
|
||
|
||
Иногда требуется применить лишь одну или несколько новых миграций. Для этого можно
|
||
использовать следующую команду:
|
||
|
||
~~~
|
||
yiic migrate up 3
|
||
~~~
|
||
|
||
При этом применятся три новых миграции. Вместо трёх можно указать
|
||
любое количество применяемых миграций.
|
||
|
||
Также можно привести состояние базы данных к определённой версии:
|
||
|
||
~~~
|
||
yiic migrate to 101129_185401
|
||
~~~
|
||
|
||
В качестве параметра, указывающего версию, к которой надо привести базу данных,
|
||
используется часть имени файла, соответствующая времени создании миграции.
|
||
Если между последней применённой и указанной миграциями несколько миграций, то все
|
||
они будут применены. Если указанная миграция уже применялась, то будет произведён
|
||
откат всех миграций, применённых после неё (описано в следующем разделе).
|
||
|
||
|
||
Откат миграций
|
||
--------------
|
||
|
||
Для отката одной или нескольких последних применённых миграций можно
|
||
воспользоваться следующей командой:
|
||
|
||
~~~
|
||
yiic migrate down [step]
|
||
~~~
|
||
|
||
где необязательный параметр `step` задаёт количество миграций, которые надо откатить.
|
||
По умолчанию откатывается одна последняя применённая миграция.
|
||
|
||
Как было описано ранее, не все миграции можно откатить. При попытке отката таких
|
||
миграций будет выброшено исключение и процесс отката будет прерван.
|
||
|
||
|
||
Повторное применение миграций
|
||
-----------------------------
|
||
|
||
Повторное примение миграции производится путём последовательного отката и применения.
|
||
Осуществить это можно следующей командой:
|
||
|
||
~~~
|
||
yiic migrate redo [step]
|
||
~~~
|
||
|
||
где необязательный параметр `step` указывает количество миграций, которые необходимо
|
||
применить ещё раз. По умолчанию повторяется одна последняя миграция.
|
||
|
||
|
||
Просмотр информации о миграциях
|
||
-------------------------------
|
||
|
||
Кроме применения и отката миграций инструмент миграций может отображать историю
|
||
миграций и новые, ещё не применённые миграции.
|
||
|
||
~~~
|
||
yiic migrate history [limit]
|
||
yiic migrate new [limit]
|
||
~~~
|
||
|
||
Здесь параметр `limit` указывает количество отображаемых миграций. Если `limit`
|
||
не указан, показываются все миграции.
|
||
|
||
Первая команда показывает уже применённые миграции, вторая — миграции, которые
|
||
ещё не были применены.
|
||
|
||
|
||
Изменение истории миграций
|
||
--------------------------
|
||
|
||
Иногда требуется изменить историю миграций так, чтобы текущая версия была
|
||
заменена на указанную без применения или отката миграций. Часто это требуется
|
||
при созданнии новой миграции. Для этого можно использовать следующую команду:
|
||
|
||
~~~
|
||
yiic migrate mark 101129_185401
|
||
~~~
|
||
|
||
Эта команда очень похожа на `yiic migrate to`, но она лишь изменяет таблицу истории
|
||
миграций до указанной версии без применения или отката самих миграций.
|
||
|
||
|
||
Настройка команды миграций
|
||
--------------------------
|
||
|
||
Есть несколько способов настроить команду миграций.
|
||
|
||
### Используя параметры командной строки
|
||
|
||
Команда миграций может быть настроена четыремя опциями:
|
||
|
||
* `interactive`: использовать ли интерактивный режим. По умолчанию true, то есть
|
||
при пременением миграции будет выводиться подтверждение. Если параметр выставлен
|
||
в false, то миграции можно применить в фоновом режиме.
|
||
|
||
* `migrationPath`: указывает директорию, в которой хранятся все файлы миграций.
|
||
Путь должен указываться в формате псевдонима и соответствующая ему директория должна
|
||
существовать. Если параметр не указан, будет использована поддиректория
|
||
`migrations`, находящаяся внутри директории с приложением;
|
||
|
||
* `migrationTable`: указывает имя таблицы в базе данных, которая хранит историю
|
||
миграций. По умолчанию оно равно `tbl_migration`. Структура таблицы следующая:
|
||
`version varchar(255) primary key, apply_time integer`;
|
||
|
||
* `connectionID`: указывает идентификатор компонента базы данных.
|
||
По умолчанию это 'db';
|
||
|
||
* `templateFile`: указывает путь к файлу, который используется как шаблон
|
||
для генерации классов миграций. Путь должен указываться как псевдоним
|
||
(то есть как `application.migrations.template`). Если путь не задан, будет
|
||
использоваться внутренний шаблон. В шаблоне токен `{ClassName}` будет заменён
|
||
именем класса миграции.
|
||
|
||
Для указания опций используется следующий формат:
|
||
|
||
~~~
|
||
yiic migrate up --option1=value1 --option2=value2 ...
|
||
~~~
|
||
|
||
К примеру, если необходимо мигрировать модуль `forum`, файлы миграций которого
|
||
расположены в директории модуля `migrations`, можно воспользоваться следующей командой:
|
||
|
||
~~~
|
||
yiic migrate up --migrationPath=ext.forum.migrations
|
||
~~~
|
||
|
||
|
||
### Глобальная конфигурация команды
|
||
|
||
В то время, как опции командной строки позволяют нам на лету конфигурировать команду
|
||
миграций, иногда требуется применить настройки раз и навсегда. К примеру, нам
|
||
может понадобиться использовать другую таблицу для хранения истории миграций или
|
||
использовать свой шаблон миграции. Это можно сделать, изменив настройки консольного
|
||
приложения следующим образом:
|
||
|
||
~~~
|
||
[php]
|
||
return array(
|
||
......
|
||
'commandMap'=>array(
|
||
'migrate'=>array(
|
||
'class'=>'system.cli.commands.MigrateCommand',
|
||
'migrationPath'=>'application.migrations',
|
||
'migrationTable'=>'tbl_migration',
|
||
'connectionID'=>'db',
|
||
'templateFile'=>'application.migrations.template',
|
||
),
|
||
......
|
||
),
|
||
......
|
||
);
|
||
~~~
|
||
|
||
Теперь, при запуске команды `migrate`, указанные выше настройки будут применены
|
||
без ввода каких-либо дополнительных параметров.
|
||
|
||
|
||
<div class="revision">$Id: database.query-builder.txt 2842 2011-01-12 21:31:22Z alexander.makarow $</div> |