Управление плагинами¶
В данном разделе приведены примеры команд для управления плагинами в Picodata с помощью команд языка SQL.
Общие сведения¶
Плагин — набор кода на языке Rust для добавления новой функциональности к Picodata. Плагин имеет собственный жизненный цикл, т.е. может быть независимо от остальных плагинов подключен, отключен, и использован вместе с другими плагинами.
Управлять плагинами может только Администратор СУБД. В свою очередь, плагины также работают с административными правами и имеют полный доступ к системе.
Запуск Picodata с поддержкой плагинов¶
Для использования плагинов запустите Picodata c параметром picodata run --plugin-dir
В этой директории Picodata будет искать плагины. Требуется, чтобы структура директорий плагина соответствовали схеме:
корень plugin-dir
└── имя_плагина
└── версия_плагина
В качестве примера рассмотрим установку и использование тестового плагина weather_cache, который позволяет узнать температуру воздуха по заданным координатам. Плагин принимает на вход долготу и широту, проверяет погоду в указанных координатах с помощью публичного сервиса OpenWeather и возвращает температуру в градусах Цельсия. Данные кэшируются: при повторных запросах они будут прочитаны из Picodata.
Подготовка плагина¶
Исходный код плагина требуется сначала скомпилировать, для чего понадобятся 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 NUMBER NOT NULL,
longitude NUMBER NOT NULL,
temperature NUMBER 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 со списком добавленных плагинов:
picodata> 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 с конфигурацией сервисов плагина:
picodata> 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 со списком сервисов плагина (но пока без привязки к тиру):
picodata> 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:
picodata> 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 появится привязка сервиса к указанному тиру:
picodata> 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:
picodata> 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, а также удалены записи
плагина и его сервисов из системных таблиц.