Magento 2: настройка базы данных
В данной статье мы подробно рассмотрим как создать базу данны для вашего модуля.
Как настроить декларативную схему
(Configure declarative schema)
До Magento 2.3 разработчики расширений должны были писать код (скрипты PHP) для изменения схемы базы данных. До Magento 2.3 существовали следующие типы скриптов:
- Скрипты InstallData и InstallSchema, которые выполняются при первой установке модуля.
- Инкрементные сценарии UpgradeData и UpgradeSchema, которые дополняют существующую схему модуля.
- Повторяющиеся скрипты, которые выполняются каждый раз, когда вы устанавливаете или обновляете Magento.
Основным недостатком этого подхода является то, что Magento применяет изменения вслепую. Например, в одной версии может быть введен новый столбец базы данных, который будет удален в следующей. Декларативная установка освобождает от этой ненужной работы.
Декларативная установка основана на объявлениях структуры базы данных и используется в таких проектах, как Doctrine. Файлы схемы определяют, какой должна быть структура базы данных, а Magento определяет различия между текущей структурой таблицы и тем, какой она должна быть. Эти различия могут быть представлены атомарными SQL операциями.
Magento отдает приоритет декларативной схеме и выполняет декларативные схемы установки перед патчами данных и схем.
В следующем примере, извлеченном из файла Catalog/etc/db_schema.xml, определяется таблица catalog_product_entity_datetime:
<table name="catalog_product_entity_datetime" resource="default" engine="innodb" comment="Catalog Product Datetime Attribute Backend Table"> <column xsi:type="int" name="value_id" unsigned="false" nullable="false" identity="true" comment="Value ID"/> <column xsi:type="smallint" name="attribute_id" unsigned="true" nullable="false" identity="false" default="0" comment="Attribute ID"/> <column xsi:type="smallint" name="store_id" unsigned="true" nullable="false" identity="false" default="0" comment="Store ID"/> <column xsi:type="int" name="entity_id" unsigned="true" nullable="false" identity="false" default="0" comment="Entity ID"/> <column xsi:type="datetime" name="value" on_update="false" nullable="true" comment="Value"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="value_id"/> </constraint> <constraint xsi:type="foreign" referenceId="CAT_PRD_ENTT_DTIME_ATTR_ID_EAV_ATTR_ATTR_ID" table="catalog_product_entity_datetime" column="attribute_id" referenceTable="eav_attribute" referenceColumn="attribute_id" onDelete="CASCADE"/> <constraint xsi:type="foreign" referenceId="CAT_PRD_ENTT_DTIME_ENTT_ID_CAT_PRD_ENTT_ENTT_ID" table="catalog_product_entity_datetime" column="entity_id" referenceTable="catalog_product_entity" referenceColumn="entity_id" onDelete="CASCADE"/> <constraint xsi:type="foreign" referenceId="CATALOG_PRODUCT_ENTITY_DATETIME_STORE_ID_STORE_STORE_ID" table="catalog_product_entity_datetime" column="store_id" referenceTable="store" referenceColumn="store_id" onDelete="CASCADE"/> <constraint xsi:type="unique" referenceId="CATALOG_PRODUCT_ENTITY_DATETIME_ENTITY_ID_ATTRIBUTE_ID_STORE_ID"> <column name="entity_id"/> <column name="attribute_id"/> <column name="store_id"/> </constraint> <index referenceId="CATALOG_PRODUCT_ENTITY_DATETIME_ATTRIBUTE_ID" indexType="btree"> <column name="attribute_id"/> </index> <index referenceId="CATALOG_PRODUCT_ENTITY_DATETIME_STORE_ID" indexType="btree"> <column name="store_id"/> </index> </table>
Структура db_schema
Файл //etc/db_schema.xml объявляет структуру базы данных модуля.Внимание: Если вы включили подсветку URN, вы можете использовать функцию автозаполнения PhpStorm после выбора узла xsi:type. Это также позволит вам просмотреть, какие атрибуты доступны в каждой строке вашего файла db_schema.xml.
Узел верхнего уровня (Top-level node)
Узел schema определяет расположение файла schema.xsd.Узел таблицы(table node)
Каждый файл db_schema.xml должен содержать один или несколько узлов таблицы. Каждый узел таблицы представляет собой таблицу в базе данных. Узел таблицы может содержать следующие атрибуты:- name Имя таблицы
- engine SQL-движок. Это значение должно быть innodb или memory.
- resource Участок базы данных, на который нужно установить таблицу. Это значение должно быть default, checkout, или sales.
- comment Комментарий к таблице
- column (столбец)
- constraint (ограничение)
- index (показатель)
Column subnode (подузел столбца)
Column subnode определяет столбец в таблице. Каждый column(столбец) требует своего объявления.Column может иметь следующие атрибуты:
- - xsi:type Задает тип столбца. Может принимать следующие значения:
- blob (включает blob, mediumblob, longblob)
- boolean
- date
- datetime
- decimal
- float
- int (включает smallint, bigint, tinyint)
- json
- real (includes decimal, float, double, real)
- smallint
- text (включает текст, средний текст, длинный текст)
- timestamp
- varbinary
- varchar
- - default Инициализирует столбец указанным значением по умолчанию. Значение по умолчанию должно иметь тот же тип данных, что и в xsi:type.
- - disabled Отключает или удаляет объявленную таблицу, столбец, ограничение или индекс.
- - identity Указывает, автоматически ли увеличивается значение столбца.
- - length Задает длину столбца. Может использоваться для типов char, varchar и varbinary.
- - nullable Указывает, может ли столбец быть обнуляемым.
- - onCreate Это триггер DDL, который позволяет перемещать данные из существующего столбца во вновь созданный столбец. Этот триггер работает только когда столбец создан.
- - padding Размер целочисленного столбца.
- - precision Количество цифр после запятой в вещественном типе данных.
- - scale The number of digits after the decimal in a real data type.
- - unsigned Для числовых типов данных указывает, может ли столбец содержать положительные и отрицательные значения или только положительные значения.
Пример:
<column xsi:type="int" name="entity_id" unsigned="true" nullable="false" identity="true" comment="Credit ID"/>
Сonstraint subnode (подузел ограничения)
constraint subnode всегда содержит следующие атрибуты:- type Одно из следующих значений primary (первичный), unique (уникальный), or foreign (внешний)
- referenceId Пользовательский идентификатор, который используется только для сопоставления отношений в области файлов db_schema.xml. Реальный объект в базе данных имеет имя, сгенерированное системой. Самый удобный способ установить значение этого атрибута — использовать значение, записанное в файле модуля db_schema_whitelist.json при запуске команды generate-whitelist.
В следующем примере показан формат internal constraint (внутреннего ограничения):
<constraint xsi:type="primary" referenceId="PRIMARY"> <column name="entity_id"/> </constraint>foreign constraint (внешнее ограничение) похоже на foreign keys(внешние ключи) в SQL. Этот тип ограничения соединяет две таблицы друг с другом. Следующие атрибуты определяют внешнее ограничение:
- - table Название текущей таблицы
- - column Столбец в текущей таблице, который ссылается на определенный столбец в другой таблице.
- - referenceTable Таблица, на которую ссылаются
- - referenceColumn Столбец в referenceTable
- - onDelete Триггер внешнего ключа (foreign key trigger). Значение должно быть CASCADE, SET NULL или NO ACTION.
Пример:
<constraint xsi:type="foreign" referenceId="COMPANY_CREDIT_COMPANY_ID_COMPANY_ENTITY_ID" table="company_credit" column="company_id" referenceTable="company" referenceColumn="entity_id" onDelete="CASCADE"/>index subnode
(подузел индекса) index subnode имеет ту же структуру, что и внутренние constrained (ограничения), но содержит другую логику. В то время как constraints используются для определения ограничений, индексы используются для ускорения операций DQL. Следующие атрибуты определяют индекс:
- - referenceId Пользовательский идентификатор, который используется только для сопоставления отношений в области файлов db_schema.xml. Реальный объект в базе данных имеет имя, сгенерированное системой. Самый удобный способ установить значение этого атрибута — использовать значение, записанное в файле модуля db_schema_whitelist.json при запуске команды generate-whitelist.
- - indexType Допустимые значения btree, fulltext, или hash
<index referenceId="NEWSLETTER_SUBSCRIBER_CUSTOMER_ID" indexType="btree"> <column name="customer_id"/> </index>
Выполнение общих операций с базой данных
Далее будет показано, как выполнять общие операции с базой данных с использованием декларативной схемы. Снимки экрана используют git diff, чтобы проиллюстрировать, как выполнять эти задачи.Создать таблицу
В следующем примере создается таблица declarative_table с четырьмя столбцами. Столбец id_column является первичным ключом.
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> + <table name="declarative_table"> + <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> + <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> + <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> + <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> + <constraint xsi:type="primary" referenceId="PRIMARY"> + <column name="id_column"/> + </constraint> + </table> </schema>!!! При создании новой таблицы не забудьте создать файл db_schema_whitelist.json. !!!
Удалть таблицу
В следующем примере таблица declarative_table была полностью удалена из файла db_schema.xml.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> - <table name="declarative_table"> - <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> - <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> - <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> - <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> - <constraint xsi:type="primary" referenceId="PRIMARY"> - <column name="id_column"/> - </constraint> - </table> </schema>!!! При удалении таблицы не удаляйте ее из файла db_schema_whitelist.json, иначе она не будет удалена. !!!
Переименуем таблицу
Поддерживается переименование таблиц. Декларативная схема создаст новую таблицу с новым именем и удалит таблицу со старым именем. Переименование таблицы через RENAME TABLE НЕ поддерживается. Чтобы перенести данные из другой таблицы, укажите атрибут onCreate в объявлении таблицы и добавьте имя исходной таблицы:onCreate="migrateDataFromAnotherTable(catalog_category_entity)"Обратите внимание, что перенос данных из другой таблицы и одновременное переименование столбцов не поддерживается.
Этот декларативный процесс переименования таблицы не быстрый. Если вам нужно быстро перенести большое количество данных, вы можете создать дамп таблицы CSV, используя --safe-mode=1, и добавить данные вручную, используя исправления (data/recurring patches).
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> + <table name="new_declarative_table" onCreate="migrateDataFromAnotherTable(declarative_table)"> - <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> </table> </schema>!!! При переименовании таблицы не забудьте заново сгенерировать файл db_schema_whitelist.json, чтобы он содержал новое имя в дополнение к старому. !!!
Добавим столбец в таблицу
В следующем примере добавляется столбец date_closed :<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> + <column xsi:type="timestamp" name="date_closed" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> </table> </schema>!!! При добавлении нового столбца в таблицу не забудьте создать файл db_schema_whitelist.json. !!!
Удалим столбец из таблицы
В следующем примере столбец date_closed удаляется путем удаления его узла (column node). Чтобы удалить столбец, объявленный в другом модуле, повторно объявите его, установив для атрибута disabled значение true.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> - <column xsi:type="timestamp" name="date_closed" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> </table> </schema>!!! Столбец можно удалить, только если он существует в файле db_schema_whitelist.json. !!!
Изменим тип столбца
В следующем примере тип столбца Title изменяется с varchar на text.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> - <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> + <column xsi:type="text" name="title" nullable="false" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> </table> </schema>
Переименовать столбец
Чтобы переименовать столбец, удалите исходное объявление столбца и создайте новое. В объявлении нового столбца используйте атрибут onCreate, чтобы указать, из какого столбца следует перенести данные. Используйте следующую конструкцию для переноса данных из той же таблицы.onCreate="migrateDataFrom(entity_id)"!!! При переименовании столбца не забудьте заново сгенерировать файл db_schema_whitelist.json, чтобы он содержал новое имя в дополнение к старому. !!!
Добавление индекса
В следующем примере индекс INDEX_SEVERITY добавляется в таблицу declarative_table.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="text" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> + <index referenceId="INDEX_SEVERITY" indexType="btree"> + <column name="severity"/> + </index> </table> </schema>
Создадим внешний ключ
В следующем примере выбранный constraint node (узел ограничения) определяет характеристики внешнего ключа FL_ALLOWED_SEVERITIES.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> + <constraint xsi:type="foreign" referenceId="FL_ALLOWED_SEVERITIES" table="declarative_table" + column="severity" referenceTable="severities" referenceColumn="severity_identifier" + onDelete="CASCADE"/> </table> </schema>!!! Внешние ключи можно добавлять к таблицам, только если обе таблицы созданы с использованием декларативной схемы (db_schema.xml). !!!
Удалим внешний ключ
В следующем примере внешний ключ FL_ALLOWED_SEVERITIES удаляется путем удаления его constraint node (узла ограничения). Чтобы удалить ограничение, объявленное в другом модуле, повторно объявите его, установив для атрибута disabled значение true.<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <column xsi:type="int" name="severity" unsigned="true" nullable="false" comment="Severity code"/> <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/> <column xsi:type="timestamp" name="time_occurred" comment="Time of event"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> - <constraint xsi:type="foreign" referenceId="FL_ALLOWED_SEVERITIES" table="declarative_table" - column="severity" referenceTable="severities" referenceColumn="severity_identifier" - onDelete="CASCADE"/> </table> </schema>!!! Внешний ключ можно удалить, только если он существует в файле db_schema_whitelist.json. !!!
Пересоздадим внешний ключ
В этом примере модуль A определяет новую таблицу с первичным ключом id_column. Модуль B объявляет собственную схему, в которой он создает новый столбец (new_id_column) и меняет primary index на этот столбец. Модуль B отключает исходный первичный ключ и устанавливает новый первичный ключ со значением referenceId, отличным от PRIMARY. Хотя это значение отличается, настоящее имя первичного ключа в базе данных остается PRIMARY.Module A declaration:
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="id_column" unsigned="true" nullable="false" comment="Entity Id"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="id_column"/> </constraint> </table> </schema>
Module B declaration:
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd"> <table name="declarative_table"> <column xsi:type="int" name="new_id_column" unsigned="true" nullable="false" comment="New Entity Id"/> <constraint xsi:type="primary" referenceId="PRIMARY" disabled="true"/> <constraint xsi:type="primary" referenceId="NEW_PRIMARY"> <column name="new_id_column"/> </constraint> </table> </schema>
Другие задачи
Отключить модуль
Когда модуль отключен в app/etc/config.php, его конфигурация схемы базы данных больше не читается при обновлении или установке. В результате последующие обновления системы перестраивают схему базы данных без таблиц, столбцов или других элементов модуля. Обратите внимание, что файл отключенных модулей db_schema_whitelist.json по-прежнему читается во время обновления установок, поэтому система декларативной схемы (declarative schema system) может выполнять необходимые операции. На практике это означает, что если вы отключите модуль, использующий декларативную схему, и запустите bin/magento setup:upgrade, его таблицы базы данных будут удалены (подробнее см. и обсуждение на https://github.com/magento/magento2/issues/). 24926). Рассмотрите возможность использования setup:upgrade --safe-mode=1 для создания резервной копии базы данных после отключения модуля, а затем, в конечном итоге, setup:upgrade --data-restore=1, если вы снова включаете модуль и хотите выполнить восстановление из этой резервной копии. .Создание белого списка схемы (schema whitelist)
Обратная совместимость должна поддерживаться. Таким образом, декларативная схема не удаляет автоматически таблицы базы данных, столбцы или ключи, которые не определены в файле db_schema.xml. Декларативная схема не может удалить эти элементы, потому что они могут быть объявлены в другом месте, например, в файле Setup/UpgradeSchema.php.!!! Белые списки не могут быть созданы на экземплярах Magento, использующих префикс базы данных. Наличие префикса влияет на имена некоторых сущностей БД, например на имена ключей, и эти имена нельзя использовать в сгенерированных белых списках. Белый список должен создаваться разработчиком расширения в среде разработки без префиксов. !!!
Файл //etc/db_schema_whitelist.json содержит историю всех таблиц, столбцов и ключей, добавленных с помощью декларативной схемы. Это обязательно необходимо, для возможности операций удаления. Его можно сгенерировать вручную или создать автоматически с помощью следующей команды:
bin/magento setup:db-declaration:generate-whitelist [options]
[options] могут быть:
--module-name[=MODULE-NAME] указывает, для какого модуля создать whitelist (белый список). Если имя модуля не указано, то по умолчанию создается whitelist для всех модулей. Вы также можете явно установить --module-name=all.
Следующий пример демонстрирует вызов данной команды для генерирования whitelist для модуля SpaceX_DBSchema:
(перед выполнением - убедитесь что модуль подключён. Если не подключён, выполните: bin/magento setup:upgrade )
bin/magento setup:db-declaration:generate-whitelist --module-name=SpaceX_DBSchema
!!! В Magento 2.3 Alpha команда setup:db-declaration:generate-whitelist называлась Declaration:generate:whitelist. !!!
Рекомендуется создавать новый файл белого списка для каждого релиза. Вы должны создать белый список в любом релизе, который содержит изменения в файле db_schema.xml.
В следующем примере кода показан пример файла db_schema_whitelist.json:
{
"adminnotification_inbox": {
"column": {
"notification_id": true,
"severity": true,
"date_added": true,
"title": true,
"description": true,
"url": true,
"is_read": true,
"is_remove": true
},
"index": {
"ADMINNOTIFICATION_INBOX_SEVERITY": true,
"ADMINNOTIFICATION_INBOX_IS_READ": true,
"ADMINNOTIFICATION_INBOX_IS_REMOVE": true
},
"constraint": {
"PRIMARY": true
}
},
"admin_system_messages": {
"column": {
"identity": true,
"severity": true,
"created_at": true
},
"constraint": {
"PRIMARY": true
}
}
}
!!! Этот файл является временным решением. Он будет удален в будущем, когда скрипты обновления больше не будут поддерживаться. !!!
