Поделиться через

SqlPackage

SqlPackage — это программа командной строки, которая автоматизирует задачи разработки баз данных путем предоставления некоторых общедоступных api Data-Tier Application Framework (DacFx). Основные варианты использования SqlPackage сосредоточены на переносимости баз данных и развертываниях для семейства баз данных SQL Server, SQL Azure и Azure Synapse Analytics. SqlPackage можно автоматизировать с помощью Azure Pipelines и GitHub или других средств CI/CD.

Скачайте последнюю версию. См. подробности в заметках о выпуске.

Примечание.

Хотя Microsoft Entra ID является новым названием для Azure Active Directory (Azure AD), чтобы не нарушать существующие среды, Azure AD по-прежнему используется в некоторых жестко закодированных элементах, таких как поля пользовательского интерфейса, поставщики подключений, коды ошибок и командлеты. В этой статье два имени являются взаимозаменяемыми.

Портативность

Переносимость базы данных — это возможность перемещения схемы базы данных и данных между различными экземплярами SQL Server, SQL Azure и Azure Synapse Analytics. Экспорт базы данных из базы данных SQL Azure в локальный экземпляр SQL Server или из SQL Server в базу данных SQL Azure — это примеры переносимости базы данных. SqlPackage поддерживает переносимость базы данных с помощью действий экспорта и импорта , которые создают и используют BACPAC-файлы. SqlPackage также поддерживает переносимость баз данных с помощью операций извлечения и публикации, которые создают и используют файлы DACPAC, которые могут содержать данные непосредственно или ссылаться на данные, хранящиеся в хранилище BLOB-объектов Azure.

  • Экспорт: экспорт подключенной базы данных SQL, включая схему базы данных и пользовательские данные, в файл BACPAC (.bacpac).

  • Импорт: импортирует данные схемы и таблицы из BACPAC-файла в новую пользовательскую базу данных.

Развертывания

Развертывания базы данных — это процесс обновления схемы базы данных в соответствии с требуемым состоянием, например добавление столбцов в таблицу или изменение содержимого хранимой процедуры. SqlPackage поддерживает развертывание баз данных с помощью операций публикации и извлечения. Действие публикации обновляет схему базы данных в соответствии с содержимым исходного DACPAC-файла, а действие "Извлечение" создает файл приложения уровня данных (DACPAC), содержащий схему или схему и пользовательские данные из подключенной базы данных SQL. SqlPackage позволяет развертываниям как для новых, так и для существующих баз данных из одного артефакта (DACPAC) автоматически создавать план развертывания, который применяет необходимые изменения к целевой базе данных. План развертывания можно проверить перед применением изменений в целевой базе данных с помощью действий Script или DeployReport .

  • Извлечение: создает файл приложения уровня данных (DACPAC), который содержит схему или схему и пользовательские данные из подключенной базы данных SQL.

  • Публикация: постепенно обновляет схему базы данных, чтобы соответствовать схеме исходного .dacpac файла. Если база данных не существует на сервере, операция публикации создает ее. В противном случае обновляется существующая база данных.

  • DeployReport: создает XML-отчет, представляющий изменения, которые будут предприняты действием публикации.

  • DriftReport: создает XML-отчет, представляющий изменения, примененные к зарегистрированной базе данных с момента последней регистрации.

  • скрипт: создает скрипт добавочного обновления Transact-SQL, который обновляет схему целевого объекта для сопоставления схемы источника.

Синтаксис Command-Line

SqlPackage инициирует действия, указанные с помощью параметров, свойств и переменных SQLCMD, указанных в командной строке.

SqlPackage {parameters} {properties} {SQLCMD variables}

Дополнительные сведения о синтаксисе командной строки SqlPackage подробно описаны в справочнике по интерфейсу командной строки SqlPackage и на страницах отдельных действий.

Команды служебной программы

Версия

Отображает версию sqlpackage как номер сборки. Можно использовать в интерактивных запросах и в автоматизированных процессах.

SqlPackage /Version

Помощь

Сведения об использовании SqlPackage можно отобразить с помощью /? или /help:True.

SqlPackage /?

