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

Справочник / объект

Скрипт автора

Тип объекта в Holkas: SCR

Holkas · Oracle и PostgreSQL

SQL автора пакета: все поля, запуск до и после объектов, проверка при плане, рёбра и хранение в Git и ZIP.

← Все объекты
На этой странице

Holkas · Скрипты автора пакета

Скрипт готовит данные или проверяет их перед изменением структуры. Например, останавливает установку новой связи, пока в базе остались старые значения.

ИдентификаторSCR + имя
Источник описанияМанифест или файл
В базе-приёмникеВыполнение SQL

Зачем нужен скрипт автора

Holkas сравнивает структуру и метаданные КОР Парус 8. Правило подготовки прикладных данных знает автор пакета. Он записывает SQL в описание строки манифеста SCR, указывает объекты и выбирает запуск до или после их команд.

Проверка — тот же скрипт. Для отказа он вызывает ошибку: raise_application_error на Oracle или RAISE EXCEPTION на PostgreSQL. Например, перед сменой связи классом Request он проверяет, что старые ссылки уже преобразованы. Обычный SELECT, вернувший «ошибка» или число 37, не останавливает перенос сам по себе.

SCR не является хранимой процедурой БД или программой пользовательского приложения. Текст исполняется напрямую в базе-приёмнике. Из таблицы Паруса YPDEVSCR текущая версия Holkas его не выгружает: старые Text в Base64, CallingRelative и CommandsFilter относятся к прежней реализации, которую заменил формат holkas-script/1.

Что входит в перенос

У скрипта нет самостоятельных вложенных объектов. Objects — список ссылок для задания порядка команд; перечисленные классы и функции не становятся его частями.

Выбор SCR CheckRequest сам по себе не включает CLS Request. Добавьте класс или другие нужные объекты в состав переноса отдельно. В базе скрипт появится в плане, только если хотя бы одна их команда действительно нужна. В Git или ZIP описание сохраняется и без связанных команд.

Справочник полей

6 полей описания · 2 поля ссылки · имя объекта

Имя самого скрипта задаётся снаружи описания. Ниже — все шесть полей SCR и оба поля записи Objects. Обозначение «Сравнивается» относится к сохранённому файлу Git; база прежнее состояние скрипта не хранит.

Как читать обозначения и форматы

Ключ — имя скрипта в адресе объекта. Сравнивается — разница в описании может потребовать перезаписи файла Git. В базе все поля задают одно выполнение SCR, отдельных команд для Objects и текстов нет.

Технические имена слева совпадают с Git YAML, рядом указаны имена JSON. Описание строки манифеста и файл внутри ZIP используют разные представления When; примеры ниже показывают каждое.

