Holkas
Написать в поддержку Поддержка

Справочник

Пакет доработок

Что находится внутри ZIP Holkas, как прочитать manifest.json и найти файл объекта. Версия формата, релиз Паруса, имена файлов и ограничения совместимости.

На этой странице

Для чего нужен пакет

ZIP хранит снимок выбранных объектов на момент выгрузки. Его можно передать в другой контур, загрузить как источник и сравнить с базой получателя. Исходная база для этого уже не нужна. Порядок действий и реальные экраны — Передать доработку через ZIP.

В пакет входят определения объектов целиком, а не только команды последнего плана. Обычная таблица TBP сохраняет структуру; строки справочника переносятся отдельным объектом DAT. Рабочие документы и вся база в пакет автоматически не попадают.

Как устроен архив

От строки в оглавлении — к файлу объекта

contracts-1.1.zip
manifest.json

Оглавление и сведения об источнике. Перечисляет пять объектов; у каждого есть отдельный JSON с его содержимым.

  1. CLSHolkasSiteContracts
    Class/HolkasSiteContracts.json

    Свойства класса, атрибуты и визуальные формы.

  2. TBPparus.hksite_contracts
    TablePostgres/parus.hksite_contracts.json

    Структура таблицы, ограничения, индексы и другие части.

  3. JFPparus.f_hksite_contract_check
    FunctionPostgres/parus.f_hksite_contract_check.json

    Определение функции, владелец и права.

  4. METHolkasSiteContracts|CheckAmount
    Method/HolkasSiteContracts%7CCheckAmount.json

    Метод класса — самостоятельный объект пакета.

  5. MECHolkasSiteContracts|UserDefinedMethod
    MethodCall/HolkasSiteContracts%7CUserDefinedMethod.json

    Вызов метода. Разделитель в имени закодирован как %7C.

В практической главе выбраны класс, таблица и функция. При чтении класс раскрылся также в метод и вызов метода: поэтому в архиве пять объектов, а не три.

Структура скачиваемого учебного архива. Порядок записей ZIP и objects — не очередь применения: команды строятся после сравнения с приёмником и упорядочиваются по зависимостям.

В корне находится manifest.json, рядом — каталоги типов с JSON-файлами объектов. Для чтения важны имена записей, а не порядок, в котором архиватор их показывает.

Встроенный manifest.json — не манифест состава формата holkas-manifest/2. Первый описывает уже сохранённый снимок внутри ZIP. Второй — отдельный список для выбора объектов из источника. Их нельзя подставлять друг вместо друга.

Поля manifest.json

ПолеТипЗначение
dbmsСтрокаСУБД источника: обычно postgres или oracle. Один пакет относится к одной СУБД.
formatVersionЦелое числоВерсия устройства пакета. Holkas принимает 1. Это не версия Holkas и не версия вашей доработки.
createdAtСтрока даты и времениМомент выгрузки в UTC, в формате ISO 8601.
createdByОбъектname и email автора выгрузки. Это сведения о происхождении, а не подпись файла или разрешение на применение.
objectsМассивОглавление пакета: по одной записи на объект. Holkas перечисляет содержимое по этому списку.
objects[].typeCodeСтрокаКод типа, например CLS, TBP, JFP. По нему определяется тип объекта и каталог файла.
objects[].nameСтрокаПолное имя объекта Holkas. Для составных имён важны все части и разделители.
parusReleaseСтрока, может отсутствоватьДата релиза Паруса источника: yyyy-MM-dd. Нужна для правил совместимости. В старых пакетах поле отсутствует; это трактуется как исходный релиз раньше всех учитываемых изменений.
singleTransactionЛогическое значение, может отсутствоватьtrue требует полной установки одной транзакцией PostgreSQL. При обычной выгрузке поле опускается. Это требование установки, а не свойство отдельного списка объектов.

Эти поля формирует Holkas. Перенос произвольного ZIP с похожими именами файлов не поддерживается. Смена dbms или parusRelease вручную не переводит SQL и не преобразует содержимое под другую базу.

Заголовок учебного пакета, без массива objects, показанного на иллюстрации:

{
  "dbms": "postgres",
  "formatVersion": 1,
  "createdAt": "2026-10-20T18:36:59.5596977+00:00",
  "createdBy": {
    "name": "site-guide",
    "email": "site-guide@holkas.local"
  },
  "parusRelease": "2024-11-28"
}