Для сведений о параметрах и свойствах, относящихся к конкретному действию, используйте параметр справки в дополнение к параметру этого действия.

SqlPackage /Action:Publish /?

Аутентификация

SqlPackage проходит проверку подлинности с помощью методов, доступных в SqlClient. Настройка типа проверки подлинности может выполняться с помощью параметров строки подключения для каждого действия SqlPackage (/SourceConnectionString и /TargetConnectionString) или с помощью отдельных параметров для свойств подключения. В строке подключения поддерживаются следующие методы проверки подлинности:

  • Проверка подлинности SQL Server
  • Проверка подлинности Active Directory (Windows)
  • Проверка подлинности Microsoft Entra
    • Имя пользователя и пароль
    • Встроенная проверка подлинности
    • Универсальная проверка подлинности
    • Managed Identity
    • Принципал службы

Управляемая идентичность

Примечание.

Microsoft Entra ID ранее был известен как Azure Active Directory (Azure AD).

В автоматизированных средах управляемое удостоверение Microsoft Entra — это рекомендуемый метод проверки подлинности. Этот метод не требует передачи учетных данных в SqlPackage во время выполнения, так как SqlPackage использует управляемые удостоверения для подключения к базам данных, поддерживающим проверку подлинности Microsoft Entra, и для получения маркеров Microsoft Entra без управления учетными данными. Если управляемое удостоверение настроено для среды, в которой выполняется действие SqlPackage, действие SqlPackage может использовать это удостоверение для проверки подлинности в SQL Azure. Дополнительную информацию о настройке управляемого удостоверения для вашего окружения смотрите в документации по управляемому удостоверению.

Пример строки подключения с использованием управляемого удостоверения, назначаемого системой:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Управляемые удостоверения поддерживаются как в Azure DevOps, так и в GitHub Actions в конвейерах CI/CD.

Принципал службы

Примечание.

Microsoft Entra ID ранее был известен как Azure Active Directory (Azure AD).

Субъекты-службы приложений Microsoft Entra — это объекты безопасности в приложении Microsoft Entra, которые определяют, что приложение может делать в данном арендаторе. Они настраиваются на портале Azure во время процесса регистрации приложения и настроены для доступа к ресурсам Azure, таким как SQL Azure. Дополнительные сведения о настройке служебного принципала для вашей среды см. в документации по служебному принципалу.

При использовании SqlPackage с учетной записью службы можно получить токен доступа и передать его в SqlPackage. Маркер доступа можно получить с помощью модуля Azure PowerShell или Azure CLI. В этом процессе вызывающая система поддерживает контроль над обновлением или аннулированием токена. Маркер доступа можно передать в SqlPackage с помощью /at параметра.

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Кроме того, можно передать идентификатор клиента и секрет служебного принципала в SqlPackage в строке подключения. Формат строки подключения включает Authentication=Active Directory Service Principal; и User Id=AppId; Password=<password>. Когда учетные данные учетной записи службы передаются в строке подключения, параметр /at не требуется, и SqlPackage обновляет проверку подлинности по мере необходимости во время операции.

Принципы службы поддерживаются как в конвейерах CI/CD, так и в Azure DevOps и GitHub Actions.

Переменные среды

Организация пулов соединений

Пул подключений можно включить для всех подключений, сделанных SqlPackage, задав для переменной CONNECTION_POOLING_ENABLED среды значение True. Этот параметр рекомендуется для операций с именем пользователя и паролем Microsoft Entra, чтобы избежать регулирования библиотекой проверки подлинности Майкрософт (MSAL).

Временные файлы

Во время операций SqlPackage данные таблицы записываются во временные файлы до сжатия или после декомпрессии. Для больших баз данных эти временные файлы могут занять значительное количество дискового пространства, но их расположение можно указать. Операции экспорта и извлечения включают необязательное свойство, указывающее /p:TempDirectoryForTableData для переопределения значения SqlPackage по умолчанию.

Api .NET GetTempPath используется для определения значения по умолчанию в SqlPackage.

