Устранение неполадок и производительности с помощью SqlPackage

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

Общая стратегия

В качестве общего руководства, более высокую производительность можно получить, используя версию SqlPackage на базе .NET вместо версии на базе .NET Framework, установленной с помощью DacFramework.msi.

Если вы не можете установить инструмент SqlPackage dotnet, который позволяет выполнять команды SqlPackage из командной строки в любом каталоге:

  1. Скачайте ZIP-файл для SqlPackage в .NET 8 для операционной системы (Windows, macOS или Linux).
  2. Распаковать архив согласно указаниям на странице скачивания.
  3. Откройте окно командной строки и смените каталог (cd) на папку SqlPackage.

Используйте последнюю доступную версию SqlPackage, так как регулярно публикуются улучшения производительности и исправления ошибок.

Замена SqlPackage для службы импорта и экспорта

Если вы попытались использовать службу импорта и экспорта для импорта или экспорта базы данных, можно использовать SqlPackage для выполнения той же операции с дополнительным контролем над необязательными параметрами и свойствами. Запись блога Оптимизация импорта BACPAC: SqlPackage Done Right! описывает шаги по использованию SqlPackage вместо службы импорта и экспорта для импорта .bacpac.

Пример команды для импорта:

./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>

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

./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>

Используйте многофакторную аутентификацию в качестве альтернативы имени пользователя и паролю для аутентификации с помощью Microsoft Entra. Замените параметры имени пользователя и пароля для /ua:true и /tid:"contoso.onmicrosoft.com".

Diagnostics

Диагностика ошибок и непредвиденного поведения в SqlPackage поддерживается журналами диагностики и пакетом диагностики. Журналы диагностики важны для устранения неполадок и записываются в файл с параметром /DiagnosticsFile:<filename>.

Управление уровнем детализации диагностического вывода через /DiagnosticsLevel параметр. Используйте Information значения и Verbose для получения большей информации.

Записывайте данные трассировки, связанные с производительностью, задав переменную среды DACFX_PERF_TRACE=true перед запуском SqlPackage. Данные трассировки увеличивают объём журнала, поэтому включайте их только при диагностике проблем с производительностью. Чтобы задать эту переменную среды в PowerShell, используйте следующую команду:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

В SqlPackage 162.5 и более поздних версиях вы можете создать диагностический пакет для помощи в устранении неполадок. Пакет диагностики содержит версию SqlPackage, выполненную команду, сведения о моделях исходной и целевой базы данных, а также выходные данные команды. Чтобы создать пакет диагностики, используйте параметр /DiagnosticsPackageFile:<filename>.

Общие проблемы

Ошибки, связанные с истечением времени ожидания

Для проблем с тайм-аутом используйте следующие свойства для настройки соединения между SqlPackage и экземпляром SQL:

  • /p:CommandTimeout=: Указывает время ожидания команды в секундах при выполнении запроса. По умолчанию: 60
  • /p:DatabaseLockTimeout=. Задает время ожидания блокировки базы данных в секундах. Используйте -1 для ожидания на неопределенный срок. По умолчанию: 60
  • /p:LongRunningCommandTimeout=: Указывает время ожидания длительной команды в секундах. Стандартное значение 0, , ждёт бесконечно.

Потребление ресурсов клиента

Для команд экспорта и извлечения SqlPackage передаёт данные таблицы во временный каталог для буферизации перед записью в файл BACPAC или DACPAC. Это требование к объёму хранилища может быть значительным и зависит от полного объёма экспортируемых данных. Укажите альтернативный временный каталог со свойством /p:TempDirectoryForTableData=<path>.

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

Низкое потребление ресурсов сервера

По умолчанию SqlPackage устанавливает максимальный параллелизм сервера равным 8. Если вы заметили низкое потребление ресурсов сервера, увеличение значения MaxParallelism параметра может повысить производительность.

Маркер доступа

Использование параметра /AccessToken: or /at: позволяет аутентификация на основе токена для SqlPackage, но передача токена команде может быть сложной. Если вы парсируете объект токена доступа в PowerShell, либо явно передайте значение строки, либо оберните ссылку на свойство токена в $(). Рассмотрим пример.

$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken
# OR
SqlPackage /at:$($AccessToken_Object.Token)

Connection

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

  • Подключение без шифрования: /SourceEncryptConnection:False или /TargetEncryptConnection:False
  • Сертификат сервера доверия: /SourceTrustServerCertificate:True или /TargetTrustServerCertificate:True

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

The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
The connection string provided contains encryption settings which may lead to connection failure if the server is not properly configured.

Дополнительные сведения об изменениях безопасности подключения в SqlPackage см. в разделе "Улучшения безопасности подключения" в SqlPackage 161.

Ошибка действия импорта 2714 для ограничения

При выполнении действия импорта вы можете получить ошибку 2714, если объект уже существует:

*** Error importing database:Could not import package.
Error SQL72014: Core Microsoft SqlClient Data Provider: Msg 2714, Level 16, State 5, Line 1 There is already an object named 'DF_Department_ModifiedDate_0FF0B724' in the database.
Error SQL72045: Script execution error. The executed script:
ALTER TABLE [HumanResources].[Department]
    ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];

