SqlPackage

  • Статья

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

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

Примечание.

Хотя идентификатор Microsoft Entra — это новое имя 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.

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

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

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

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

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

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

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

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

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

Синтаксис командной строки

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

SqlPackage {parameters} {properties} {SQLCMD variables}

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

Вспомогательные команды

Версия

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

SqlPackage /Version

Справка

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

SqlPackage /?

Чтобы получить сведения о параметре или свойстве для определенного действия, используйте параметр help с параметром этого действия.

SqlPackage /Action:Publish /?

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

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

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

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

Примечание.

Идентификатор Microsoft Entra ранее был известен как 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;

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

Субъект-служба

Примечание.

Идентификатор Microsoft Entra ранее был известен как 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;"

Субъекты-службы поддерживаются как в конвейерах 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 содержит функции с поддержкой Интернета, которые могут собирать и отправлять анонимные данные об использовании функций и диагностических данных в Корпорацию Майкрософт.

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 Server, SqlPackage и DacFx поддерживают Управляемый экземпляр SQL Azure, База данных SQL Azure, Azure Synapse Analytics и Хранилище данных Synapse в Microsoft Fabric.

Следующие шаги