Это фрагмент для чтения, не полный файл для замены manifest.json.

Требование одной транзакции

При выгрузке в S3 или файл пакета параметр «Перенести одной транзакцией» записывает singleTransaction: true в оглавление. При чтении такого ZIP требование сильнее настроек сервера, подключения и плана: у операции показана метка «одной транзакцией · требует пакет», а источник итогового значения в REST — package. Явное выключение в плане вызывает отказ.

Приёмник пакетаЧто произойдёт
База PostgreSQLВесь план применяется одной транзакцией. Исключённые команды или команды «вне плана» — отказ до первой записи.
S3 или файл пакетаТребование сохраняется в новом ZIP.
SQL-файл PostgreSQLSQL оборачивается в BEGIN … COMMIT; для выполнения используйте psql -v ON_ERROR_STOP=1.
База или SQL-файл OracleОтказ: общий откат DDL невозможен.
GitТребование теряется; план предупреждает, что при следующем переносе его придётся задать заново.

Для установки нужен Holkas 0.1.25 или новее: прежние версии не обеспечивают это требование. В отдельном манифесте состава такого поля нет. Как выгрузить пакет и проверить обязательный режим.

Как определяется путь объекта

Путь имеет вид КаталогТипа/ЗакодированноеИмя.json. Каталог не равен короткому коду типа: CLS хранится в Class, TBP — в TablePostgres, JFP — в FunctionPostgres. Коды и назначение типов описаны в справочнике объектов.

В имени файла символы /, \, :, *, ?, ", <, >, | и % заменяются на %XX с шестнадцатеричным кодом. Например, | становится %7C, / — %2F, а сам % — %25. Точки, пробелы и кириллица сохраняются. Внутри ZIP каталог отделяется прямым слешем /.

Имя объектаИмя файла
parus.f_hksite_contract_checkparus.f_hksite_contract_check.json
HolkasSiteContracts|CheckAmountHolkasSiteContracts%7CCheckAmount.json
Раздел/СтатусыРаздел%2FСтатусы.json

Первые два имени — из учебного архива; третье иллюстрирует кодирование. Не переименовывайте файл независимо от objects[].name: Holkas вычисляет ожидаемый путь из типа и имени. Просто добавить JSON в архив тоже недостаточно — в оглавлении должна быть соответствующая запись.

Все каталоги типов
КодКаталог в ZIP
ACTAction
APPApplication
CLSClass
CLOClassObject
CTPCompositeTypePostgres
CNSConstraint
PCECustomProcedure
REPCustomReport
SCRCustomScript
DATDataSet
DOMDomain
JFNFunctionOracle
JFPFunctionPostgres
LNKLink
MSGMessage
MECMethodCall
METMethod
JPGPackageOracle
PRMParameter
PICPictogram
JPRProcedureOracle
JPPProcedurePostgres
JSQSequenceOracle
SQPSequencePostgres
STYStereotype
JSYSynonymOracle
JTBTableOracle
TBPTablePostgres
UAPUserApplication
VIWView
JVWViewOracle
JVPViewPostgres

Что хранится в JSON объекта

JSON использует UTF-8 и имена полей в camelCase. Поля со значением null при записи опускаются. Строки SQL могут содержать \n и Unicode-последовательности: после разбора JSON это обычный текст с переносами строк.

Форма содержимого зависит от типа. У функции из учебного пакета есть schema, name, body, owner и grants; у класса — свойства, attributes и visualForms; у таблицы — columns, constraints, indexes, triggers и grants. Идентификатор объекта задаётся строкой оглавления, поэтому поле name не обязано повторяться внутри каждого типа.

У объектов PostgreSQL — таблицы, последовательности, представления, функции, процедуры и составного типа — поле owner обязательно. Если его нет или оно пустое, перенос останавливается до плана и называет такие объекты; роль схемы не подставляется. У объектов Oracle owner не записывается: владельца задаёт схема.

У DAT файл содержит definition и rows: описание набора и считанные строки. Это больше, чем отдельное описание holkas-dataset/1. Формат обеих частей разобран на странице Описание набора данных.

Класс и его подчасти

