Перейти к содержимому
M
Все статьи
Разработка 10 мин чтения

База данных плагина Moodle: install.xml, upgrade.php и как не сломать апгрейд

XMLDB в Moodle: как описать таблицы в install.xml, писать upgrade.php и savepoint, и почему апгрейд плагина падает. Разбор ошибок с таблицей «симптом — причина».

XMLDB в Moodle: как описать таблицы в install.xml, писать upgrade.php и savepoint, и почему апгрейд плагина падает. Разбор ошибок с таблицей «симптом — причина».

Таблицы плагина описываются в 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 не записан. Повторный запуск благодаря проверкам существования дойдёт до конца, но делать это нужно осознанно. Порядок такой: сначала прочитать сообщение об ошибке и понять, на какой строке всё остановилось; затем проверить в базе фактическое состояние таблицы; исправить причину (чаще всего это данные, не подходящие под новый тип); запустить обновление повторно. Сброс версии в базе вручную, чтобы «обмануть» систему, я не рекомендую: после него ядро и схема расходятся, и вы теряете возможность отследить, что уже применено.

Поэтому всегда держите под рукой копию базы, снятую непосредственно перед обновлением. Если восстановление из неё занимает минуты, любая ошибка шага перестаёт быть катастрофой.

Как обновлять рабочий сайт

  1. Сделайте резервную копию базы и каталога moodledata. Правила и частота описаны в материале про резервное копирование.
  2. Восстановите копию на тестовом сервере и прогоните обновление там, на реальных данных.
  3. Включите режим обслуживания на рабочем сайте.
  4. Выложите новый код, запустите php admin/cli/upgrade.php --non-interactive от пользователя веб-сервера.
  5. Проверьте журнал, откройте страницы плагина, дождитесь запуска cron.
  6. Отключите режим обслуживания.

Если плагин обновляется на рабочей СДО, а вы не уверены в каждом шаге, на странице технической поддержки Moodle описано, как я беру такие работы под контроль. Следующая тема этой серии связана с правами, которыми часто управляют новые таблицы: access.php и capabilities.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.