Cargo plugin for Picodata plugins

Плагин к cargo с функциями для упрощения разработки плагинов к Пикодате.

Установка

cargo install picodata-pike

Поддерживаемые версии

Pike	Picodata
`1..`	`> 24.6, < 25.1`
`2..`	`>= 25.1, < 26`
`3..`	`>= 25.4, < 26`

Quickstart

Начнем работу с новым плагином:

cargo pike plugin new test_plugin

cd test_plugin

Запустим кластер, конфигурацию которого можно задать в ./topology.toml

cargo pike run

В вашем распоряжении окажется рабочий кластер с установленным плагином. Остановим кластер комбинацией Ctrl+C или же командой cargo pike stop в отдельном окне.

Если вам нужно собрать архив для поставки на сервера, это можно сделать командой:

cargo pike plugin pack

В папке target появиться желанный архив.

В шаблоне нового плагина автоматически создаётся smoke-тест, который проверяет жизненный цикл плагина (установка, миграции, включение, выключение, удаление).
Для запуска smoke-теста используйте:

cargo test

Команды

`--help`

Для всех команд есть флаг --help выводящий справку по использованию.

cargo pike --help

`run`

Запуск кластера пикодаты по файлу topology.toml. Автоматически запускает плагины указанные в топологии.

Пример топологии:

pre_install_sql = [
    'ALTER SYSTEM SET raft_wal_count_max = 10000;'
]

[tier.default]
replicasets = 2
replication_factor = 2

[plugin.super_plugin]
migration_context = [
    { name = "example_name", value = "example_value" },
]

[plugin.super_plugin.service.main]
tiers = ["default"]

cargo pike run --topology topology.toml --data-dir ./tmp

Для отключения автоматической установки и включения плагинов можно использовать опцию --disable-install-plugins.

Доступные опции

-t, --topology <TOPOLOGY> - Путь к файлу топологии. Значение по умолчанию: topology.toml
--data-dir <DATA_DIR> - Путь к директории хранения файлов кластера. Значение по умолчанию: ./tmp
--disable-install-plugins - Отключение автоматической установки плагинов
--base-http-port <BASE_HTTP_PORT> - Базовый http-порт, с которого начнут открываться http-порты отдельных инстансов. Значение по умолчанию: 8000
--base-pg-port <BASE_PG_PORT> - Базовый порт постгрес протокола, с которого начнут открываться порты отдельных инстансов. Значение по умолчанию: 5432
--picodata-path <BINARY_PATH> - Путь до исполняемого файла Пикодаты. Значение по умолчанию: picodata
--release - Сборка и запуск релизной версии плагина
--target-dir <TARGET_DIR> - Директория собранных бинарных файлов. Значение по умолчанию: target
-d, --daemon - Запуск кластера в режиме демона
--disable-colors - Отключает раскрашивание имён инстансов в разные цвета в логах
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./
--no-build - Отменить сборку плагина перед стартом кластера. Значение по умолчанию: false
--config-path - Путь к файлу конфигурации. Значение по умолчанию: ./picodata.yaml
--instance-name - Название инстанса, которого хотим запустить, если параметр не указан - запускается весь кластер
--with-web-auth - Оставить включённой аутентификацию WebUI. По умолчанию Pike отключает WebUI auth для локальной разработки запросом ALTER SYSTEM SET jwt_secret = ''
--with-audit - Включить логи аудита. По умолчанию, они отключены. Если параметр указан - каждый инстанс кластера хранит собственный лог аудита под именем audit.log в своей директории.

Также, можно задать iproto, http и pg порты через enviroment в topology.toml, они соответсвуют названиям переменных в picodata run --help. В enviroment выставляются значения вида <host>:<port>, работать будут только 127.0.0.1 и 0.0.0.0, т. к. пайк предназначен для локальной разработки

topology.toml

