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

  • [アーティクル]

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

全体的な戦略

一般的なガイドラインとして、SqlPackageの .NET Core バージョンを使用すると、パフォーマンスが向上します。

  1. お使いのオペレーティングシステム (Windows、macOS、またはLinux) 用の .NET Core の 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 の破損のリスクがある場合にのみ実行してください。

診断

トラブルシューティングにはログが不可欠です。 /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 Database

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

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

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

関連するコンテンツ