У класса и каждой его подчасти — ограничения, связи, действия, метода, вызова метода, представления и записи реестра — свой файл и своя строка в objects. В Class/Request.json лежат только реквизиты класса, атрибуты и формы. Метод Request|Save записан в Method/Request%7CSave.json и указан в оглавлении как MET. Так устроены ZIP и из S3, и из «Файла пакета»: архив можно выгрузить одним способом и загрузить другим.

Подчасть можно выгрузить и без класса: она сохранится отдельным файлом. Применить её к базе можно, только если класс уже есть в приёмнике или создаётся в том же переносе.

В ZIP, которые S3 записывал в Holkas 0.1.30 и раньше, подчасти лежали внутри Class/<код>.json, а в objects был указан только класс. Такие архивы читаются и сейчас — через S3 и через «Файл пакета». Обратного нет: Holkas 0.1.30 и более ранних версий не прочитает через S3 новый ZIP с классом и сообщит, что у класса нет поля $.constraints. Обновите Holkas получателя.

Пакет сохраняет положительную спецификацию: перечисленные объекты должны существовать в приёмнике. Отсутствие другого корневого объекта в ZIP не означает команду его удалить. Правила частей и строк набора рассматриваются в модели переноса и справочнике DAT.

Совместимость и проверка

При открытии Holkas ищет manifest.json, разбирает его и проверяет formatVersion. Для перечисленных объектов затем определяются типы и читаются ожидаемые JSON-файлы. Неизвестные текущей версии Holkas типы пропускаются с сообщением в журнале; типы уровня СУБД фильтруются по СУБД, указанной в пакете. Поэтому успешное открытие архива само по себе ещё не подтверждает пригодность всех его объектов.

Логические объекты Паруса могут переноситься между Oracle и PostgreSQL по поддерживаемым правилам. SQL-функция PostgreSQL не становится функцией Oracle от смены приёмника. Перед применением проверяйте состав, журнал, аномалии и команды плана. Покрытие релизов — в проверках совместимости.

У пакета нет поля hash, аналогичного отдельному манифесту состава. Не приписывайте ему правила контрольной суммы holkas-manifest/2. Для контроля передачи всего файла можно отдельно сравнить SHA-256 ZIP на отправляющей и принимающей сторонах; это проверка байтов файла, не электронная подпись.

Если пакет не читается

Сообщение или ситуацияЧто проверить
Архив не открываетсяСкачивание завершилось полностью; передан ZIP, а не HTML страницы или начальный фрагмент ответа MCP.
Нет manifest.jsonФайл лежит именно в корне архива. Не добавилась внешняя папка при перепаковке.
formatVersion … is unsupportedВерсия формата не поддерживается текущим Holkas. Сверьте версии отправителя и получателя; ручная замена числа не конвертирует пакет.
Объект не найден по ожидаемому путиИмя из objects соответствует имени и каталогу JSON; кодирование символов не изменено.
У класса нет поля $.constraintsZIP записан новым Holkas, а читает его через S3 Holkas 0.1.30 или старше. Обновите Holkas получателя или загрузите ZIP как «Файл пакета».
JSON объекта не разбираетсяФайл не обрезан и не изменён несовместимым образом. Получите исходный пакет повторно.
В составе меньше объектов, чем ожидалосьСверьте оглавление и журнал: неизвестные или несовместимые типы могут быть пропущены.

Для изменения доработки предпочтительно изменить источник и выгрузить новый пакет: так оглавление и содержимое будут согласованы. Сборка ZIP вручную не заменяет проверку плана на приёмнике.

Дальше: практический перенос ZIP, манифест состава, описание набора данных.

Старые пакеты и пустые списки

Отсутствующий список, null и [] не взаимозаменяемы. Обязательный список без значения вызывает отказ с именем объекта и поля. Явный пустой список означает известное отсутствие элементов и может породить Delete в приёмнике.

Для отдельных добавленных сведений предусмотрена совместимость: старые формы без назначений и связей с приложениями сохраняют их в приёмнике; отсутствующие настройки регистрации таблицы класса и типы документов связи отчёта тоже сохраняются. Это не доказательство полного совпадения этих частей.

Особый случай — родитель параметра отчёта: старый файл его не содержит и может очистить существующую связь. Альтернативные рабочие места со старым числовым MainWorkPlace нужно выгрузить заново. Старые временные таблицы Oracle без режима хранения читаются как постоянные. Полный перечень действий — переход на 0.1.30.