Таблицы плагина описываются в XML, а изменения схемы выполняются шагами PHP. Сама идея простая, но на ней падает больше обновлений, чем на любом другом участке плагина: забытый savepoint, поле без значения по умолчанию, правка только install.xml. Ниже я разбираю устройство XMLDB, затем самые частые поломки в формате «симптом, причина, что делать». Тему можно читать вместе с материалом про обновление Moodle: там обновляется всё, а здесь лишь схема одного плагина.
Как Moodle работает с базой
XMLDB это слой, который описывает таблицы независимо от СУБД. По одному и тому же описанию Moodle создаёт таблицы в MariaDB, MySQL и PostgreSQL, учитывая различия в типах. Поэтому в плагине нельзя писать «сырые» запросы CREATE TABLE: они будут работать на одной СУБД и ломаться на другой. Для обращений к данным используется объект $DB, для изменений схемы менеджер $DB->get_manager().
У имён есть ограничения. Название таблицы начинается с имени компонента (local_hello_note), префикс сайта (обычно mdl_) Moodle добавляет сам. Длина имени без префикса ограничена, поэтому длинные слова сокращайте заранее. Нельзя называть поля зарезервированными словами SQL (user, order, group, desc, часто путают с text), редактор XMLDB такие имена отвергает. Вместо order используйте sortorder.
install.xml: описание для чистой установки
Файл можно писать руками, но безопаснее собирать в редакторе XMLDB: «Администрирование → Разработка → XMLDB editor». Он генерирует корректный XML и сразу проверяет типы и длины. Результат выглядит так:
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="local/hello/db" VERSION="20261101" COMMENT="Hello plugin tables"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd">
<TABLES>
<TABLE NAME="local_hello_note" COMMENT="User notes">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="true"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false"/>
<FIELD NAME="notetext" TYPE="text" NOTNULL="true" SEQUENCE="false"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id"/>
<KEY NAME="userid" TYPE="foreign" FIELDS="userid" REFTABLE="user" REFFIELDS="id"/>
</KEYS>
<INDEXES>
<INDEX NAME="userid_time" UNIQUE="false" FIELDS="userid, timecreated"/>
</INDEXES>
</TABLE>
</TABLES>
</XMLDB>
Здесь есть всё, что я ожидаю увидеть в любой таблице плагина: автоинкрементный id, внешний ключ на пользователя, метка времени как целое число и индекс под реальный запрос. Тип text не может иметь значение по умолчанию, это ограничение СУБД. Индекс стоит добавлять там, где вы будете фильтровать: по пользователю, курсу, дате. Не добавляйте индексы «на всякий случай»: каждый замедляет запись.
Атрибут VERSION у корневого элемента носит справочный характер и в логике обновления не участвует. Решает номер версии плагина в version.php.
upgrade.php: шаги для существующих сайтов
Пусть в версии 2026110200 вы добавили в таблицу поле status. Сначала правим install.xml, чтобы новые установки создавались сразу с полем. Потом пишем шаг для тех, у кого плагин уже стоит:
<?php
defined('MOODLE_INTERNAL') || die();
function xmldb_local_hello_upgrade($oldversion) {
global $DB;
$dbman = $DB->get_manager();
if ($oldversion < 2026110200) {
$table = new xmldb_table('local_hello_note');
$field = new xmldb_field('status', XMLDB_TYPE_INTEGER, '2', null,
XMLDB_NOTNULL, null, '0', 'notetext');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
upgrade_plugin_savepoint(true, 2026110200, 'local', 'hello');
}
return true;
}
Имя функции строится строго: xmldb_, компонент, _upgrade. Условие сравнивает старую версию с номером шага. Внутри каждого шага проверка существования (field_exists, table_exists, index_exists) делает его повторяемым, то есть безопасным при повторном запуске после сбоя. Завершается шаг вызовом upgrade_plugin_savepoint() с тем же номером, типом и именем плагина. Файл с этой функцией вызывается только тогда, когда версия в version.php больше сохранённой, поэтому не забудьте её поднять до значения последнего шага или выше.
Если нужно создать новую таблицу, откройте тот же редактор XMLDB и скопируйте PHP-код, который он предлагает для создания. Либо опишите таблицу в install.xml и установите её командой менеджера по описанию из файла: для этого в API есть метод установки одной таблицы из XML.
Разбор типичных поломок
| Симптом | Причина | Что делать |
|---|---|---|
| Новое поле есть на свежей установке, на рабочем сайте его нет | Поправили только install.xml | Добавить шаг в upgrade.php и поднять версию |
| При обновлении ошибка про обязательное поле без значения по умолчанию | Добавляется обязательное поле без значения по умолчанию в таблицу, где уже есть строки | Задать значение по умолчанию, при необходимости заполнить данные отдельным шагом |
| Шаг выполняется при каждом обновлении | Нет upgrade_plugin_savepoint или в нём не тот номер | Добавить вызов с номером шага, равным условию |
| Ошибка о том, что поле уже существует, после неудачного апгрейда | Шаг не проверяет существование и запущен повторно | Добавить проверки field_exists и аналогичные |
| Не удаётся удалить поле | На него ссылается индекс или ключ | Сначала удалить индекс или ключ, потом поле |
| Версия в базе больше, чем в файле | Откатили код, не откатив базу | Вернуть код той версии или восстановить базу из копии |
| Обновление на тестовой копии прошло, на рабочем упало | Разные СУБД или реальные данные не влезают в новый тип | Тестировать на копии рабочей базы, проверить данные до смены типа |
| Cron перестал запускаться | Висит незавершённое обновление | Завершить его через веб или CLI |
Права и данные внутри апгрейда
В upgrade.php часто нужно не только менять схему, но и обновлять данные. Здесь два замечания из практики. Первое: если шаг назначает новое право ролям функцией assign_capability(), сначала вызовите update_capabilities('local_hello'), иначе права ещё нет в базе и апгрейд падает. Второе: при чтении записей через get_records_sql() первый выбираемый столбец служит ключом массива. Если он не уникален, строки с одинаковым значением молча затираются друг другом. Для миграции данных это опасно, поэтому первым столбцом ставьте id или используйте get_recordset_sql(), который отдаёт строки по очереди и не требует уникальности.
Большие объёмы данных не обрабатывайте в одном шаге целиком: рекордсет читается порциями, обновления делаются построчно или пакетами, и вы не складываете всё в память. Если шаг может идти долго, учтите ограничение времени выполнения PHP при запуске из браузера. Для таких сайтов обновление безопаснее запускать из командной строки.
Какие операции есть у менеджера схемы
Добавлением поля набор не ограничивается. Менеджер $dbman умеет почти всё, что нужно при развитии таблицы, и каждая операция работает одинаково на всех СУБД:
| Задача | Метод | На что обратить внимание |
|---|---|---|
| Создать таблицу | create_table() | Перед вызовом проверять table_exists() |
| Удалить таблицу | drop_table() | Данные пропадут безвозвратно, нужна копия |
| Переименовать таблицу или поле | rename_table(), rename_field() | Не забыть обновить код, запросы и описание в install.xml |
| Добавить или удалить поле | add_field(), drop_field() | Перед удалением снять ключи и индексы, которые на него ссылаются |
| Сменить тип, точность, обязательность, значение по умолчанию | change_field_type(), change_field_precision(), change_field_notnull(), change_field_default() | Данные должны подходить под новый тип, иначе операция упадёт |
| Индексы | add_index(), drop_index(), index_exists() | На больших таблицах построение занимает время |
| Ключи | add_key(), drop_key() | Внешние ключи в Moodle служат описанием связи и не всегда создаются в СУБД как ограничения |
Для каждой операции в редакторе XMLDB есть генератор PHP-кода: вы описываете изменение в интерфейсе, а он выдаёт готовый фрагмент для вставки в upgrade.php. Я пользуюсь им, чтобы не ошибиться в параметрах конструктора xmldb_field, которые легко перепутать местами.
Чтение и запись данных: безопасный минимум
После схемы наступает очередь данных. Объект $DB предоставляет методы, которые сами подставляют префикс таблиц и экранируют значения. Строить SQL конкатенацией строк нельзя: пользовательский ввод в таком запросе превращается в инъекцию.
$id = $DB->insert_record('local_hello_note', $record);
$note = $DB->get_record('local_hello_note', ['id' => $id], '*', MUST_EXIST);
$DB->set_field('local_hello_note', 'status', 1, ['id' => $id]);
$DB->delete_records('local_hello_note', ['id' => $id]);
$sql = "SELECT n.id, n.notetext, u.firstname
FROM {local_hello_note} n
JOIN {user} u ON u.id = n.userid
WHERE n.status = :status";
$rows = $DB->get_records_sql($sql, ['status' => 1]);
Названия таблиц в SQL оборачивают в фигурные скобки, значения передают только через плейсхолдеры. Флаг MUST_EXIST заставляет метод бросить исключение, если записи нет, вместо тихого false. Для больших выборок используйте get_recordset(), он читает данные по строкам и не держит всё в памяти. Не забывайте закрывать рекордсет методом close(). Обратите внимание на первый столбец в get_records_sql(): он становится ключом массива, и при неуникальном значении записи затираются. Я выбираю id первым всегда.
Деинсталляция: убрать за собой
Таблицы, описанные в install.xml, при удалении плагина Moodle удаляет сам. Остальное придётся убирать вручную в файле db/uninstall.php: функция xmldb_local_hello_uninstall() удаляет данные, которые плагин положил в чужие таблицы или в файловое хранилище. Если плагин создавал строки в таблицах ядра, оставлять их нельзя. Проверка простая: поставьте и удалите плагин на тестовом сайте и сравните базу до и после.
Когда апгрейд упал посреди шага
Самая неприятная ситуация: на рабочем сайте шаг обновления выполнился наполовину. Поле добавилось, а индекс нет, savepoint не записан. Повторный запуск благодаря проверкам существования дойдёт до конца, но делать это нужно осознанно. Порядок такой: сначала прочитать сообщение об ошибке и понять, на какой строке всё остановилось; затем проверить в базе фактическое состояние таблицы; исправить причину (чаще всего это данные, не подходящие под новый тип); запустить обновление повторно. Сброс версии в базе вручную, чтобы «обмануть» систему, я не рекомендую: после него ядро и схема расходятся, и вы теряете возможность отследить, что уже применено.
Поэтому всегда держите под рукой копию базы, снятую непосредственно перед обновлением. Если восстановление из неё занимает минуты, любая ошибка шага перестаёт быть катастрофой.
Как обновлять рабочий сайт
- Сделайте резервную копию базы и каталога moodledata. Правила и частота описаны в материале про резервное копирование.
- Восстановите копию на тестовом сервере и прогоните обновление там, на реальных данных.
- Включите режим обслуживания на рабочем сайте.
- Выложите новый код, запустите
php admin/cli/upgrade.php --non-interactiveот пользователя веб-сервера. - Проверьте журнал, откройте страницы плагина, дождитесь запуска cron.
- Отключите режим обслуживания.
Если плагин обновляется на рабочей СДО, а вы не уверены в каждом шаге, на странице технической поддержки Moodle описано, как я беру такие работы под контроль. Следующая тема этой серии связана с правами, которыми часто управляют новые таблицы: access.php и capabilities.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.