Миграции¶

Синтаксис¶

Синтаксис команды bake следует форме ниже:

$ bin/cake bake migration CreateProducts name:string description:text created modified

При использовании bake для создания таблиц, добавления столбцов и т. п. в вашей базе данных, вы обычно предоставляете две вещи:

• имя миграции, которую вы создадите (CreateProducts в нашем примере)

• столбцы таблицы, которые будут добавлены или удалены в процессе миграции (name: string description: text created modified в нашем примере)

В связи с соглашениями CakePHP, не все изменения схемы могут выполняться с помощью этих команд оболочки.

Кроме того, вы можете создать пустой файл миграции, если хотите получить полный контроль над тем, что нужно выполнить, указав определение столбцов:

$ bin/cake migrations create MyCustomMigration

fieldName:fieldType?[length]:indexType:indexName

Создание таблицы¶

Вы можете использовать bake для создания таблицы:

$ bin/cake bake migration CreateProducts name:string description:text created modified

В приведённой выше командной строке будет создан файл миграции, напоминающий:

<?php
use Migrations\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /**
     * Метод изменения.
     *
     * Более подробная информация об этом методе доступна здесь:
     * https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     * @return void
     */
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string', [
            'default' => null,
            'limit' => 255,
            'null' => false,
        ]);
        $table->addColumn('description', 'text', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('created', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('modified', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->create();
    }
}

Добавление столбцов в существующую таблицу¶

Если имя миграции в командной строке имеет форму «AddXXXToYYY» и за ней следует список имён столбцов и типов, тогда будет создан файл миграции, содержащий код для создания столбцов:

$ bin/cake bake migration AddPriceToProducts price:decimal

Выполнение приведенной выше командной строки сгенерирует:

<?php
use Migrations\AbstractMigration;

class AddPriceToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('price', 'decimal')
              ->update();
    }
}

Добавление столбца в качестве индекса в таблицу¶

Также можно добавлять индексы в столбцы:

$ bin/cake bake migration AddNameIndexToProducts name:string:index

будет сгенерировано:

<?php
use Migrations\AbstractMigration;

class AddNameIndexToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string')
              ->addIndex(['name'])
              ->update();
    }
}

Указание длины поля¶

Если вам нужно указать длину поля, вы можете сделать это в квадратных скобках в поле типа:

$ bin/cake bake migration AddFullDescriptionToProducts full_description:string[60]

Выполнение приведенной выше командной строки будет генерировать:

<?php
use Migrations\AbstractMigration;

class AddFullDescriptionToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('full_description', 'string', [
            'default' => null,
            'limit' => 60,
            'null' => false,
        ])
        ->update();
    }
}

Если длина не указана, значения длины для определённого типа столбцов установятся по умолчания как:

• string: 255

• integer: 11

• biginteger: 20

Изменить столбец из таблицы¶

Таким же образом вы можете сгенерировать миграцию для изменения столбца с помощью командной строки, если имя миграции имеет вид «AlterXXXOnYYY»:

bin/cake bake migration AlterPriceOnProducts name:float

создаст файл:

<?php
use Migrations\AbstractMigration;

class AlterPriceFromProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->changeColumn('name', 'float');
        $table->update();
    }
}

Удаление столбца из таблицы¶

Аналогичным образом вы можете сгенерировать миграцию для удаления столбца с помощью командной строки, если имя миграции имеет форму «RemoveXXXFromYYY»:

$ bin/cake bake migration RemovePriceFromProducts price

создаст файл:

<?php
use Migrations\AbstractMigration;

class RemovePriceFromProducts extends AbstractMigration
{
    public function up()
    {
        $table = $this->table('products');
        $table->removeColumn('price')
              ->save();
    }
}

migrate : Применение миграции¶

После создания или записи файла миграции вам необходимо выполнить одну из следующих команд, чтобы применить изменения в своей базе данных:

# Запуск всех миграций
$ bin/cake migrations migrate

# Миграция к определённой версии, используя опцию ``--target``
# или ``-t`` для краткости.
# Значение - это метка времени, которая имеет префикс имени файла миграции::
$ bin/cake migrations migrate -t 20150103081132

# По умолчанию файлы миграции ищются в каталоге **config/Migrations**.
# Вы можете указать альтернативный каталог, используя опцию ``--source``
# или ``-s`` для краткости.
# В следующем примере будут выполняться миграции в каталоге
# **config/Alternate**
$ bin/cake migrations migrate -s Alternate

# Вы можете запускать миграции используя другое соединение, чем ``default``,
# для этого используйте опцию ``--connection`` или ``-c`` для краткости.
$ bin/cake migrations migrate -c my_custom_connection

# Миграции также могут выполняться для плагинов. Просто используйте опцию
# ``--plugin`` или ``-p`` для краткости.
$ bin/cake migrations migrate -p MyAwesomePlugin

rollback : Откат миграций¶

