3. Описание MCP-сервера › 3.3 Движок › База данных › engine_db_execute

Меняет данные пулом шагов: любые запросы, вставки, узлы деревьев, уборку и отметки для кеша витрины. Читающие шаги select и dependent здесь тоже работают.

Право

«Прямой доступ → База данных → Изменение данных» (AGENT_ENGINE_DB_EXECUTE).

Параметры

Параметр	Тип	Что это
[`pool`]	список объектов	шаги пула — см. «База данных»
[`pool_source`]	строка	файл JSON на этом компьютере со списком шагов — абсолютный путь или путь от папки магазина — вместо `pool`

Нужен pool или pool_source, но не оба.

Шаги

Шаг	Поля	Что делает	Ответ шага
`lock`	`tables`	берёт таблицы в работу — все сразу или ни одной	`tables`
`unlock`	`tables`; без них — всё, что взял пул	отпускает взятое этим пулом раньше конца	`tables`
`generate`	`table`	следующий id из генератора таблицы	`value`
`select`	как у `engine_db_select`, без проверки на чтение	строки запроса	`rows`, `data`
`modify`	`sql`, `params`	любой запрос: `UPDATE`, `DELETE`, DDL	`affected`, `insert_id`
`insert`	`table`, `rows`	вставляет строки одним многострочным `INSERT`	`affected`, `insert_id`
`tree_add`	`table`, `parent_id`	добавляет узел дерева	`value` — id узла
`tree_move`	`table`, `id`, `parent_id`	переносит узел с поддеревом под другого родителя	—
`tree_up`, `tree_down`	`table`, `id`	сдвигает узел среди соседей	—
`tree_remove`	`table`, `id`	удаляет узел вместе с поддеревом	`deleted` — сколько строк
`dependent`	`table`, `ids`	как у `engine_db_select`	`depend`, `count`
`clear_dependent`	`table`	убирает строки зависимых таблиц, оставшиеся без владельца	`cleared`
`change`	`tables`	отмечает таблицы изменёнными	`tables`

У любого шага может быть name: тогда его value или insert_id одалживается следующим шагам как @имя.

generate берёт id из генератора. Генератор есть у таблиц, у которых engine_db_tables показывает gen; у остальных id выдаёт сама СУБД через AUTO_INCREMENT, и шаг для них отказывает. Бывает генератор и без таблицы: store_clann выдаёт номер клана товара для поля clann таблицы store.

insert принимает rows — список строк, каждая объектом с одинаковыми колонками. Один INSERT вмещает не больше 65 535 значений — строк, умноженных на колонки; больше — несколькими шагами insert.

id и parent_id шагов дерева — целое число или @имя. Слово отказывает, а не читается как ноль: ноль — это верх дерева.

Деревья

Деревом считается любая таблица с полями tindex, tlevel и absindex: каталог topic, справочники info, альтернативные каталоги topic_alt, характеристики *_key и другие.

Форму дерева меняют только шаги tree_*. Они пересчитывают эти три поля по всей таблице, и обычные INSERT, UPDATE и DELETE этого не повторят.
Служебные деревья закрыты: oper, orders_client_field и личные таблицы пользователей u_*.
tree_add создаёт пустую строку — только id и место в дереве. Поля заполняет следующий modify по одолженному id.
Новый узел topic или info видит только администратор, пока у узла нет строк в topic_right или info_right.
Корень каталога — id = 1. parent_id = 0 ставит узел на верхний уровень; так создаётся первый узел пустого справочника info.
Шаг дерева сам отмечает свою таблицу для кеша.

Уборка

clear_dependent убирает строки зависимых таблиц, которые остались без владельца, и идёт дальше по цепочке: вслед за info чистятся хвосты info_value. Ответ cleared называет по таблице, сколько строк снято; занятую таблицу шаг пропускает и пишет у неё busy.

Строка с пустым ключом, если поле может быть пустым, ни на кого не указывает по замыслу, и уборка её не трогает.
Таблицы людей user и user_group уборке закрыты.
Пока пул держит таблицы, уборка отказывает: взятые им таблицы тоже заняты. Её ставят после unlock или запускают отдельным пулом.
Уборка сама отмечает таблицы, которые почистила.

Отметки для кеша

Витрина узнаёт об изменении таблицы по отметке. Шаг change отмечает названные таблицы; шаги дерева и уборка отмечают свои сами. Отметки ставятся один раз в конце пула — тысяча вставок стоит одной отметки. Таблица, изменённая запросом без change, не отмечается, и витрина продолжает отдавать старое.

Блокировки в пуле

lock берёт все названные таблицы или ни одной. Блокировку на мгновение он пережидает, а занятую дольше таблицу отказывает — даже если её держит окно программы под тем же логином.
unlock отпускает только то, что взял этот пул.
В конце пул отпускает всё, что взял, — unlock последним шагом не нужен. Отпущенное перечислено в unlocked.

Ответ

{"ok": false,
 "steps": [
   {"num": 1, "do": "lock", "tables": ["store"]},
   {"num": 2, "do": "generate", "value": 4187, "name": "new_id"},
   {"num": 3, "do": "insert", "error": "Duplicate entry '4187' for key 'PRIMARY'"}
 ],
 "changed": [], "unlocked": ["store"], "ms": 14}

Поле	Что это
`ok`	дошёл ли пул до конца
`steps`	шаги по порядку: номер `num`, шаг `do`, `name`, если было, ответ шага или `error` у остановившегося
`changed`	какие таблицы отмечены для кеша
`unlocked`	какие таблицы пул отпустил
`ms`	сколько длился вызов на сервере

Отказы

Шаг, который не прошёл, останавливает пул. Ответ приходит с признаком ошибки и тем же JSON; шаги до остановившегося выполнены, их изменения остались.

`error` шага	Когда
`Table is busy: … - the lock is listed in the program and lifted there`	`lock`: таблица занята
`Not locked by this pool: …`	`unlock`: таблицу взял не этот пул
`Unknown table: …`	названа таблица, которой нет
`No generator for: … - a table without one takes its id from AUTO_INCREMENT`	`generate`: генератора с таким именем нет
`Nothing to insert: rows is empty`, `rows takes a list of rows…`, `Row … has other columns than the first one`	`insert`: строки не того вида
`This tree is not for the agent: …`	служебное дерево
`Not a tree table: …`	у таблицы нет полей дерева
`No parent … in …`, `No node … in …`	нет такого узла
`No such node, or the parent sits inside the moved branch`	`tree_move`: узла нет или новый родитель внутри переносимой ветки
`The id of this step takes a whole number, and […] is not one`, `The parent_id of this step…`	`id` или `parent_id` не целое число
`This sweep is not for the agent: …`	уборка `user` или `user_group`
`Unlock before this sweep: …`	уборка, пока пул держит таблицы
`No dependent list for …`	у таблицы нет записанных зависимых
`No step named … before this one`	`@имя` ссылается на шаг, которого раньше нет
`Unknown step: …`	такого шага нет
текст ошибки базы	ошибка в запросе

Отказы до запуска пула — те же, что у engine_db_select.

Общие отказы — «Ответы и отказы».