Скрипты предварительного развертывания и после развертывания для Fabric Data Warehouse (предварительная версия)

Применимо к:✅ Хранилище данных в Microsoft Fabric

Important

Эта функция доступна в предварительной версии.

Скрипты предварительного развертывания и после развертывания позволяют выполнять пользовательские команды Transact-SQL в рамках развертывания хранилища в Fabric. Используйте скрипты предварительного развертывания и после развертывания для очистки данных, начальных ссылочных данных или применения безопасности SQL, не выраженной в схеме хранилища.

В хранилище данных Fabric скрипт предварительного или последующего развертывания представляет собой общий SQL-запрос. Эти скрипты можно создавать в проекте базы данных SQL и указывать их в портале Fabric. Обозначение хранится как метаданные на уровне хранилища и сохраняется в системе контроля версий как часть файла хранилища .sqlproj, поэтому оно корректно проходит через Git и конвейеры развертывания без необходимости повторного применения вручную.

В этой статье объясняется, какие сценарии предварительного развертывания и после развертывания представляют собой, как настроить их на портале Fabric, как они работают с конвейерами управления версиями и развертываниями, а также как создавать их в Visual Studio Code и SQL Server Management Studio (SSMS).

Important

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

Что такое скрипты перед развертыванием и после развертывания?

Когда вы подключаете рабочее пространство к системе контроля версий, каждый склад представлен как проект базы данных SQL: скрипт SQL-объектов, находящийся под контролем версий и составляющий схему склада (таблицы, представления, хранимые процедуры и функции). Каждый объект хранится в виде .sql файла, содержащего синтаксис языка определения данных (DDL), например CREATE TABLE. Объекты описывают требуемое состояние схемы, а процесс развертывания сравнивает требуемое состояние с целевым хранилищем и создает разностный скрипт T-SQL, который создает, изменяет или удаляет объекты, чтобы целевой объект соответствовал проекту.

Скрипты, выполняемые до и после развертывания, дополняют этот процесс скриптами Transact-SQL, которые выполняются до и после развертывания схемы:

• Скрипт предварительного развертывания запускается перед применением плана развертывания схемы.
• Скрипт после развертывания выполняется после завершения плана развертывания схемы.

Скрипт предварительного развертывания или после развертывания — это один из общих запросов , хранящихся в папке "Запросы " хранилища. Хранилище поддерживает не более одного скрипта предварительного развертывания и одного скрипта после развертывания. Обозначение хранится как метаданные на уровне хранилища, а не путём дублирования содержимого скрипта, поэтому это создаёт лишь незначительные накладные расходы на хранение.

Так как каждый указанный скрипт выполняется при каждом развертывании хранилища, создайте код Transact-SQL так, чтобы он был идемпотентным (то есть безопасным для многократного выполнения).

Tip

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

Распространенные варианты использования

• Управление справочными и статическими данными: Вставлять, обновлять или удалять строки из таблиц подстановочных значений, конфигурационных или справочных таблиц после развертывания схемы.
• Очистка данных. Удаление устаревших или временных данных до или после применения изменений схемы.
• Настройка среды: применение параметров или инициализация состояния, которое отличается от среды разработки, тестирования и рабочей среды.
• Инициализация конвейера на основе метаданных: Подготовка состояния хранилища данных, необходимого для последующих этапов конвейера.
• Безопасность SQL: данные таблицы хранилища и функции безопасности SQL, такие как роли, пользователи и GRANT/DENY разрешения, не включены в проект базы данных SQL. Используйте скрипт после развертывания для повторного создания этих объектов после развертывания, включая различия между тестовой и рабочей средой. Примеры см. в разделе Пример скрипта после развертывания для безопасности SQL.

Структура и синтаксис файла проекта SQL

Проект SQL для хранилища данных ссылается на скрипты, выполняемые до и после развертывания, в файле проекта (.sqlproj), используя типы элементов PreDeploy и PostDeploy. Каждая запись указывает на один общий файл запроса в проекте.

Следующий пример обозначается pre-deployment.sql как скрипт предварительного развертывания и post-deployment.sql в качестве скрипта после развертывания:

<ItemGroup>
  <PreDeploy Include="pre-deployment.sql" />
  <PostDeploy Include="post-deployment.sql" />
</ItemGroup>

Important