Команда Rollback используется для отмены предыдущих миграций, выполняемых этим плагином. Это обратное действие по отношения к команде migrate:

# Вы можете вернуться к предыдущей миграции, используя команду
# ``rollback``::
$ bin/cake migrations rollback

# Вы также можете передать номер версии миграции для отката
# к определённой версии::
$ bin/cake migrations rollback -t 20150103081132

Вы также можете использовать параметры --source, --connection и --plugin, как и для migrate.

status : Статус миграции¶

Команда Status выводит список всех миграций вместе с их текущим статусом. Вы можете использовать эту команду, чтобы определить, какие миграции были выполнены:

$ bin/cake migrations status

Вы также можете выводить результаты как форматированную JSON строку, используя опцию --format или -f для краткости.:

$ bin/cake migrations status --format json

Вы также можете использовать параметры --source, --connection и --plugin, как и для migrate.

mark_migrated : Пометка миграций как перенесённые¶

Иногда бывает полезно отметить набор миграций, перенесённых без их фактического запуска. Для этого вы можете использовать команду mark_migrated. Команда работает плавно, как и другие команды.

Вы можете пометить все миграции как перенесенные с помощью этой команды:

$ bin/cake migrations mark_migrated

Вы также можете пометить все миграции до определённой версии как перенесенные с помощью параметра --target:

$ bin/cake migrations mark_migrated --target=20151016204000

Если вы не хотите, чтобы целевая миграция была помечена как перенесённая во время процесса миграции, вы можете использовать флаг --exclude:

$ bin/cake migrations mark_migrated --target=20151016204000 --exclude

Наконец, если вы хотите пометить только перенесённую миграцию, вы можете использовать флаг --only:

$ bin/cake migrations mark_migrated --target=20151016204000 --only

Вы также можете использовать параметры --source, --connection и --plugin, как и для migrate.

Эта команда ожидает номер версии миграции в качестве аргумента:

$ bin/cake migrations mark_migrated 20150420082532

Если вы хотите пометить все миграции как перенесенные, вы можете использовать специальное значение all. Если вы используете его, оно будет отмечать все найденные миграции как перенесенные:

$ bin/cake migrations mark_migrated all

seed : Засеивание базы данных¶

Начиная с 1.5.5, вы можете использовать оболочку migrations для засеивания вашей базы данных. Это использует Phinx library seed feature. По умолчанию файлы семян будут искать в каталоге config/Seeds вашего приложения. Пожалуйста, убедитесь, что вы следуете Phinx instructions to build your seed files.

Что касается миграций, для файлов семян предоставляется интерфейс bake:

# Это создаст файл ArticlesSeed.php в каталоге config/Seeds вашего приложения.
# По умолчанию таблица, которую семя будет пытаться изменить, является "табличной"
    # версией имени файла семени.
$ bin/cake bake seed Articles

# Вы указываете имя таблицы, которую будут изменять семенные файлы,
    # используя опцию ``--table``
$ bin/cake bake seed Articles --table my_articles_table

# Вы можете указать плагин для выпечки
$ bin/cake bake seed Articles --plugin PluginName

# Вы можете указать альтернативное соединение при создании сеялки.
$ bin/cake bake seed Articles --connection connection

Начиная с версии 1.6.4 команда bake seed позволяет создать файл семян с данными, экспортированными из вашей базы данных, с помощью флага --data:

$ bin/cake bake seed --data Articles

По умолчанию он будет экспортировать все строки, найденные в вашей таблице. Вы можете ограничить количество строк, экспортированных с помощью опции -limit:

# Будет экспортировано только первые 10 найденных строк
$ bin/cake bake seed --data --limit 10 Articles

Если вы хотите включить только поле из таблицы в файл семени, вы можете использовать опцию --fields. Она принимает список полей для включения в виде строки значений, разделенных запятой:

# Будет экспортировать только поля `id`, `title` и `excerpt`
$ bin/cake bake seed --data --fields id,title,excerpt Articles

Чтобы засеять вашу базу данных, вы можете использовать подкоманду seed:

# Без параметров подкоманда seed будет запускать все доступные сеялки
# в целевом каталоге, в алфавитном порядке.
$ bin/cake migrations seed

# Вы можете указать только одну сеялку для запуска с использованием
    # опции `--seed`
$ bin/cake migrations seed --seed ArticlesSeed

# Вы можете запускать сеялки из альтернативного каталога
$ bin/cake migrations seed --source AlternativeSeeds

# Вы можете запускать сеялки из плагина
$ bin/cake migrations seed --plugin PluginName

# Вы можете запускать сеялки из определённого соединения
$ bin/cake migrations seed --connection connection

Имейте в виду, что в отличие от миграций сеялки не отслеживаются, а это означает, что одну и ту же сеялку можно применять несколько раз.

use Migrations\AbstractSeed;

