Divisionz.Scaffold.SQLScriptExecutor.Bin 1.0.0-rc845

Divisionz.Scaffold.SQLScriptExecutor.Bin

Библиотека выполнения коллекций sql скриптов одной командой. SQL скрипты группируются в команды, команды могут включть в себя другие команды. CLI-обёртка (dotnet tool sql-exec) поставляется отдельным пакетом Divisionz.Scaffold.SQLScriptExecutor.

Библиотека провайдер-нейтральна: конкретный исполнитель разрешается через DI — зарегистрируйте фабрики провайдеров (AddMSSQLExecutor / AddPostgreSQLExecutor / AddMySQLExecutor из пакетов Divisionz.Scaffold.SQLScriptExecutor.{MSSQL,PostgreSQL,MySQL} или Add{Provider}Provider из Divisionz.Scaffold.DB.{Provider}) и задайте Utils.SharedServices. Тип провайдера определяется из строки подключения (ProviderTypeResolver), если не задан явно в конфиге.

Пример программного формирования набора команд и запуска

using Divisionz.Scaffold.SQLScriptExecutor.Bin;
using Divisionz.Scaffold.SQLScriptExecutor.Model;
using Microsoft.Extensions.DependencyInjection;

// 1. Регистрация фабрик исполнителей (по одной на используемый провайдер)
Utils.SharedServices = new ServiceCollection()
    .AddPostgreSQLExecutor()
    .BuildServiceProvider();

// 2. Формирование пакета команд
var package = new SQLPackage
{
    ConnectionString = "Host=localhost;Database=mydb;Username=postgres;Password=secret"
};
package.AddScript("create", "1.tables.sql", "CREATE TABLE demo(id int PRIMARY KEY);");
package.AddScript("seed", "1.seed.sql", "INSERT INTO demo(id) VALUES (1);");
// провайдер можно задать явно: package.Provider = ProviderType.PostgreSQL;
// иначе он определяется из строки подключения

// 3. Запуск (одна транзакция на исполнитель)
using (var exec = package.GetSQLExecutor())
{
    await exec.ExecuteAsync(package.Commands["create"]);
    await exec.ExecuteAsync(package.Commands["seed"]);
    exec.CommitAndClose();
}

Готовый пакет можно также прочитать из файла (SqlPackageStore.Read) или собрать сканированием каталога (SqlPackageStore.FromFolder).

Пример конфигурационного файла

{
  "ConnectionString": "",
  "SQLFileExtension": "sql",
  "Commands": {
    "create": {
      "Include": [
        "./1.tables.sql",
        "updateSP"
      ]
    },
    
    "drop": {
      "Include": [
        "./0.drop.sql"
      ]
    },
    "updateSP": {
      "Include": [
        "./0.utils.sql"
      ]
    },
    
    "Utils": {
      "Include": [
        "./Utils/backup.sql",
        "./Utils/error.sql",
        "./Utils/restore.sql"
      ]
    }
  }
}

Чтение команд из embedded-ресурсов сборки

SqlPackageStore.FromEmbeddedResources(Assembly) собирает пакеты команд прямо из ресурсов, встроенных в сборку (например, в сборку модели). Имя ресурса разбирается по схеме:

{сборка}.SQL.{Provider}.{команда}.{файл}
Model.SQL.PostgreSQL.create.1.tables.sql   →   пакет PostgreSQL, команда create, скрипт 1.tables.sql

Встраивание в .csproj сборки-владельца скриптов:

<EmbeddedResource Include="SQL\PostgreSQL\create\1.tables.sql" />

На каждый найденный {Provider} создаётся отдельный SQLPackage (с заполненным Provider), внутри — команды по именам папок:

var packages = SqlPackageStore.FromEmbeddedResources(typeof(Rank).Assembly);
var package = packages.Single(p => p.Provider == ProviderType.PostgreSQL);
package.ConnectionString = cs;

using (var exec = package.GetSQLExecutor())
{
    await exec.ExecuteAsync(package.Commands["create"]);
    exec.CommitAndClose();
}