Fabric Data Warehouse поддерживает только один файл для скрипта предварительного развертывания и один файл для скрипта после развертывания. Создание скрипта из нескольких файлов, например с помощью команды SQLCMD :r для ссылки на другие файлы, не поддерживается. Если .sqlproj содержит несколько записей до развертывания или после развертывания, обновление Git завершается ошибкой.

Пример скрипта после развертывания для безопасности SQL

Так как функции безопасности SQL не записываются в проекте базы данных SQL, скрипт после развертывания — это распространенный способ повторного их создания после развертывания хранилища. Напишите скрипт, чтобы он смог выполняться во всех развертываниях.

В следующем примере создается пользовательская роль базы данных с именем DataReaders и предоставляется SELECT разрешение на схему dbo .

-- post-deployment.sql
-- Recreate a role and grant permissions after deployment.
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'DataReaders')
BEGIN
    CREATE ROLE DataReaders;
END;
GO

GRANT SELECT ON SCHEMA::dbo TO DataReaders;
GO

Note

Fabric Data Warehouse не поддерживает все инструкцииTransact-SQL, доступные в SQL Server. Убедитесь, что инструкции в скриптах поддерживаются в Fabric Data Warehouse.

Настройка скриптов предварительного развертывания и после развертывания на портале Fabric

На портале Fabric назначьте существующий общий запрос как скрипт предварительного развертывания или после развертывания. Это можно сделать из обозреватель объектов или из параметров элемента хранилища.

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

Из обозревателя объектов

1. В редакторе хранилища разверните папку "Запросы" в обозреватель объектов.
2. Щелкните правой кнопкой мыши общий запрос, который вы хотите использовать.
   • При необходимости перенесите запрос из «Мои запросы » в общий запрос.
3. Выберите "Задать скрипты развертывания". Это действие отправляет вас в область параметров элемента.
4. В полях скрипта предварительного развертывания и скрипта после развертывания выберите Выбрать скрипт.
5. Выберите вариант «Установить запрос как скрипт перед или после развертывания», затем в каждом случае выберите общий запрос. В каждом выпадающем меню перечислены все общие запросы в складе.

Из настроек предмета

1. Откройте настройки склада.
2. Перейдите в раздел CI/CD .
3. В полях скрипта предварительного развертывания и скрипта после развертывания выберите Выбрать скрипт.
4. Выберите вариант «Установить запрос как скрипт перед или после развертывания», затем в каждом случае выберите общий запрос. В каждом выпадающем меню перечислены все общие запросы в складе.

Сделанный вами выбор сохраняется как метаданные на уровне хранилища и синхронизируется между обозреватель объектов и пунктом Настройки для элемента.

Поведение скриптов перед развертыванием и после развертывания

Интеграция с Git

При подключении рабочей области к репозиторию Git обозначения до и после развертывания сериализуются в файл .sqlproj хранилища при выполнении фиксации. При обновлении хранилища из Git Fabric применяет изменения к динамическому хранилищу и запускает скрипты в порядке:

1. Скрипт предварительного развертывания запускается до применения изменений схемы.
2. Применяется план развертывания схемы.
3. Скрипт после развертывания выполняется после завершения изменений схемы.

Обозначения при двусторонней синхронизации через Git дают согласованный результат: независимо от того, настраиваете ли вы скрипт на портале и фиксируете изменения, или создаёте его в .sqlproj и обновляете рабочую область. Повторные коммиты и обновления не приводят к дублированию или потере конфигурации. Так как разрешено только одно предварительное развертывание и один скрипт после развертывания, конфигурация, созданная в Git, заменяет любое существующее обозначение в хранилище при обновлении.

Note

Скрипты до и после развертывания требуют новейшего опыта контроля версий для полной поддержки рабочих процессов Git. В рабочих пространствах, которые не обновлялись, метаданные скриптов развертывания не синхронизируются с контролем версий, и скрипты развертывания не участвуют в рабочих процессах на базе Git.

Это ограничение распространяется только на рабочие процессы Git и не является обязательным условием для развертывания конвейеров (ALM).

С конвейерами развертывания

Конвейеры развертывания используют обозначения до и после развертывания при продвижении склада на этапах разработки, тестирования и производства . Указанные скрипты выполняются детерминированно в каждой целевой среде, поэтому их можно использовать для применения настройки среды или повторного применения безопасности SQL при перемещении содержимого между этапами.

В рабочих пространствах без системы контроля версий

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

Создание скриптов перед развертыванием и после развертывания в проекте базы данных SQL