class DatabaseSeed extends AbstractSeed
{
    public function run(): void
    {
        $this->call('AnotherSeed');
        $this->call('YetAnotherSeed');

        // Вы можете использовать plugin dot syntax, чтобы
                    // вызывать сеялки из плагина
        $this->call('PluginName.FromPluginSeed');
    }
}

dump : Создание файла дампа для разницы выпечек¶

Команда Dump создаёт файл, который будет использоваться с bake шаблоном migration_diff:

$ bin/cake migrations dump

Каждый сгенерированный файл дампа относится к соединению, из которого он создан (и суффикс как таковой). Это позволяет команде bake migration_diff правильно вычислять разницу, если ваше приложение имеет дело с несколькими базами данных, возможно, от разных поставщиков баз данных.

Файлы дампов создаются в том же каталоге, что и файлы миграции.

Вы также можете использовать параметры --source, --connection и --plugin, как и для migrate.

Создание пользовательских первичных ключей¶

Если вам нужно избегать автоматического создания первичного ключа id при добавлении новых таблиц в базу данных, вы можете использовать второй аргумент метода table():

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products', ['id' => false, 'primary_key' => ['id']]);
        $table
              ->addColumn('id', 'uuid')
              ->addColumn('name', 'string')
              ->addColumn('description', 'text')
              ->create();
    }
}

Вышеупомянутый элемент создаст столбец id с типом CHAR(36), который также является первичным ключом.

$ bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

Кроме того, начиная с Migrations 1.3 был введён новый способ обработки первичного ключа. Для этого ваш класс миграции должен расширить новый класс Migrations\AbstractMigration.

Вы можете указать свойство autoId в классе Migration и установить его в false, что отключит автоматическое создание столбца id. Вам нужно будет вручную создать столбец, который будет использоваться в качестве первичного ключа, и добавить его в объявление таблицы:

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{

    public bool $autoId = false;

    public function up()
    {
        $table = $this->table('products');
        $table
            ->addColumn('id', 'integer', [
                'autoIncrement' => true,
                'limit' => 11
            ])
            ->addPrimaryKey('id')
            ->addColumn('name', 'string')
            ->addColumn('description', 'text')
            ->create();
    }
}

По сравнению с предыдущим способом работы с первичным ключом, этот метод даёт вам возможность больше контролировать определение столбца первичного ключа: unsigned или not, limit, comment и т.д.

Все запечённые миграции и моментальные снимки будут использовать этот новый способ, когда это необходимо.

Параметры сортировки¶

Если вам нужно создать таблицу с другой сортировкой, чем стандартная по умолчанию, вы можете определить её с помощью метода table() в качестве опции:

<?php
use Migrations\AbstractMigration;

class CreateCategoriesTable extends AbstractMigration
{
    public function change()
    {
        $table = $this
            ->table('categories', [
                'collation' => 'latin1_german1_ci'
            ])
            ->addColumn('title', 'string', [
                'default' => null,
                'limit' => 255,
                'null' => false,
            ])
            ->create();
    }
}

Обратите внимание, что это можно сделать только при создании таблицы: в настоящее время нет способа добавить столбец в существующую таблицу с другой сортировкой, чем таблица или база данных. В настоящее время только MySQL и SqlServer поддерживают этот ключ конфигурации.

Обновление имени столбцов и использование объектов Table¶

Если вы используете объект CakePHP ORM Table для управления значениями из своей базы данных вместе с переименованием или удалением столбца, убедитесь, что вы создали новый экземпляр объекта Table после вызова update(). Реестр объектов таблицы очищается после вызова update(), чтобы обновить схему, которая отражается и хранится в объекте Table при создании экземпляра.

Миграции и развёртывание¶

Если вы используете плагин при развёртывании приложения, обязательно очистите кэш ORM, чтобы он обновил метаданные столбца ваших таблиц. В противном случае вы можете столкнуться с ошибками в отношении столбцов, которые не существуют при выполнении операций над этими новыми столбцами. Ядро CakePHP включает Schema Cache Shell который вы можете использовать для выполнения этой операции:

$ bin/cake schema_cache clear

Обязательно прочитайте раздел Schema Cache Shell, если вы хотите узнать больше об этой оболочке.

Переименование таблицы¶

Плагин даёт вам возможность переименовать таблицу, используя метод rename(). В файле миграции вы можете сделать следующее:

public function up()
{
    $this->table('old_table_name')
        ->rename('new_table_name');
}

Пропуск генерации файла schema.lock¶

Для того, чтобы функция diff работала, каждый раз, когда вы переносите, откатываете или выпекаете снимок, создается файл .Lock, чтобы отслеживать состояние вашей схемы базы данных в любой момент времени. Вы можете пропустить создание этого файла, например, при развёртывании в рабочей среде, используя опцию --no-lock для вышеупомянутой команды:

$ bin/cake migrations migrate --no-lock

$ bin/cake migrations rollback --no-lock

$ bin/cake bake migration_snapshot MyMigration --no-lock