Адрес и описание скрипта SCR · 7
Nameимя в адресе объектастрокаКлючИмя скрипта
Назначение
Например, CheckRequest. Задаётся в строке манифеста или имени объекта файла, а не среди шести полей описания.
При переносе:
В Git другое имя означает другой файл; прежний автоматически не удаляется. В базе имя обозначает команду выполнения, записи с таким именем там не создаётся.
FormatJSON: formatстрокаСравниваетсяВерсия описания
Назначение
Текущий формат — holkas-script/1.
При переносе:
В описании строки манифеста отсутствие, null или пустое значение заменяются текущим форматом; другой формат отклоняется. В Git поле участвует в сравнении сохранённого описания.
WhenJSON: whenперечислениеСравниваетсяДо или после объектов
Назначение
Before — до всех команд связанных объектов, After — после них. В описании манифеста: before / after; в Git: Before / After; в JSON внутри ZIP: 0 / 1.
При переносе:
В описании манифеста отсутствие или null дают before; пустая строка отклоняется. Для базы меняет направление рёбер, для Git — содержимое файла. After не означает, что скрипт на плане увидит уже выполненные команды.
ObjectsJSON: objectsсписок ссылокСравниваетсяОбласть действия
Назначение
Тип и имя каждого объекта, к командам которого привязан скрипт. [] означает все команды переноса, кроме других скриптов.
При переносе:
Точное имя сопоставляется без учёта регистра вместе с типом; CLS Request охватывает также дочерние корни вида Request|OPEN. Ссылки не добавляют объекты в перенос. Если подходящих команд нет, SCR в план базы не входит. Список хранится целиком; в Git учитывается и перестановка записей. См. ограничение захвата одноимённых корней ниже.
AtPlanJSON: atPlanлогическоеСравниваетсяЗапуск при построении плана
Назначение
true — дополнительно выполнить скрипт в базе-приёмнике при построении плана; false — только при применении.
При переносе:
В описании манифеста отсутствие или null дают false; 0 не заменяет false. На плане каждый скрипт запускается отдельно и откатывается; обычные команды плана перед ним не выполняются. При применении запускается снова. Git и ZIP сохраняют флаг без запуска SQL.
OracleJSON: oracleстрока / nullСравниваетсяТекст для Oracle
Назначение
SQL или PL/SQL для Oracle; отдельная строка / разделяет блоки.
При переносе:
Выбирается приёмником Oracle; автоматического перевода нет. Нужен непустой текст. Если действий нет, задайте BEGIN NULL; END;. В одном блоке — одна SQL-команда либо блок BEGIN / DECLARE; завершающая ; у обычной SQL-команды снимается, у этих PL/SQL-блоков сохраняется. В Git текст сравнивается буквально: пробелы, регистр и окончания строк могут потребовать перезаписи файла.
PostgresJSON: postgresстрока / nullСравниваетсяТекст для PostgreSQL
Назначение
SQL или PL/pgSQL для PostgreSQL; применяется тот же разделитель блоков.
При переносе:
Выбирается приёмником PostgreSQL. В одном блоке допускается несколько SQL-команд. Если действий нет, задайте DO $$ BEGIN NULL; END $$;. Null, пустая строка и пробелы означают отсутствие текста для этой СУБД. В Git учитывается буквальная разница текста, без разбора смысла SQL.
Ссылка на объект Objects[] · 2
TypeJSON: typeстрокаСравниваетсяТип связанного объекта
Назначение
Код типа, например CLS, MSG или JFP; относится к одной записи Objects.
При переносе:
Парсер описания манифеста проверяет известность типа и запрещает SCR: привязка к другому скрипту не поддерживается. Поле не выбирает только Create или только Delete — охватываются все команды подходящего объекта.
NameJSON: nameстрокаСравниваетсяИмя связанного объекта
Назначение
Адрес объекта: Request для CLS, Request|OPEN для ACT, parus.request_ok для JFP. Это не имя самого скрипта.
При переносе:
Парсер описания манифеста убирает крайние пробелы и требует непустое имя; полностью одинаковые пары Type + Name объединяет. Маски не разворачиваются: Request* не обозначает все классы с таким началом. Изменение ссылки меняет область действия, но не переименовывает связанный объект.
Пустые значения и ручная правка

В описании манифеста Objects отсутствует, равен null или [] — значит весь перенос. Для Git и ZIP сохраняйте явный полный список: чтение ZIP (S3 и «Файл пакета») требует поле objects и отклоняет его отсутствие или null. Подстановка [] расширит область действия на все обычные команды.

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

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

Команды плана

SCR
CreateUpdate

Выполнение или сохранение скрипта

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

В Git нет файла — Create; описание отличается — Update; совпадает — команды нет. S3 и «Файл пакета» создают новый ZIP без сравнения с прежним архивом. В этих приёмниках SQL не выполняется.

Ключ: Имя скрипта

Удаление SCR и SetOrder не формируются. Снятие скрипта из манифеста не отменяет SQL, который он уже выполнил, и не удаляет автоматически прежний файл Git.

Пример: проверка перед изменением класса

Учебный PostgreSQL-скрипт проверяет существующую таблицу приёмника parus.request. Свяжите его с CLS Request, задайте Before; AtPlan включайте, если таблица уже доступна до применения.

DO $$ BEGIN
  IF EXISTS (SELECT 1 FROM parus.request WHERE old_ref IS NOT NULL) THEN
    RAISE EXCEPTION 'Сначала преобразуйте старые ссылки заявок';
  END IF;
END $$;

Пока есть старые ссылки, SCR отказывает и команды класса, ожидающие его, пропускаются. Автор преобразует данные отдельно и повторяет перенос: проверка запускается снова. После успешного переноса и исчезновения команд класса SCR также исчезает из плана. Сам скрипт данные не исправляет.

Это условный пример, а не результат нового переноса и не готовая проверка вашей схемы.

Ограничения и что с ними делать

Ошибка и откат при применении

В обычном режиме у SCR своя транзакция. Ошибка любого блока откатывает изменения данных этого скрипта и блокирует команды, которые его ждут. Независимые команды могут продолжить работу; уже выполненные команды других объектов сохраняются.