Произвольные папки (напр. SQL\{provider}\Utils\...) становятся командами с тем же именем — в потоки стандартных команд они не вплетаются, вызывайте их явно.

Стандартные команды

Зарезервированные имена команд. Под этими именами генератор эмитит команды в SQLExecConfig.json, поэтому скрипты, встроенные в сборку под стандартным именем (SQL\{provider}\{команда}\...), попадают именно в эту команду — так переопределяется или расширяется её набор скриптов (например, своя SQL\PostgreSQL\create\9.custom.sql добавится к сгенерированному create).

Хуки before{команда} / after{команда}

Любую стандартную команду X можно обернуть SQL-хуком из сборки модели. Если существует команда before{X} — её скрипты выполняются до X; after{X} — после. Вплетание автоматическое:

• при генерации — в Include команды (before{X} в начало, after{X} в конец);
• для migrate — при упаковке миграции (beforeMigrate/afterMigrate попадают в migrate.Include), исполняются на каждую применяемую миграцию.

Имя хука = before/after + имя команды с заглавной первой буквой: create→beforeCreate/afterCreate, migrate→beforeMigrate/afterMigrate, updateSP→beforeUpdateSP/afterUpdateSP.

Пример — хук после миграции (refresh/ресид):

Model/SQL/PostgreSQL/afterMigrate/1.refresh.sql

→ в SQLExecConfig.json появится команда afterMigrate, и migrate.Include сошлётся на неё.

Регистронезависимость

Имена команд и хуков регистронезависимы: папка/ключ/ссылка в Include в любом регистре распознаются одинаково (beforeMigrate = BeforeMigrate = BEFOREMIGRATE). В эмитённом SQLExecConfig.json ключи канонические (beforeMigrate). Элемент Include без расширения трактуется как имя команды, с расширением — как файл.

Провайдер и автоопределение

Поле Provider в конфиге (необязательное) явно задаёт СУБД: MSSQL, PostgreSQL, MySQL, Oracle, SQLite. Если Provider не задан, тип провайдера выводится из строки подключения (ProviderTypeResolver).

Для надёжного автоопределения:

• MySQL — используйте ключ Uid (например Server=...;Port=3306;Database=...;Uid=root;Pwd=...). Uid однозначно указывает на MySQL; User ID/UserID неоднозначны (их принимают также MSSQL и Oracle), поэтому автоопределение MySQL по ним не сработает.
• MSSQL — Initial Catalog, Integrated Security, TrustServerCertificate, Encrypt либо Data Source=host,port.
• PostgreSQL — Host, Username, Search Path.
• Oracle — TNS-дескриптор (DESCRIPTION=...) либо EZ-connect Data Source=host:port/service_name.
• SQLite — Data Source=:memory:, файл .db/.sqlite*, либо ключи Version/Mode/Cache.

Многопакетный запуск из корня (flush-all-sql)

sql-exec может выполнить сразу несколько пакетов, обнаружив их рекурсивно. Если в корневом каталоге нет SQLExecConfig.json, sql-exec использует натуральную сортировку и спускается в подкаталоги, пока в каждом не найдёт конфиг — и действует по нему.

Так устроен вывод wdst -fs --sql-provider=X:

{out}/SQL/{provider}/
  0.{базовая сборка}/SQLExecConfig.json   (+ sql-файлы)
  1.{зависимая сборка}/SQLExecConfig.json (+ sql-файлы)

• sql-exec {out}/SQL/{provider}/ create — выполнит create в каждом пакете в порядке возрастания generation (базовые сборки раньше).
• sql-exec {out}/SQL/{provider}/ drop --order DESC — drop в порядке убывания (зависимые раньше).
• Порядок — числовой по числовому префиксу имени каталога (0 < 1 < 2 < 10, НЕ алфавитный 0, 10, 2).

Для AI-агентов

sql-exec --agent-rules печатает встроенный гайд (контракт CLI в агент-ориентированном формате); sql-exec --agent-rules --out AGENTS.md пишет его в файл репозитория.