Атрибуты новых таблиц/полей/индексов, определённые движком

В MariaDB движок хранилища может позволить пользователю указывать дополнительные атрибуты для каждого индекса, поля или таблицы. Движок должен объявить, какие атрибуты он вводит.

API

В структуре handlerton есть три новых члена, их можно установить в функции инициализации движка следующим образом:

example_hton->table_options= example_table_option_array;
example_hton->field_options= example_field_option_array;
example_hton->index_options= example_index_option_array;

Массивы объявляются статически, как в следующем примере:

static MYSQL_THDVAR_ULONG(varopt_default, PLUGIN_VAR_RQCMDARG,
  "default value of the VAROPT table option", NULL, NULL, 5, 0, 100, 0);

struct ha_table_option_struct
{
  char *strparam;
  ulonglong ullparam;
  uint enumparam;
  bool boolparam;
  ulonglong varparam;
};

ha_create_table_option example_table_option_list[]=
{
  HA_TOPTION_NUMBER("NUMBER", ullparam, UINT_MAX32, 0, UINT_MAX32, 10),
  HA_TOPTION_STRING("STR", strparam),
  HA_TOPTION_ENUM("ONE_OR_TWO", enumparam, "one,two", 0),
  HA_TOPTION_BOOL("YESNO", boolparam, 1),
  HA_TOPTION_SYSVAR("VAROPT", varopt, varparam),
  HA_TOPTION_END
};

Движок объявляет структуру ha_table_option_struct , которая будет хранить значения этих новых атрибутов.

И он описывает эти атрибуты для MySQL, создавая массив макросов HA_TOPTION_* . Обратите внимание на деталь: эти макросы ожидают структуру, называемую ha_table_option_struct , если структура называется по-другому, потребуется #define .

Поддерживаются пять типов атрибутов:

Не используйте enum для членов вашей структуры HA_TOPTION_ENUM C, размер enum зависит от компилятора и даже от опций компиляции, а API плагина использует только типы с известными размерами хранения.

Во всех макросах два первых параметра — имя атрибута, которое должно использоваться в SQL в операторе CREATE TABLE, и имя соответствующего члена структуры ha_table_option_struct.

HA_TOPTION_SYSVAR несколько отличается. Он не определяет тип атрибута или значение по умолчанию, а вместо этого связывает атрибут с системной переменной. Тип атрибута и диапазон допустимых значений будут такими же, как и у соответствующей системной переменной. Значение по умолчанию атрибута будет текущим значением его системной переменной. В отличие от других типов атрибутов, которые хранятся только в файле .frm только если они явно заданы в операторе CREATE TABLE, атрибуты HA_TOPTION_SYSVAR всегда хранятся. Изменение значения системной переменной не повлияет на существующие таблицы. Обратите внимание, что по этой причине, если таблица была создана в старой версии движка хранилища, а новая версия ввела атрибут HA_TOPTION_SYSVAR, значение атрибута в старых таблицах будет значением по умолчанию системной переменной, а не её текущим значением.

Массив завершается макросом HA_TOPTION_END.

Поля и атрибуты индексов (ключей) объявляются аналогично с использованием макросов HA_FOPTION_* и HA_IOPTION_*.

При выполнении оператора CREATE TABLE, вызывается метод обработчика ::create(), атрибуты таблицы доступны в table_arg->s->option_struct, атрибуты полей — в члене option_struct отдельных полей (объектов класса Field), атрибуты индексов — в члене option_struct отдельных ключей (объектов класса KEY).

Кроме того, они доступны в большинстве других методов обработчика: атрибуты хранятся в файле .frm и при каждом открытии MySQL предоставляются движку путем заполнения соответствующих членов option_struct таблицы, полей и ключей.

ALTER TABLE нуждается в специальной поддержке от движка. MySQL сравнивает старые и новые определения таблиц, чтобы решить, нужно ли перестраивать таблицу. Так как семантика объявленных движком атрибутов неизвестна, MySQL не может принять это решение, проанализировав значения атрибутов — это делегируется движку. Структура HA_CREATE_INFO имеет три новых члена:

ha_table_option_struct *option_struct;           ///< structure with parsed table options
ha_field_option_struct **fields_option_struct;   ///< array of field option structures
ha_index_option_struct **indexes_option_struct;  ///< array of index option structures

Движок (в методе ::check_if_incompatible_data()) отвечает за сравнение новых значений атрибутов из структуры HA_CREATE_INFO со старыми значениями из таблицы и возвращает COMPATIBLE_DATA_NO если они были изменены таким образом, что требует перестройки таблицы.

Пример объявления атрибутов и сравнения значений для ALTER TABLE можно найти в движке EXAMPLE.

SQL

Атрибуты, объявленные движком, могут быть указаны для поля, индекса или таблицы в операторе CREATE TABLE или ALTER TABLE . Синтаксис стандартный:

CREATE TABLE ... (
  field ... [attribute=value [attribute=value ...]],
  ...
  index ... [attribute=value [attribute=value ...]],
  ...
) ...  [attribute=value [attribute=value ...]]

Все значения должны быть указаны как литералы, а не выражения. Значение булевого параметра можно указать как одно из YES, NO, ON, OFF, 1 или 0. Значение строки можно указать в кавычках или без них, как идентификатор (если это допустимый идентификатор, конечно). Сравните со старым поведением:

CREATE TABLE ... ENGINE=FEDERATED CONNECTION='mysql://root@127.0.0.1';

где значение атрибута ENGINE указано без кавычек, а значение CONNECTION — в кавычках.

Когда атрибут задан, он будет сохранён вместе с определением таблицы и отображён в SHOW CREATE TABLE; . Чтобы удалить атрибут из определения таблицы, используйте ALTER TABLE для установки его значения в DEFAULT .

Значения неизвестных атрибутов или атрибутов с недопустимыми значениями по умолчанию вызывают ошибку. Но с помощью ALTER TABLE можно изменить движок хранилища, и некоторые ранее допустимые атрибуты могут стать неизвестными для нового движка. Тем не менее, они не удаляются автоматически, так как таблица может быть изменена обратно на первый движок, и эти атрибуты снова будут допустимыми. Однако, SHOW CREATE TABLE будет комментировать эти неизвестные атрибуты в выводе, в противном случае они сделают недействительным генерируемый оператор CREATE TABLE.

С режимом IGNORE_BAD_TABLE_OPTIONS sql mode это поведение меняется. Неизвестные атрибуты не вызывают ошибку, а только приводят к предупреждению. И SHOW CREATE TABLE не будет комментировать их. Этот режим неявно включен в потоке репликации сервера.

См. также

• Создание плагинов для MariaDB
• Движки хранилища
• Разработка движков хранилища