次の方法で共有

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

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

全体的な戦略

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

任意のディレクトリでコマンド プロンプトから SqlPackage コマンドを実行できる SqlPackage の dotnet ツールをインストールできない場合は、以下の手順を実施します。

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

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

Import/Export サービスの代わりに SqlPackage を使用する

Import/Export サービスを使ってデータベースをインポートまたはエクスポートしようとしている場合は、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 でのエラーと予期しない動作の診断は、診断ログと診断パッケージでサポートされています。 診断ログはトラブルシューティングに不可欠であり、/DiagnosticsFile:<filename> パラメーターを使用してファイルにキャプチャされます。

診断出力の詳細レベルは、/DiagnosticsLevel パラメーターによって制御されます。 Information と Verbose の値は、詳細を取得する場合に役立ちます。

パフォーマンス関連のトレース データは、SqlPackage を実行する前に環境変数 DACFX_PERF_TRACE=true 設定することでログに記録できます。 トレース データによってログ出力が増加するため、パフォーマンスの問題を診断する場合にのみ含まれます。 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 で、無期限に待機するのに使います。

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

エクスポート コマンドと抽出コマンドの場合、テーブル データは 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 での接続セキュリティの変更について詳しくは、「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 が制約にランダムな名前を割り当てる) と明示的に名前が付けられた制約を使用する制約がある場合、同じ名前の制約が 2 回作成される可能性があります。 明示的に名前が付けられたすべての制約を使用する (DEFAULT を使用しない) か、システム定義のすべての名前を使用する (DEFAULT を使用する) 必要があります。
  3. model.xml を手動で編集し、エラーが発生した名前の制約の名前を一意の名前に変更します。 Microsoft サポートから指示され、.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 のパラメーターは、SqlPackage プロセスを実行するスレッドの最大スタック サイズを指定するすべてのコマンド (/ThreadMaxStackSize:) で使用できます。 既定値は、SqlPackage を実行する .NET バージョンによって決まります。 大きな値を設定すると、SqlPackage の全体的なパフォーマンスに影響する可能性がありますが、この値を大きくすると、入れ子になったステートメントによって発生するスタック オーバーフローの例外が解決されることがあります。 可能な場合、スタック オーバーフローの例外を回避するために T-SQL コードをリファクタリングすることをお勧めしますが、回避策として /ThreadMaxStackSize: パラメーターを使用できます。

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

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

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

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

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

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

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

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

Azure SQL Database

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

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

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

その他のリソース

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

最も関連性の高い記事の一部を次に示します。

関連コンテンツ