SqlPackage に関する問題とパフォーマンスのトラブルシューティング

  • [アーティクル]

シナリオによっては、SqlPackageの操作に予想以上の時間がかかることや、操作が完了しないことがあります。 この記事では、これらの操作のトラブルシューティングやパフォーマンス向上のためによく提案される戦術について説明します。 使用できるパラメーターやプロパティを理解するには各アクションの特定のドキュメントのページを読むことをお勧めしますが、SqlPackageの操作を調べるときはこの記事が出発点となります。

全体的な戦略

一般的なガイドラインとして、DacFramework.msi によってインストールされた .NET Framework バージョンではなく、SqlPackage の .NET バージョンを使用することで、パフォーマンスを向上できます。

任意のディレクトリでコマンド プロンプトから SqlPackage コマンドを実行できる SqlPackage dotnet ツールをインストールできない場合:

  1. お使いのオペレーティングシステム (Windows、macOS、またはLinux) 用の .NET 8 の SqlPackageの zip をダウンロードします。
  2. ダウンロード ページの指示に従ってアーカイブを解凍します。
  3. コマンド プロンプトを開き、SqlPackageフォルダーにディレクトリを変更 (cd) します。

パフォーマンスの向上とバグ修正が定期的にリリースされるため、利用可能な最新バージョンの SQLPackageを使用することが重要です。

インポート/エクスポートサービスの代わりにSqlPackageを使用する

インポート/エクスポートサービスを使ってデータベースをインポートまたはエクスポートしようとしている場合は、SqlPackage を使うと、オプション パラメーターとプロパティをより細かく制御しながら同じ操作を実行できます。

インポートの場合は、次のようなコマンドです。

./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 認証 (旧称Azure Active Directory)を通じて認証を行うことができます。 /ua:true と /tid:"yourdomain.onmicrosoft.com" のユーザー名とパスワードのパラメーターを置き換えます。

一般的な問題

タイムアウト エラー

タイムアウトに関連する問題の場合は、次のプロパティを使って、SqlPackageとSQL インスタンスの間の接続を調整できます。

  • /p:CommandTimeout=: クエリが実行されたときのコマンド タイムアウトを秒単位で指定します。 既定:60
  • /p:DatabaseLockTimeout=: データベースのロック タイムアウトを秒単位で指定します。 -1を使うと無期限に待機できます。既定値: 60
  • /p:LongRunningCommandTimeout=: 実行時間の長いコマンドのタイムアウトを秒単位で指定します。 既定値は 0 で、無期限に待機するのに使います。

クライアント リソースの消費量

エクスポートおよび抽出コマンドの場合、bacpac/dacpac ファイルに書き込まれる前に、テーブル データはバッファーのために一時ディレクトリに渡されます。 このストレージ要件は大きくなる可能性があり、エクスポートされるデータのフル サイズに比例します。 /p:TempDirectoryForTableData=<path> プロパティを使って、代替の一時ディレクトリを指定します。

スキーマ モデルはメモリ内でコンパイルされるため、大規模なデータベース スキーマの場合、SqlPackageを実行するクライアント マシンで大量のメモリが必要になる可能性があります。

サーバーのリソース消費量が少ない場合

SqlPackageの最大サーバー並列処理は既定では 8 に設定されます。 サーバー リソースの消費量が少ないことに気付いた場合は、MaxParallelism パラメーターの値を大きくするとパフォーマンスが向上する可能性があります。

アクセス トークン

/AccessToken: または/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)

つながり

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の接続セキュリティの変更の詳細については、「SqlPackage161 での接続セキュリティの強化」を参照してください。

制約のインポート アクション エラー 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 が制約にランダムな名前を付与) と、明示的に名前を付けた制約がある場合、同じ名前の制約が 2 回作成される可能性があります。 明示的に名前を付けたすべての制約を使用する (DEFAULTを使用しない) か、システムが定義したすべての名前を使用する (DEFAULTを使用する) ことをお勧めします。
  3. model.xmlを手動で編集し、エラーが発生した名前で制約の名前を一意の名前に変更します。 このオプションは、Microsoft サポートから指示され、.bacpac の破損のリスクがある場合にのみ実行する必要があります。

Stack Overflow の例外エラー