Вместо портала Fabric можно создавать скрипты до и после развертывания непосредственно в проекте SQL-базы данных хранилища, используя расширение SQL Database Projects в Visual Studio Code или интегрированную среду работы с проектами SQL в SQL Server Management Studio. Конфигурация отображается на портале Fabric (как в обозреватель объектов, так и в параметрах элементов) после следующего обновления Git.

Visual Studio Code

1. Установите расширение проектов базы данных SQL в Visual Studio Code.
2. Откройте проект базы данных SQL для своего хранилища. Если рабочая область подключена к Git, клонируйте репозиторий, откройте папку проекта хранилища.
3. В представлении "Проекты баз данных " щелкните правой кнопкой мыши узел проекта и выберите "Добавить скрипт предварительного развертывания " или "Добавить скрипт после развертывания".
4. Укажите имя скрипта без расширения файла. Файл скрипта добавляется в проект и открывается в редакторе.
5. Добавьте Transact-SQL в скрипт и сохраните файл. Убедитесь, что файл сохранён в .sharedqueries папке для следующего обновления Git.
6. Зафиксируйте и отправьте изменения в репозиторий Git, а затем обновите рабочую область из системы управления версиями, чтобы применить конфигурацию.

SQL Server Management Studio

1. Используйте SQL Server Management Studio 22 или более поздней версии, включая возможности проектов базы данных SQL.
2. Откройте проект базы данных SQL для своего хранилища.
3. В Обозреватель решений щелкните правой кнопкой мыши узел проекта и выберите "Добавить>скрипт". Выберите скрипт предварительного развертывания или скрипт после развертывания.
4. Файл скрипта добавляется в проект и открывается в редакторе запросов.
5. Добавьте Transact-SQL в скрипт и сохраните файл. Убедитесь, что вы сохранили файл в .sharedqueries папке для следующего обновления Git.
6. Зафиксируйте и отправьте изменения в репозиторий Git, а затем обновите рабочую область из системы управления версиями, чтобы применить конфигурацию.

Изменение файла проекта напрямую

В любом инструменте можно назначить скрипт, изменив .sqlproj файл и добавив один PreDeploy или PostDeploy элемент в ItemGroup:

<ItemGroup>
  <PreDeploy Include="./sharedqueries/pre-deployment.sql" />
  <PostDeploy Include="./sharedqueries/post-deployment.sql" />
</ItemGroup>

Миграция из существующих проектов SQL

Если вы мигрируете .sqlproj из SQL Server Data Tools (SSDT) или Visual Studio, который уже содержит записи <PreDeploy> и <PostDeploy>, процесс импорта распознаёт эти записи и связывает их с конфигурацией Fabric перед развертыванием и после развертывания. Так как Fabric поддерживает только одно предварительное развертывание и один скрипт после развертывания, убедитесь, что проект содержит не более одной записи каждого типа перед импортом.

Рекомендации и ограничения

• Хранилище поддерживает только один скрипт предварительного развертывания и один скрипт после развертывания. Он не поддерживает несколько файлов для каждого скрипта.
• Вы не можете назначить один и тот же общий запрос и в качестве скрипта предварительного развертывания, и в качестве скрипта после развертывания.
• Если удалить общий запрос, используемый как скрипт предварительного развертывания или скрипт после развертывания, соответствующее назначение автоматически снимается.
• Если вы преобразуете общий запрос, назначенный в качестве скрипта предварительного развертывания или скрипта после развертывания, в пользовательский запрос, соответствующее назначение будет автоматически снято.
• Скрипты, выполняемые до и после развертывания, запускаются при каждом развертывании хранилища. Скрипты Transact-SQL должны быть идемпотентными, поэтому повторяющиеся запуски не завершаются ошибкой или создают повторяющиеся объекты.
• Скрипты предварительного развертывания и после развертывания не проверяются на соответствие модели базы данных во время сборки. Ошибки в сценариях возникают во время развертывания, а сбой скрипта останавливает развертывание.
• Вы можете использовать только Transact-SQL, поддерживаемые в Fabric Data Warehouse.
• Учетная запись, от имени которой выполняется развертывание, должна иметь разрешения, необходимые для выполнения содержимого скрипта.

Связанные материалы

• Рабочие процессы разработки и развертывания
• Разработка и развертывание зависимостей между хранилищами
• Начните работу с конвейерами развертывания Fabric