Управление плагинами¶
В данном разделе приведены примеры команд для управления плагинами в Picodata с помощью команд языка SQL.
Общие сведения¶
Плагин — набор кода на языке Rust для добавления новой функциональности к Picodata. Плагин имеет собственный жизненный цикл, т.е. может быть независимо от остальных плагинов подключен, отключен, и использован вместе с другими плагинами.
Управлять плагинами может только Администратор СУБД. В свою очередь, плагины также работают с административными правами и имеют полный доступ к системе.
Запуск Picodata с поддержкой плагинов¶
Для использования плагинов запустите Picodata c параметром
picodata run --share-dir
В этой директории Picodata будет искать плагины. Требуется, чтобы структура директорий плагина соответствовали схеме:
корень share-dir
└── имя_плагина
└── версия_плагина
В качестве примера рассмотрим установку и использование тестового плагина weather_cache, который позволяет узнать температуру воздуха по заданным координатам. Плагин принимает на вход долготу и широту, проверяет погоду в указанных координатах с помощью публичного сервиса OpenWeather и возвращает температуру в градусах Цельсия. Данные кэшируются: при повторных запросах они будут прочитаны из Picodata.
Примечание
Здесь и далее приведен список шагов для создания плагина вручную. Эти операции можно также автоматизировать с помощью консольной утилиты Pike
Подготовка плагина¶
Исходный код плагина требуется сначала скомпилировать, для чего понадобятся Rust и Cargo 1.76 или новее. Используйте следующую команду:
make artifacts
Результат сборки появится в директории build. Перенесите файлы в
поддиректорию плагина так, чтобы получилась следующая структура:
└── weather_cache
└── 0.1.0
├── manifest.yaml
├── migrations
│ └── 0001_weather.db
└── weather_cache.so
Структура плагина¶
Манифест¶
Файл манифеста (manifest.yaml) содержит описание плагина, список его
сервисов и их конфигурации, а также список необходимых миграций.
Содержимое файла в тестовом плагине:
name: weather_cache
description: That one is created as an example of Picodata's plugin
version: 0.1.0
services:
- name: weather_service
description: This service provides HTTP route for a throughput weather cache
default_configuration:
openweather_timeout: 5
migration:
- migrations/0001_weather.db
Сервисы¶
Тестовый плагин содержит один сервис weather_service, для которого
установлена конфигурация по умолчанию (таймаут ожидания ответа от службы
OpenWeather).
Миграции¶
Миграция представляет собой набор SQL-команд, которые необходимы для
создания нужных плагину объектов (pico.UP) и их удаления
(pico.DOWN). Файлы миграций должны располагаться внутри поддиректории
с версией плагина (путь к каждому файлу миграции прописывается в
манифесте отдельно).
Содержимое файла 0001_weather.db тестового плагина
-- pico.UP
CREATE TABLE "weather" (
id UUID NOT NULL,
latitude INTEGER NOT NULL,
longitude INTEGER NOT NULL,
temperature INTEGER NOT NULL,
PRIMARY KEY (id)
)
USING memtx
DISTRIBUTED BY (latitude, longitude);
-- pico.DOWN
DROP TABLE "weather";
Добавление плагина¶
Добавление плагина означает его регистрацию в кластере. Подключитесь к консоли администратора инстанса Picodata, запущенного с поддержкой плагинов, и введите SQL-команду CREATE PLUGIN:
CREATE PLUGIN weather_cache 0.1.0;
После успешного добавления в системных таблицах появятся записи о новом плагине.
В таблице _pico_plugin со списком добавленных плагинов:
(admin) sql> SELECT * FROM _pico_plugin;
+-------------+---------+-------------+---------+-------------+------------+
| name | enabled | services | version | description | migration_ |
| | | | | | list |
+==========================================================================+
| "weather_ca | false | ["weather_s | "0.1.0" | "That one | ["migratio |
| che" | | ervice"] | | is created | ns/0001_we |
| | | | | as an | ather.db"] |
| | | | | example of | |
| | | | | Picodata's | |
| | | | | plugin" | |
+-------------+---------+-------------+---------+-------------+------------+
(1 rows)
В таблице _pico_plugin_config с конфигурацией сервисов плагина:
(admin) sql> SELECT * FROM _pico_plugin_config;
+-----------------+---------+-------------------+------------------+-------+
| plugin | version | entity | key | value |
+==========================================================================+
| "weather_cache" | "0.1.0" | "weather_service" | "openweather_tim | 5 |
| | | | eout" | |
+-----------------+---------+-------------------+------------------+-------+
(1 rows)
В таблице _pico_service со списком сервисов плагина (но пока без
привязки к тиру):
(admin) sql> SELECT * FROM _pico_service;
+-----------------+-------------------+---------+-------+------------------+
| plugin_name | name | version | tiers | description |
+==========================================================================+
| "weather_cache" | "weather_service" | "0.1.0" | [] | "This service |
| | | | | provides HTTP |
| | | | | route for a |
| | | | | throughput |
| | | | | weather cache" |
+-----------------+-------------------+---------+-------+------------------+
(1 rows)
Примечание
В кластере может быть не более двух версий одного и того же плагина. Чтобы добавить новую версию, может понадобиться удалить одну из старых.
Запуск миграции плагина¶
Процесс миграции означает создание или изменение необходимой для плагина
схемы данных. На данном этапе таблица weather, указанная в файле
0001_weather.db еще не создана, т.к. миграции не были запущены. Для их
запуска введите следующую команду ALTER
PLUGIN:
ALTER PLUGIN weather_cache MIGRATE TO 0.1.0;
Успешная миграция означает, что в БД появилась новая таблица weather:
(admin) sql> SELECT * FROM weather;
+----+----------+-----------+-------------+
| id | latitude | longitude | temperature |
+=========================================+
+----+----------+-----------+-------------+
(0 rows)
Данные плагина в системных таблицах и таблицах, созданных в результате
миграции pico.UP, персистентны и сохраняются между циклами
включения/отключения плагина.
Включение сервисов плагина¶
Основная функциональность плагина реализуется через его сервисы, которые
должны быть включены в явном виде. Сервисы работают с привязкой
к тирам: если конфигурация тиров в кластере не была явно задана,
то в примере с тестовым плагином укажите тир по умолчанию default в
команде ALTER PLUGIN:
ALTER PLUGIN weather_cache 0.1.0 ADD SERVICE weather_service TO TIER default;
После успешного включения плагина в системной таблице _pico_service
появится привязка сервиса к указанному тиру:
(admin) sql> SELECT * FROM _pico_service;
+----------------+----------------+---------+-------------+----------------+
| plugin_name | name | version | tiers | description |
+==========================================================================+
| "weather_cache | "weather_servi | "0.1.0" | ["default"] | "This service |
| " | ce" | | | provides HTTP |
| | | | | route for a |
| | | | | throughput |
| | | | | weather cache" |
+----------------+----------------+---------+-------------+----------------+
(1 rows)
Включение и отключение плагина¶
Включите плагин следующей командой:
ALTER PLUGIN weather_cache 0.1.0 ENABLE;
После успешного включения в колонке enabled в системной таблице
_pico_plugin установится значение true:
(admin) sql> SELECT * FROM _pico_plugin;
+-------------+---------+-------------+---------+-------------+------------+
| name | enabled | services | version | description | migration_ |
| | | | | | list |
+==========================================================================+
| "weather_ca | true | ["weather_s | "0.1.0" | "That one | ["migratio |
| che" | | ervice"] | | is created | ns/0001_we |
| | | | | as an | ather.db"] |
| | | | | example of | |
| | | | | Picodata's | |
| | | | | plugin" | |
+-------------+---------+-------------+---------+-------------+------------+
(1 rows)
Примечание
Нельзя включить больше одной версии плагина в кластере
Для отключения плагина используйте следующую команду:
ALTER PLUGIN weather_cache 0.1.0 DISABLE;
Конфигурация плагина¶
Конфигурация плагина хранится в манифесте и предполагает настройку входящих в него сервисов. Например, для изменения таймаута для вызова OpenMeteo в тестовом плагине введите следующую команду ALTER PLUGIN:
ALTER PLUGIN weather_cache 0.1.0 SET weather_service.openweather_timeout='7';
См. также:
Проверка работы плагина¶
Запустите отдельное окно терминала и введите следующую команду для проверки работы тестового плагина:
curl "localhost:8081/api/v1/weather?longitude=55&latitude=66"
Удаление плагина¶
Перед удалением плагина его необходимо отключить.
Введите команду DROP PLUGIN для удаления плагина:
DROP PLUGIN weather_cache 0.1.0;
При удалении плагина с помощью указанной выше команды его схема данных
(записи в системных таблицах), а также таблицы, созданные ранее
миграцией pico.UP, остаются в кластере. Для очистки этих данных
следует при удалении плагина использовать параметр WITH DATA,
например:
DROP PLUGIN weather_cache 0.1.0 WITH DATA;
В таком случае будут запущена миграция pico.DOWN, а также удалены записи
плагина и его сервисов из системных таблиц.
См. также: