Миграции

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

Где лежат

Файлы миграций находятся в папке config/Migrations. Работает с ними плагин Migrations, который уже установлен в новом проекте.

Создание

bin/cake bake migration CreateArticles title:string body:text published:boolean created modified

После имени миграции перечислены столбцы в виде имя:тип. По слову Create в начале имени генератор понимает, что нужна новая таблица articles. В папке появится файл с датой в имени — дата задаёт порядок выполнения.

Файл миграции

// config/Migrations/20260302101500_CreateArticles.php
use Migrations\AbstractMigration;
 
class CreateArticles extends AbstractMigration
{
    public function change(): void
    {
        $table = $this->table('articles');
 
        $table->addColumn('title', 'string', ['limit' => 255, 'null' => false])
            ->addColumn('body', 'text', ['null' => false])
            ->addColumn('published', 'boolean', ['default' => false, 'null' => false])
            ->addColumn('created', 'datetime', ['null' => false])
            ->addColumn('modified', 'datetime', ['null' => false])
            ->create();
    }
}

Столбец id с первичным ключом добавляется сам. Метод change() описывает только изменение — как его отменить, плагин понимает сам. В свежих версиях плагина родительский класс называется BaseMigration, методы у него те же.

Выполнение

bin/cake migrations migrate

Команда выполняет миграции, которые ещё не запускались, и печатает их имена. В базе blog появится таблица articles.

Состояние и откат

Типы столбцов

Изменение таблицы

Чтобы добавить столбец, создают новую миграцию:

bin/cake bake migration AddViewsToArticles views:integer

public function change(): void
{
    $this->table('articles')
        ->addColumn('views', 'integer', ['default' => 0, 'null' => false])
        ->update();
}

Для существующей таблицы цепочку завершает update(), для новой — create(). После bin/cake migrations migrate у статей появится столбец views.

Если ORM не видит столбец

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

bin/cake schema_cache clear

Частая ошибка

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