Ниже приведены причины и решения для решения этой ошибки:

  1. Убедитесь, что база данных, в которую вы импортируете, является пустой.
  2. Если в вашей базе данных есть ограничения, использующие атрибут DEFAULT (где SQL Server присваивает этому ограничению случайное имя) и явно названное ограничение, ограничение с одинаковым именем может быть создано дважды. Используйте все явно названные ограничения (не используйте DEFAULT), или все системно определённые имена (используйте DEFAULT).
  3. Вручную отредактируйте файл model.xml и переименуйте ограничение, имя которого вызывает ошибку, на уникальное имя. Этот вариант следует выбрать только в том случае, если это рекомендовано службой поддержки Майкрософт и данная опция представляет риск .bacpac повреждения.

Исключение переполнения стека

Крупные скрипты T-SQL с множеством вложенных операторов могут вызывать периодические или постоянные исключения переполнения стека. Когда возникает такое состояние, сообщение об ошибке включает текст Stack overflow и трассу стека:

Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.Visit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.ExplicitVisit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)

Параметр sqlPackage доступен во всех командах, /ThreadMaxStackSize:что указывает максимальный размер стека для потока, выполняющего процесс SqlPackage. Значение по умолчанию определяется версией .NET под управлением SqlPackage. Установка большого значения может повлиять на общую производительность SqlPackage. Однако увеличение этого значения может устранить исключение переполнения стека, вызванное вложенными операторами. Выполните рефакторинг кода T-SQL, чтобы по возможности избежать исключений переполнения стека. Если вы не можете рефакторить, используйте этот /ThreadMaxStackSize: параметр как обходной путь.

При использовании /ThreadMaxStackSize: параметра настройте повторяющиеся операции на минимальное значение, которое устраняет исключение переполнения стека, если вы заметите влияние производительности. Значение параметра в мегабайтах (МБ). Например, вы можете проверить значения вроде 10 и 100.

Советы по операциям импорта

Для импорта, содержащих большие таблицы или таблицы с множеством индексов, использование /p:RebuildIndexesOfflineForDataPhase=True или /p:DisableIndexesForDataPhase=False может повысить производительность. Эти свойства изменяют операцию перестроения индекса, чтобы она происходила в автономном режиме или не происходила соответственно. Вы можете использовать эти свойства и другие свойства для настройки операции SqlPackage Import.

Индексы отключаются после импорта

Для эффективной загрузки данных импорт отключает некластерные индексы до фазы данных и восстанавливает их после этого (поведение по умолчанию /p:DisableIndexesForDataPhase=True ). Если импорт прерывается или не происходит после загрузки данных, но до завершения восстановления, один или несколько некластерных индексов могут оставаться отключенными. Отключённый индекс остаётся в метаданных, но оптимизатор запросов игнорирует его, что может привести к медленным запросам после импорта, который в остальном кажется успешным.

Чтобы найти отключённые индексы, проверьте столбец is_disabled в каталоге sys.indexes :

SELECT OBJECT_SCHEMA_NAME(object_id) AS schema_name,
       OBJECT_NAME(object_id) AS table_name,
       name AS index_name
FROM sys.indexes
WHERE is_disabled = 1;

Чтобы снова включить отключённый индекс, перестройте его с помощью ALTER INDEX. Используйте ALTER INDEX ALL ... REBUILD для включения всех отключённых индексов в таблице:

ALTER INDEX ALL ON <schema>.<table> REBUILD;

Для получения дополнительной информации см. раздел «Включить индексы и ограничения».

Советы по операциям экспорта

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

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

Распространённой причиной снижения производительности при экспорте являются нерешённые ссылки на объекты. Эта проблема заставляет SqlPackage пытаться разрешить объект несколько раз. Например, определен вид, который ссылается на таблицу, но эта таблица больше не существует в базе данных. Если в журнале экспорта отображаются неразрешенные ссылки, рекомендуется исправить схему базы данных, чтобы повысить производительность экспорта.

Во время экспорта данные таблицы сжимаются в bacpac-файле. Установка /p:CompressionOption на Fast, SuperFastили NotCompressed может повысить скорость экспорта при меньшем сжатии выходного bacpac-файла.

Для получения схемы и данных базы данных при пропуске проверки схемы выполните операцию Экспорт со свойством /p:VerifyExtraction=False. Недопустимый экспорт может быть создан, который не может быть импортирован.

Место на диске во время экспорта

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

База данных SQL Azure

Следующие советы относятся к выполнению импорта или экспорта в Базу данных SQL Azure с виртуальной машины Azure:

  • Используйте базу данных уровня "Бизнес-критический" или "Премиум" для лучшей производительности.
  • Используйте хранилище SSD на виртуальной машине.
  • Убедитесь, что достаточно места для распаковки рюкзака.
  • Выполнение SqlPackage из виртуальной машины в том же регионе, что и база данных.
  • Включите ускоренную сеть на виртуальной машине.

Для получения дополнительной информации об использовании скрипта PowerShell для сбора деталей об операции импорта см. Урок #211: Мониторинг процесса импорта SQLPackage.

Дополнительные ресурсы

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

Ниже приведены некоторые из наиболее важных статей:

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

  • Last updated on