Для Windows следующие переменные среды проверяются в следующем порядке и используется первый путь, который существует:

  1. Путь, указанный переменной TMP среды.
  2. Путь, указанный переменной TEMP среды.
  3. Путь, указанный переменной USERPROFILE среды.
  4. Каталог Windows.

Для Linux и macOS, если путь не указан в переменной TMPDIR среды, используется путь /tmp/ по умолчанию.

Пользователи SqlPackage и базы данных

Пользователи автономной базы данных включаются в операции SqlPackage. Однако часть определения пароля задается случайной строкой, сгенерированной SqlPackage, и существующее значение не передается. Рекомендуется установить новый безопасный пароль для нового пользователя после импорта .bacpac или развертывания .dacpac. В автоматизированной среде значения паролей можно получить из безопасного хранилища ключей, например Azure Key Vault, на этапе после выполнения SqlPackage.

Расширяемость

SqlPackage поддерживает расширяемость с помощью управляемой платформы расширяемости (MEF), позволяя расширенные сценарии через настраиваемые компоненты, называемые участниками. Эти расширения могут настроить способ публикации .dacpac файлов SqlPackage, позволяя командам применять стандарты или автоматизировать логику для конкретного проекта. Вкладчики развертывания выполняются в рамках процесса публикации после создания плана развертывания, но до его выполнения. Эти участники могут получить доступ к плану развертывания и изменить его с помощью DeploymentPlanModifier объекта класса для добавления, удаления или изменения порядка действий. Чтобы приступить к работе с расширяемостью развертывания, см. статью "Использование участников развертывания для настройки сборки и развертывания базы данных".

SqlPackage обнаруживает и загружает сборки участника, сканируя библиотеки динамических ссылок (.dll файлы) в том же каталоге, что и исполняемый файл SqlPackage, а также расположения, указанные в необязательном свойстве /p:AdditionalDeploymentContributorPathsкомандной строки. Хотя это обеспечивает гибкую настройку, она также содержит важные рекомендации по обеспечению безопасности.

Это важно

Так как SqlPackage использует MEF для динамической загрузки библиотек динамических ссылок (.dll файлов) во время выполнения, все сборки, размещенные вместе с исполняемым файлом SqlPackage, могут выполняться как часть процесса развертывания. Злоумышленник может использовать это поведение, введя изменения или несанкционированные расширения, которые выполняют произвольный код.

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

Сбор данных об использовании

SqlPackage содержит функции с поддержкой Интернета, которые могут собирать и отправлять анонимные данные об использовании функций и диагностических данных в Корпорацию Майкрософт.

SqlPackage может собирать сведения о стандартном компьютере, использовании и производительности, которые могут передаваться в Корпорацию Майкрософт и анализироваться для повышения качества, безопасности и надежности SqlPackage.

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

Дополнительные сведения см. в заявлении о конфиденциальности Майкрософт и приложении к заявлению о конфиденциальности SQL Server.

Отключите отчеты телеметрии

Чтобы отключить сбор и отчеты телеметрии, обновите переменную DACFX_TELEMETRY_OPTOUT среды до true или 1.

Поддержка

Библиотека DacFx и средство интерфейса командной строки SqlPackage следуют современной политике жизненного цикла Майкрософт. Все обновления системы безопасности, исправления и новые функции выпускаются только в последней версии основной версии. Обслуживание установок DacFx или SqlPackage до текущей версии помогает своевременно получать все применимые исправления ошибок.

Получите справку по SqlPackage, отправьте запросы функций и сообщите о проблемах в репозитории DacFx GitHub.

Поддерживаемые решения SQL

SqlPackage и DacFx поддерживают все поддерживаемые версии SQL во время выпуска SqlPackage/DacFx. Например, выпуск SqlPackage 14 января 2022 г. поддерживает все поддерживаемые версии SQL в январе 14 2022 г. Дополнительные сведения о политиках поддержки SQL см. в политике поддержки SQL.

Помимо SQL Server, SqlPackage и DacFx поддерживают Управляемый экземпляр SQL Azure, Базу данных SQL Azure, Azure Synapse Analytics и хранилище данных Synapse в Microsoft Fabric.

Дальнейшие действия