Если падает скрипт After, предшествующие изменения обычного переноса остаются, а операция становится неуспешной. PostgreSQL поддерживает перенос одной транзакцией: отказ SCR откатывает весь план в пределах этой транзакции. Внешние эффекты и самостоятельно зафиксированные изменения сюда не входят.

AtPlan запускает SQL до применения, с отдельным откатом

На плане каждый SCR с AtPlan запускается отдельно и затем откатывается. Команды объектов перед ним не применяются, даже при When = After. Проверка новой колонки в After может упасть на плане просто потому, что колонка ещё не создана. Для такой проверки выключите AtPlan и оставьте запуск после применения.

Подготовка данных одним SCR при плане не сохраняется для проверки следующим SCR: изменения первого уже отменены. Результат плана — прошёл, упал с текстом ошибки или «выполнится при переносе». Успех пробы не резервирует данные: при применении SQL запускается снова.

Oracle DDL и собственные COMMIT не отменяются откатом пробы

Например, CREATE TABLE на Oracle фиксируется самой СУБД: AtPlan с откатом не превращает его в безопасную пробу. Процедуры Паруса и SQL с собственным COMMIT также могут сохранить эффект. Для скриптов с такими действиями не включайте AtPlan. Режим общей транзакции переноса на Oracle недоступен.

Разделитель / и язык приёмника

Разделителем считается вся строка, которая после удаления крайних пробелов равна /. Знак в SELECT 6 / 2 не разделяет блоки. Разбор идёт по строкам, без распознавания SQL-литералов: не оставляйте отдельную строку / внутри многострочного текста или комментария.

На Oracle оформляйте PL/SQL как BEGIN / DECLARE. Для CREATE PROCEDURE и других сложных DDL не переносите автоматически соглашения BEGIN-блока: при выполнении распознаются только эти два первых слова. Текст пишется для конкретной СУБД и доступных ей объектов; Holkas не переводит SQL и не подставляет параметры привязки.

Повтор после частичного отказа может запустить SQL снова

Нет журнала «этот SCR уже выполнен». Если скрипт прошёл, но изменение объекта не удалось, следующий план снова может содержать этот SCR. INSERT без проверки существования способен добавить дубликаты. Пишите повторяемую подготовку, например с проверкой уже обработанных строк, и учитывайте сохранённые изменения предыдущей попытки.

Ограничения Delete у типов Holkas не ограничивают SQL внутри SCR: авторский DELETE может удалить данные. Допустимость действий определяется текстом и правами соединения приёмника.

Папки Паруса и выгрузка в SQL-файл

У SCR нет CrnName, пути каталога Паруса или чтения из YPDEVSCR. Поиск и создание папок в приёмнике ему не нужны. Каталог CustomScript в Git/ZIP — расположение файла Holkas.

Приёмник «SQL-файл» сейчас отклоняет SCR как логический тип. Чтобы сохранить описание с двумя текстами, используйте Git или ZIP; для выполнения — перенос в базу. Возможность хранить SQL внутри SCR не означает поддержку его выгрузки этим приёмником.

Рёбра команд скрипта

Что такое ребро и где оно видно в Holkas →

Рёбра помогают Holkas правильно отсортировать команды перед применением. Ребро связывает две команды и указывает, какая должна выполниться раньше. Для скрипта «до» изменение класса ждёт успешной проверки.

1 · СначалаПроверить старые ссылкиCreate SCR · CheckRequest
→
2 · ЗатемИзменить классUpdate CLS · Request
Учебный пример: Objects содержит CLS Request, When = Before. Если класс уже совпадает и других подходящих команд нет, обеих команд в этом примере не будет.
Два правила для приёмника БД2 правила
Create SCR · Before→Команда объекта

Когда: команда принадлежит объекту из Objects или список пуст. Охватываются все действия и части подходящего объекта.

Ошибка или снятие SCR блокирует ожидающие его команды и далее их зависимых.

Команда объекта→Create SCR · After

Когда: та же область действия, When = After.

Выполнить SQL после всех подходящих команд. Если снять итоговый скрипт, уже предшествующие ему команды этим не снимаются.

Objects не отбирает отдельное действие команды: CLS Request охватывает реквизиты класса, его атрибуты и формы, а также дочерние корни Request|…. Дочерние корни подхватывает только ссылка на класс: MSG Request охватывает лишь сообщение и не захватывает действие ACT Request|OPEN одноимённого класса. Подходят Create, Update, Delete и SetOrder, если их строит соответствующий тип. Тексты Oracle / Postgres не сканируются для поиска зависимостей: чтение таблицы в SQL само по себе не ставит её создание раньше скрипта.

