Структура драйвера БД

Пакет описывает движок в engine.json и экспортирует адаптер из ESM-модуля. Тот же контракт используется для встроенных и устанавливаемых движков.

Файлы и манифест

example-db/
  engine.json
  entry.mjs
  src/

Пример манифеста собственного драйвера:

{
  "id": "example-db",
  "label": "Пример СУБД",
  "kind": "db-engine",
  "api": 1,
  "minimum": "0.0.0",
  "entry": "entry.mjs"
}

Поле	Назначение
id	Уникальный идентификатор: 1–41 строчная латинская буква, цифра, дефис или подчёркивание; первый символ — буква или цифра.
label	Название движка в интерфейсе.
kind, api	Тип db-engine и версия контракта 1.
minimum	Минимальная стабильная версия GrigDesk X.Y.Z; укажите фактически проверенный минимум вместо примера.
entry	Относительный путь к обычному .mjs внутри пакета, без ссылок и node_modules.

Версия пакета берётся из стабильного Git-тега vX.Y.Z. Необязательное поле version в манифесте должно совпадать с ним. Внешний id не может заменять встроенный mysql или clickhouse. Имена constructor, prototype и __proto__ зарезервированы.

Если нужны npm-зависимости, приложите package.json и lock-файл. Установщик применяет общую политику зависимостей: lock v2/v3, без Git/file/link/URL-зависимостей и установочных скриптов.

Контракт адаптера

Default export точки входа — объект с id, label, JSON-совместимыми capabilities и всеми восемью методами:

Метод	Что делает
open({ profile, password, stream, openStream })	Открывает подключение и возвращает его handle; пароль приходит как Buffer.
close(handle)	Завершает подключение.
schema(handle)	Возвращает схему базы.
analyze(text, handle)	Определяет класс запроса и используемые таблицы.
inspectRights(handle, session)	Проверяет права подключения.
estimate(handle, request, settings)	Оценивает запрос.
execute(handle, request)	Выполняет запрос с предусмотренными ограничениями.
cancel(handle, run)	Отменяет выполнение.

Точные формы результатов сверяйте с адаптерами установленной версии: server/src/lib/db/engines/ и реестром server/src/lib/db/engineRegistry.ts. Названия методов сами по себе не гарантируют правильный анализ запросов, проверку прав или отмену — это нужно проверить при разработке.

Хранение и загрузка

Установленные пакеты лежат в db-engines/<id>/ папки данных; GRIGDESK_DB_ENGINES_DIR переопределяет каталог. Манифест проверяется при подготовке, а экспорт и методы — при загрузке на старте сервера. Для активации нужен ручной перезапуск.

Далее: создать драйвер · установить пакет.