README

Yii2 DB toolkit — набор инфраструктурных утилит для работы с БД на уровне миграций и DDL.

Пакет даёт синтаксический и архитектурный сахар для создания таблиц, индексов и внешних ключей, а также небольшие вспомогательные инструменты для унификации миграций между PostgreSQL и MySQL. Использование позволяет просто заводить новые таблицы, получая единую стилистику, на которую можно опираться при дальнейшем проектировании.

What's included

CreateTable — базовый класс миграции для создания таблиц:
- автоматические дефолтные колонки: id, created_at, updated_at, is_active (можно отключать через false)
- декларативное описание индексов и внешних ключей
- автоматическое создание индекса под каждый внешний ключ
- onDelete / onUpdate для FK (с валидацией значений)
- авто-создание FK-колонки при отсутствии в getColumns()
ForeignKeyDTO — DTO для применения FK внутри CreateTable
BaseDictionaryCreateTableMigration — базовая миграция “таблица-справочник”:
- колонки: code, name, description
- unique индекс на code
SchemaIntrospector (read-only) — библиотечная интроспекция схемы БД:
- DTO: SchemaDTO, TableDTO, ColumnDTO, IndexDTO, ForeignKeyDTO
- сбор таблиц/PK/columns/indexes/foreignKeys/comments
- поддержка SQLite (PRAGMA) и общая ветка для остальных драйверов
Функции-утилиты:
- генерация имён idx/fk
- нормализация конфигов
- дефолтные поля
- (опционально) провайдеры/разделение логики по драйверу (PG/MySQL)

What's NOT included

сущности / ActiveRecord
meta-layer BES

Requirements

PHP >= 8.5
yiisoft/yii2 ^2.0.55

Installation

composer require illusiard/yii2-db-toolkit

Quick start

CreateTable

Создайте миграцию, унаследовавшись от CreateTable:

use illusiard\dbtoolkit\components\CreateTable;

final class m240101_000001_create_post_table extends CreateTable
{
    public function getTableName(): string
    {
        return 'post';
    }

    public function getColumns(): array
    {
        return [
            'title' => $this->string(255)->notNull()->comment('Заголовок'),
            'body' => $this->text()->null()->comment('Текст'),
        ];
    }

    public function getIndexes(): array
    {
        return [
            ['title'],
        ];
    }

    public function getForeignKeys(): array
    {
        return [
            'user_id' => ['user', 'id', 'onDelete' => 'RESTRICT', 'onUpdate' => 'CASCADE'],
        ];
    }
}

Disabling default columns

Любую дефолтную колонку можно отключить, вернув false по соответствующему ключу:

public function getColumns(): array
{
    return [
        'id' => false,
        'created_at' => false,
        'updated_at' => false,
        'is_active' => false,

        'code' => $this->string(64)->notNull()->comment('Код'),
    ];
}

BaseDictionaryCreateTableMigration

Отдельно выделен класс для создания таблиц-словарей.

use illusiard\dbtoolkit\components\BaseDictionaryCreateTableMigration;

final class m240101_000002_create_country_dict extends BaseDictionaryCreateTableMigration
{
    public function getTableName(): string
    {
        return 'dict_country';
    }
}

SchemaIntrospector (read-only)

Интроспекция работает с любым yii\db\Connection:

use illusiard\dbtoolkit\schema\SchemaIntrospector;

$introspector = new SchemaIntrospector($db);

$schema = $introspector->introspectSchema();
$table = $introspector->introspectTable('post');

Формат данных для endpoint-слоя:

SchemaDTO::toArray() -> {tables:[...], driver, serverVersion?}
TableDTO::toDetailsArray() -> table, primaryKey, optional primaryKeyName, columns, indexes, foreignKeys

Schema tooling

Для схемного синка доступны четыре шага:

SchemaIntrospector: Connection -> SchemaDTO (текущая схема)
SchemaParser: array -> SchemaDTO (желаемая схема)
SchemaDiffService: current + desired -> SchemaDiffResult (actions в безопасном порядке)
MigrationGeneratorService: SchemaDiffResult -> MigrationCodeResult (php-код миграции)

Минимальный пример desired schema:

$desired = [
    'tables' => [
        [
            'name' => 'device',
            'primaryKey' => ['id'],
            'columns' => [
                ['name' => 'id', 'type' => 'uuid', 'allowNull' => false],
                ['name' => 'status', 'type' => 'string(32)', 'defaultValue' => 'draft'],
            ],
            'indexes' => [
                ['columns' => ['status'], 'unique' => false],
            ],
            'foreignKeys' => [
                [
                    'columns' => 'tenant_id,author_id',
                    'refTable' => 'author',
                    'refColumns' => ['tenant_id', 'id'],
                    'onDelete' => 'CASCADE',
                    'onUpdate' => 'NO ACTION',
                ],
            ],
        ],
    ],
];

primaryKey не зависит от типа колонки: schema diff создаёт и удаляет PK constraint отдельными actions. Для PostgreSQL можно использовать native uuid; для MySQL/MariaDB — выбранное приложением строковое или бинарное представление, например char(36). Составные PK поддерживаются тем же массивом primaryKey.

Ошибки endpoint-слоя (например в BES) остаются на стороне контроллера:

несуществующая таблица: 404 {error:{type:"not_found",table:"..."}}
невалидное имя таблицы: 400 {error:{type:"bad_request",...}}

Tests

Есть unit-тесты (SQLite in-memory) и интеграционные тесты (реальные БД в Docker).

Launching the database

docker compose up -d

Environment variables

Пример .env (используется тестами):

DB_DRIVER=pgsql или DB_DRIVER=mysql
PostgreSQL: DB_PG_HOST, DB_PG_PORT, DB_PG_NAME, DB_PG_USER, DB_PG_PASS
MySQL: DB_MY_HOST, DB_MY_PORT, DB_MY_NAME, DB_MY_USER, DB_MY_PASS

Running tests

Unit (SQLite in-memory):

vendor/bin/phpunit tests/Unit

PostgreSQL:

export $(cat .env | xargs)
DB_DRIVER=pgsql vendor/bin/phpunit

MySQL:

export $(cat .env | xargs)
DB_DRIVER=mysql vendor/bin/phpunit

LICENCE

BSD-3-Clause

illusiard / yii2-db-toolkit

Package info

Security

Statistics