多くの入れ子になったステートメントを含む大規模な T-SQL スクリプトは、多くの場合、間欠的または永続的な Stack Overflow の例外エラーの原因となります。 この場合、エラー メッセージには 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 プロセスを実行するスレッドの最大スタック サイズを指定できます。 既定値は、SqlPackage を実行している .NET バージョンによって決まります。 大きな値を設定すると、SqlPackage の全体的なパフォーマンスに影響を与える可能性があります。ただし、この値を大きくすることで、入れ子になったステートメントによって発生する Stack Overflow の例外エラーが解決される可能性もあります。 可能な限り Stack Overflow の例外エラーを回避するために T-SQL コードのリファクタリングが推奨されますが、/ThreadMaxStackSize: パラメーターを回避策として使用することも可能です。

/ThreadMaxStackSize: パラメーターを使用する際にパフォーマンスへの影響が示された場合は、Stack Overflow の例外エラーを解決する最小値に繰り返し操作を調整することをお勧めします。 パラメーターの値は MB (メガバイト) で、回避策としてテストするための値の例には、10 と 100 が含まれます。

診断

トラブルシューティングにはログが不可欠です。 /DiagnosticsFile:<filename> パラメーターを使用して、診断ログをファイルにキャプチャします。

SqlPackageを実行する前に環境変数 DACFX_PERF_TRACE=trueを設定することにより、パフォーマンスに関連するより多くのレース データをログできます。 PowerShellでこの環境変数を設定するには、次のコマンドを使用します。

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

インポート アクションのヒント

インポートに大きなテーブルまたは多数のインデックスを持つテーブルが含まれる場合、/p:RebuildIndexesOfflineForDataPhase=True または/p:DisableIndexesForDataPhase=Falseを使用するとパフォーマンスが向上する可能性があります。 これらのプロパティは、インデックス再構築操作がオフラインで発生するか、または発生しないようにそれぞれ変更します。 これらの、そして他のプロパティを使用して、SqlPackageImport 操作を調整できます。

エクスポート アクションのヒント

エクスポートの間にパフォーマンスが低下する一般的な原因は未解決のオブジェクト参照であり、SqlPackageはオブジェクトの解決を何回も試みます。 たとえば、テーブルを参照するビューが定義されていて、テーブルがデータベースに存在しなくなっていることがあります。 エクスポートのログに未解決の参照がある場合は、データベースのスキーマを修正して、エクスポートのパフォーマンスを向上させることを検討してください。

OS ディスク領域が制限され、エクスポート中に枯渇するシナリオでは、/p:TempDirectoryForTableDataを使用すると、エクスポートするデータを代替ディスクでバッファーすることができます。 この操作に必要な領域の占める割合が、データベースの完全なサイズに対して大きくなることがあります。 これとその他のプロパティを使用して、SqlPackageExport 操作を調整できます。

エクスポート プロセスの間に、テーブル データは bacpac ファイルに圧縮されます。 Fast、SuperFast、または NotCompressed に設定された /p:CompressionOption を使うと、出力 bacpac ファイルの圧縮は少なくなりますが、エクスポート プロセスの速度が向上する可能性があります。

スキーマ検証をスキップしながらデータベース スキーマとデータを取得するには、プロパティ /p:VerifyExtraction=FalseでExportを実行します。 インポートできない無効なエクスポートが行われる可能性があります。

Azure SQL データベース

次のヒントは、Azure 仮想マシン (VM) からAzure SQL Database に対してインポートまたはエクスポートを実行する場合に固有のものです。

  • パフォーマンスを最適にするには、Business Critical またはPremium 階層のデータベースを使用します。
  • VM で SSD ストレージを使用します。
  • bacpac のファイルを解凍するのに十分なスペースがあることを確認します。
  • データベースと同じリージョン内の VM からSqlPackageを実行します。
  • VM で高速ネットワークを有効にします。

PowerShellスクリプトを使用してインポート操作に関する詳細情報を収集する方法の詳細については、「教訓 #211:SqlPackageインポート プロセスの監視」を参照してください。

その他のリソース

Azure Database サポート ブログには、Azure SQL Database のトラブルシューティングとパフォーマンス チューニングに関する多くの記事が含まれています。これには、SqlPackage に関する記事もいくつか含まれています。

以下は、最も関連性の高い記事の一部です。

関連するコンテンツ