Cargo plugin for Picodata plugins

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

Установка

cargo install picodata-pike

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

Pike расчитан на работу с версией 25.1.1. Версия 24.6.1 признана устаревшей и поддерживается только в команде cargo pike run.

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 появиться желанный архив.

Команды

--help

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

cargo pike --help

run

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

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

[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 - Путь до директории плагина. Значение по умолчанию: ./

topology.toml

# описание количества репликасетов и фактора репликации тира
# фактор репликации отвечает за количество инстансов в одном репликасете
# в примере используется тир 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 }}"

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

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

picodata.yaml

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

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

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

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

# picodata.yaml

cluster:
  tier:
    default:
      can_vote: true
    compute: # новый тир
      can_vote: true

# topology.toml

# ...

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

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

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

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

plugin clean

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

cargo pike clean

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

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

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

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

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

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

plugin pack

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

cargo pike plugin pack

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

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

По умолчанию архив будет содержать .so файл скомпилированного плагина, 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 будет скопирован файл topology.toml, лежащий в корне плагина.

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

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

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