Каждый скрипт работает сам по себе. Holkas не связывает скрипты автора между собой: у каждого своя транзакция и своя проба при плане. Если на один объект стоят два скрипта Before, объект ждёт оба, но второй скрипт не ждёт первого, и порядок между ними не гарантирован. Отказ или снятие одного скрипта блокирует объект, но не другой скрипт. Если шаги зависят друг от друга, например «подготовить, затем проверить», пишите их в одном SCR и разделяйте блоки строкой /. Тогда ошибка первого блока остановит следующие, а при пробе на плане все блоки увидят изменения друг друга.

В Git и ZIP этих двух правил выполнения нет: скрипт сохраняется файлом. Отдельных рёбер на каталог, процедуры по тексту или другие SCR не строится.

Как скрипт хранится в файлах

Ищите каталог CustomScript/. Для имени CheckRequest описание целиком помещается в один файл. Тексты не кодируются Base64 и не раскладываются в отдельные .sql. Имя самого скрипта содержится в пути и оглавлении, а не в шести полях описания.

Git

YAML
CustomScript/CheckRequest.yaml

Git записывает все поля и Objects в YAML; при чтении из Git описание скрипта восстанавливается. В корне репозитория — .holkas. Момент запуска записан как Before или After.

S3

JSON в ZIP
CustomScript/CheckRequest.json

Для S3 SCR помещается отдельным JSON в ZIP; при чтении он берётся по оглавлению manifest.json. Имена полей — camelCase, when — число 0 или 1. ZIP хранится в S3.

Файл пакета

JSON в ZIP
CustomScript/CheckRequest.json

Скачиваемый ZIP создаётся отдельно и устроен для SCR так же. При чтении «Файла пакета» восстанавливается описание вместе со списком и двумя текстами.

Оба ZIP указывают скрипт как {"typeCode":"SCR","name":"CheckRequest"} в manifest.json. Ссылки Objects не создают файлов этих объектов: их нужно включить в выгрузку отдельно. Небезопасные символы имени кодируются в пути: / становится %2F, а не вложенной папкой.

Одно описание в трёх разных представлениях

Учебные полные описания с пустыми SQL-блоками для обеих СУБД. Они иллюстрируют запись формата, а не выполняют полезную проверку данных. Блоки прошли обратное чтение средствами Holkas из файлов; SQL в базе здесь не запускался.

Git — CustomScript/CheckRequest.yaml

Format: holkas-script/1
When: Before
Objects:
- Type: CLS
  Name: Request
AtPlan: true
Oracle: BEGIN NULL; END;
Postgres: DO $$ BEGIN NULL; END $$;

S3 и «Файл пакета» — CustomScript/CheckRequest.json

{
  "format": "holkas-script/1",
  "when": 0,
  "objects": [
    {
      "type": "CLS",
      "name": "Request"
    }
  ],
  "atPlan": true,
  "oracle": "BEGIN NULL; END;",
  "postgres": "DO $$ BEGIN NULL; END $$;"
}

Описание строки манифеста SCR CheckRequest

{
  "format": "holkas-script/1",
  "when": "before",
  "objects": [
    {
      "type": "CLS",
      "name": "Request"
    }
  ],
  "atPlan": true,
  "oracle": "BEGIN NULL; END;",
  "postgres": "DO $$ BEGIN NULL; END $$;"
}

В описании строки манифеста when — строка before / after; в JSON-файле объекта — число 0 / 1; в YAML — Before / After. Не копируйте содержимое ZIP в редактор описания без преобразования этого поля. Каноническая запись описания манифеста может опускать Objects при пустом списке и AtPlan при false; файловый экспорт сохраняет [] и false. Null у текстов опускается.

Текущее описание SCR в строке манифеста имеет приоритет над одноимённым файлом источника. Если нужен изменённый текст из Git, проверьте, что описание строки не подменяет его старой копией. Для устройства ZIP см. формат пакета.

Практический пример с экраном редактора и отказом проверки — скрипт автора перед изменением функции. Сохранение и чтение файлов — Git и файл пакета.

Основа справки: решение о скриптах автора, модель, парсер, построители графа, исполнители и файловые читатели Holkas 0.1.30; сверено 8 ноября 2026. Локально проверены план, каскад ожидания, YAML и запись и чтение ZIP для S3 и для файла пакета на учебном примере. Сеть S3, новый перенос в Oracle/PostgreSQL и запуск SQL примеров здесь не проверялись.