# SQL-скрипты, которые будут выполнены перед установкой плагинов.
# Полезно для установки глобальных настроек кластера, создания пользователей или таблиц.
# Рекомендуется использовать тройные кавычки ('''), чтобы не экранировать кавычки внутри SQL.
pre_install_sql = [
    'ALTER SYSTEM SET raft_wal_count_max = 10000;',
    '''CREATE USER "my_user" WITH PASSWORD 'secret';''',
    '''CREATE TABLE "init_table" ("id" INT PRIMARY KEY, "val" TEXT) DISTRIBUTED GLOBALLY;'''
]

# описание количества репликасетов и фактора репликации тира
# фактор репликации отвечает за количество инстансов в одном репликасете
# в примере используется тир default, указано два репликасета и фактор репликации 2,
# следовательно будет создано всего четыре инстанса
[tier.default]
replicasets = 2
replication_factor = 2

# настройки плагинов
[plugin.sp] # в примере настройки для плагина sp
# переменные которые будут подставлены в миграции
# подробнее тут: https://docs.picodata.io/picodata/24.6/architecture/plugins/#use_plugin_config
migration_context = [
    { name = "example_name", value = "example_value" },
]

# настройки сервисов плагинов
[plugin.sp.service.main] # в примере настройка сервиса main плагина sp
tiers = ["default"] # тиры на которых должен работать сервис

# переменные окружения, которые будут переданы каждому инстансу Picodata
# в значении переменной можно указать liquid-шаблон, # в таком случае
# переменная будет динамически вычислена для каждого инстанса отдельно
# подробнее про liquid-шаблоны: https://shopify.dev/docs/api/liquid
[enviroment]
SP_CONST_VAR = "const" # такое значение будет передано каждому инстансу без изменений
# здесь мы используем переменную из контекста шаблонов,
# для первого, например, инстанса значение будет "1"
SP_LIQUID_VAR = "{{ instance_id }}"
# а здесь используется переменная из контекста и стандартная функция plus
# результатом для первого, например, инстанса будет "4243"
SP_LIQUID_VAR2 = "{{ instance_id | plus: 4242 }}"
# выставляем http адрес инстанса пикодаты
PICODATA_HTTP_LISTEN = "127.0.0.1:{{ 8000 | plus: instance_id }}"

Доступные переменные контекста в шаблонах:

instance_id - порядковый номер инстанса при запуске, начинается с 1

picodata.yaml

Пайк позволяет использовать файл конфигурации Пикодаты вместе с запущенным кластером. Пример файла сразу генерируется командами new и init. Документацию к параметрам можно найти в документации к Пикодате.

Настройка нескольких тиров

Для настройки необходимо указать нужные тиры в файле топологии topology.toml.

Пример добавления тира compute:

# topology.toml

# ...

[tier.compute] # новый тир
replicasets = 1
replication_factor = 1

Подключение внешних плагинов

Для добавления дополнительных плагинов, не входящих в текущий проект, в топологии можно указать свойство path для плагина.

Поддерживаются две формы пути: относительный и абсолютный.

[plugin.ext_plugin]
path = "../ext_plugin"                # относительная директория проекта

[plugin.third_party_plugin]
path = "/opt/bundles/third_plugin_0.3.1-ubuntu_focal.tar.gz"  # абсолютный путь к архиву

[plugin.home_plugin]
path = "~/Downloads/my_plugin_0.2.0-arch_rolling.tar.gz"      # путь из $HOME

Путь может вести на:

Директорию с проектом плагина (поддерживаются и cargo project и cargo workspace)
Директорию с собранными версиями плагина, которая получается в результате выполнения pike plugin build
Архив с плагином, созданный через pike plugin pack или вручную.

Файлы внешних плагинов автоматически помещаются в рабочую директорию запуска кластера: <data_dir>/cluster/plugins. Эта директория затем передаётся picodata через --plugin-dir, поэтому нет необходимости иметь «родительский» плагин. Достаточно:

положить topology.toml и (опционально) picodata.yaml в пустую папку
указать path на архив/директорию внешнего плагина
запустить cargo pike run

Пример запуска внешнего плагина

Предварительно подготавливаем плагин:

mkdir -p "/tmp/pike-manual-test"
cd "/tmp/pike-manual-test"
cargo pike plugin new my-plugin
cd my-plugin
cargo pike plugin pack

Путь, полученный в результате работы pike plugin pack нужно будет указать в topology.toml path.

Создаем папку my-run в домашней директории со следующим содержимым:

my-run/
├── topology.toml
└── picodata.yaml   (опционально)

topology.toml:

[tier.default]
replicasets = 1
replication_factor = 3

[plugin.my-plugin]
path = "/tmp/pike-manual-test/my-plugin/./target/release/my-plugin_0.1.0-cachyos_rolling.tar.gz"
migration_context = []

[plugin.my-plugin.service.example_service]
tiers = ["default"]

picodata.yaml:

cluster:
  name: my-plugin_0.1.0-arch_rolling
  default_bucket_count: 16384
instance:
  memtx:
    memory: 2000000000

Запуск:

cargo pike run

`stop`

Остановить кластер можно либо комбинацией клавиш Ctrl+C в терминале, где вызывалась команда cargo pike run, либо в другом окне командой:

cargo pike stop --data-dir ./tmp

При помощи --data-dir указывается путь до директории с файлами кластера (значение по умолчанию: ./tmp)

Вывод:

[*] stopping picodata cluster, data folder: ./tmp
[*] stopping picodata instance: i1
[*] stopping picodata instance: i2
[*] stopping picodata instance: i3
[*] stopping picodata instance: i4

Для того, чтобы остановить только один инстанс в кластере, необходимо передать его название в опцию --instance-name. Пайк остановит только указанный инстанс, а остальные продолжат свое выполнение.

Например,

cargo pike stop --data-dir ./tmp --instance-name i2

Вывод:

[*] stopping picodata cluster instance 'i2', data folder: ./tmp/i2
[*] stopping picodata instance: i2 - OK

Доступные опции

--data-dir <DATA_DIR> - Путь к директории хранения файлов кластера. Значение по умолчанию: ./tmp
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./
--instance-name <INSTANCE_NAME> - Название инстанса Пикодаты. По умолчанию игнорируется.

`enter`

Подключения к определенному инстансу Пикодаты по его имени

cargo pike enter default_2_1

Доступные опции

--data-dir <DATA_DIR> - Путь к директории хранения файлов кластера. Значение по умолчанию: ./tmp
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./
--picodata-path <BINARY_PATH> - Путь до исполняемого файла Пикодаты. Значение по умолчанию: picodata

`plugin clean`

Очистка дата-каталогов пикодаты.

cargo pike clean

Доступные опции

--data-dir <DATA_DIR> - Путь к директории хранения файлов кластера. Значение по умолчанию: ./tmp
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./

`plugin new`

Создание нового проекта плагина из шаблона.

cargo pike plugin new name_of_new_plugin

Автоматически инициализирует в проект git. Для отключения этого поведения можно воспользоваться флагом --without-git.

Доступные опции

--without-git - Отключение автоматической инициализации git-репозитория
--workspace - Создание проекта плагина как воркспейса

`plugin add`

Добавление плагина в workspace. Работает только внутри директории плагина, инициализированного с флагом --workspace

cargo pike plugin add name_of_new_plugin

Доступные опции

--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./

`plugin init`

Создание нового проекта плагина из шаблона в текущей папке.

cargo pike plugin init

Доступные опции

--without-git - Отключение автоматической инициализации git-репозитория
--workspace - Создание проекта плагина как воркспейса

`plugin pack`

Сборка всех нужных для поставки плагина файлов в один архив (для деплоя или поставки).

cargo pike plugin pack

Команда plugin pack соберёт релизную версию плагина в новый архив в директории target проекта.

Имя архива

По умолчанию, если не указана опция --archive-name, имя архива включает идентификатор ОС и её вариант:

<plugin_name>_<version>-<os_id>_<variant>.tar.gz

Примеры:

weather-cache_0.1.1-ubuntu_focal.tar.gz
weather-cache_0.1.1-centos_el8.tar.gz
weather-cache_0.1.1-altlinux_p9.tar.gz

Для rolling-дистрибутивов (например, arch, gentoo, void) в качестве варианта используется rolling. Если конкретный вариант не может быть определён, указываются безопасные значения по умолчанию.

Настройка содержания архива

По умолчанию архив будет содержать .so/.dylib файл скомпилированного плагина, manifest.yaml, папку с миграциями, а также содержимое папки assets.

Папка assets нужна чтобы положить сторонние артефакты. Артефакты можно положить либо вручную, либо передать путь до них скрипту сборки build.rs как:

use pike::helpers::build;

fn main() {
    let params = build::ParamsBuilder::default()
        .custom_assets(vec!["./picodata.yaml"])
        .build()
        .unwrap();

    build::main(&params);
}

В данном примере в папку assets будет скопирован файл picodata.yaml, лежащий в корне плагина.

Доступные опции

--debug - Сборка и упаковка debug-версии плагина
--target-dir <TARGET_DIR> - Директория собранных бинарных файлов. Значение по умолчанию: target
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./
--no-build - Пропустить сборку (cargo build) перед упаковкой. Требует, чтобы директория сборки уже существовала и имела корректную структуру (наличие manifest.yaml и lib<имя_пакета>.{so|dylib}). При отсутствии этих артефактов команда завершится с ошибкой с предложением предварительно собрать плагин или убрать --no-build. Значение по умолчанию: false
--archive-name <ARCHIVE_NAME> - Явно заданное имя/путь архива. Если путь относительный — архив будет создан в <target>/<debug|release>/<ARCHIVE_NAME>. Если имя/путь не оканчивается на .tar.gz, расширение будет автоматически добавлено

`plugin build`

Альяс для команды cargo build.

cargo pike plugin build

Доступные опции

--release - Сборка release-версии плагина
--target-dir <TARGET_DIR> - Директория собранных бинарных файлов. Значение по умолчанию: target
--plugin-path - Путь до директории проекта плагина. Значение по умолчанию: ./

`config apply`

Применение конфигурации сервисов плагина к запущенному командой run кластеру пикодаты.

Пример файла конфигурации сервисов:

# plugin_config.yaml

main: # имя сервиса
  value: changed # пример параметра конфигурации

cargo pike config apply

Доступные опции

-c, --config-path <CONFIG> - Путь к файлу конфига. Значение по умолчанию: plugin_config.yaml
--data-dir <DATA_DIR> - Путь к директории хранения файлов кластера. Значение по умолчанию: ./tmp
--picodata-path <BINARY_PATH> - Путь к бинарному файлу Picodata, который будет использоваться для вызова picodata admin при применении конфига. По умолчанию используется picodata из $PATH

picodata-pike 3.1.0

Cargo plugin for Picodata plugins

Установка

Поддерживаемые версии

Quickstart

Команды

--help

run

Доступные опции

topology.toml

picodata.yaml

Настройка нескольких тиров

Подключение внешних плагинов

Пример запуска внешнего плагина

stop

Доступные опции

enter

Доступные опции

plugin clean

Доступные опции

plugin new

Доступные опции

plugin add

Доступные опции

plugin init

Доступные опции

plugin pack

Имя архива

Настройка содержания архива

Доступные опции

plugin build

Доступные опции

config apply

Доступные опции

`--help`

`run`

`stop`

`enter`

`plugin clean`

`plugin new`

`plugin add`

`plugin init`

`plugin pack`

`plugin build`

`config apply`