SqlPackage

2025-06-21

SqlPackage は、パブリック API Data-Tier Application Framework (DacFx) API の一部を公開することで、データベース開発タスクを自動化するコマンドラインユーティリティです。 SqlPackage の主なユースケースは、SQL Server、Azure SQL、Azure Synapse Analytics ファミリのデータベースの移植性とデプロイに重点を置いています。 SqlPackage は、 Azure Pipelines と GitHub アクション、またはその他の CI/CD ツールを使用して自動化できます。

最新バージョンをダウンロードします。最新リリースに関する詳細については、リリースノートをご覧ください。

注

Microsoft Entra ID は Azure Active Directory (Azure AD) の新しい名前ですが、既存の環境の中断を防ぐために、Azure AD は、UI フィールド、接続プロバイダー、エラーコード、コマンドレットなどのハードコーディングされた要素に残ります。この記事では、2 つの名前は交換可能です。

移植性

データベースの移植性とは、SQL Server、Azure SQL、Azure Synapse Analytics の異なるインスタンス間でデータベーススキーマとデータを移動する機能です。 Azure SQL Database からオンプレミスの SQL Server インスタンスへのデータベースのエクスポート、または SQL Server から Azure SQL Database へのデータベースのエクスポートは、データベースの移植性の例です。 SqlPackage は、BACPAC ファイルを作成および使用するエクスポートアクションとインポートアクションを通じて、データベースの移植性をサポートします。また、SqlPackage は、データを直接格納することも、Azure Blob Storage に格納されているデータを参照することもできる DACPAC ファイルを作成および使用する Extract アクションと Publish アクションによるデータベースの移植性もサポートしています。

のエクスポート: 接続された SQL データベース (データベーススキーマやユーザーデータを含む) を BACPAC ファイル (.bacpac) にエクスポートします。
のインポート: BACPAC ファイルから新しいユーザーデータベースにスキーマとテーブルのデータをインポートします。

デプロイメント

データベース配置は、テーブルへの列の追加やストアドプロシージャの内容の変更など、目的の状態に一致するようにデータベーススキーマを更新するプロセスです。 SqlPackage は、 Publish アクションと Extract アクションによるデータベースのデプロイをサポートします。 [発行] アクションは、ソース .dacpac ファイルの内容と一致するようにデータベーススキーマを更新します。一方、[抽出] アクションは、接続された SQL データベースのスキーマまたはスキーマとユーザーデータを含むデータ層アプリケーション (.dacpac) ファイルを作成します。 SqlPackage を使用すると、ターゲットデータベースに必要な変更を適用するデプロイプランを自動的に作成することで、同じ成果物 (.dacpac) の新規または既存のデータベースの両方に対するデプロイが可能になります。デプロイメント・プランは、変更をターゲット・データベースに適用する前に、 Script アクションまたは DeployReport アクションで確認することができます。

の抽出: 接続された SQL データベースのスキーマまたはスキーマとユーザーデータを含むデータ層アプリケーション (.dacpac) ファイルを作成します。
発行: ソース .dacpac ファイルのスキーマと一致するようにデータベーススキーマを増分更新します。データベースがサーバー上に存在しない場合は、発行操作によってデータベースが作成されます。それ以外の場合は、既存のデータベースが更新されます。
DeployReport: 発行アクションが実行する変更を表す XML レポートを作成します。
DriftReport: 最後に登録されてからの登録済みデータベースに適用された変更を表す XML レポートを作成します。
スクリプト: ソースのスキーマと一致するようにターゲットのスキーマを更新する Transact-SQL 増分更新スクリプトを作成します。

Command-Line 構文

SqlPackage は、コマンドラインで指定されたパラメーター、プロパティ、および SQLCMD 変数を使用して、指定されたアクションを開始します。

SqlPackage {parameters} {properties} {SQLCMD variables}

SqlPackage コマンドライン構文の詳細については、 SqlPackage CLI リファレンスと個々のアクションページを参照してください。

ユーティリティコマンド

バージョン

sqlpackage バージョンをビルド番号として表示します。対話型プロンプトや自動パイプラインで使用できます。

SqlPackage /Version

ヘルプ

/? または /help:Trueを使用して、SqlPackage の使用状況情報を表示できます。

SqlPackage /?

特定のアクションに固有のパラメーターとプロパティ情報については、そのアクションのパラメーターに加えてヘルプパラメーターを使用します。

SqlPackage /Action:Publish /?

認証

SqlPackage は、 SqlClient で使用できるメソッドを使用して認証します。認証の種類の構成は、各 SqlPackage アクション (/SourceConnectionString と /TargetConnectionString) の接続文字列パラメーター、または接続プロパティの個々のパラメーターを使用して行うことができます。接続文字列では、次の認証方法がサポートされています。

SQL Server 認証
Active Directory (Windows) 認証
Microsoft Entra 認証
- ユーザー名/パスワード
- 統合認証
- ユニバーサル認証
- マネージド ID
- サービスプリンシパル

マネージド ID

注

Microsoft Entra ID は、以前は Azure Active Directory (Azure AD) という名前でした。

自動化された環境では、 Microsoft Entra マネージド ID が推奨される認証方法です。この方法では、SqlPackage はマネージド ID を使用して Microsoft Entra 認証をサポートするデータベースに接続し、資格情報の管理なしで Microsoft Entra トークンを取得するため、実行時に SqlPackage に資格情報を渡す必要はありません。 SqlPackage アクションが実行される環境に対してマネージド ID が構成されている場合、SqlPackage アクションはその ID を使用して Azure SQL に対する認証を行うことができます。環境のマネージド ID の構成の詳細については、マネージド ID のドキュメントを参照してください。

システム割り当てマネージド ID を使用した接続文字列の例を次に示します。

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

マネージド ID は、 Azure DevOps と GitHub アクションの両方の CI/CD パイプラインでサポートされています。

サービスプリンシパル

注

Microsoft Entra ID は、以前は Azure Active Directory (Azure AD) という名前でした。

Microsoft Entra アプリケーションサービスプリンシパルは、Microsoft Entra アプリケーション内のセキュリティオブジェクトであり、特定のテナントでアプリケーションが実行できる操作を定義します。これらは、アプリケーションの登録プロセス中に Azure portal で設定され、Azure SQL などの Azure リソースにアクセスするように構成されます。環境のサービスプリンシパルの構成の詳細については、サービスプリンシパルのドキュメントを参照してください。

サービスプリンシパルと共に SqlPackage を使用する場合は、アクセストークンを取得して SqlPackage に渡すことができます。アクセストークンは、 Azure PowerShell モジュールまたは Azure CLI を使用して取得できます。このプロセスでは、呼び出し元のシステムがトークンの更新または無効化の制御を維持します。アクセストークンは、 /at パラメーターを使用して SqlPackage に渡すことができます。

# 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;"

または、サービスプリンシパルクライアント ID とシークレットを接続文字列で SqlPackage に渡すこともできます。接続文字列の形式には、Authentication=Active Directory Service Principal; と User Id=AppId; Password=<password> が含まれます。サービスプリンシパルの資格情報が接続文字列で渡される場合、 /at パラメーターは不要になり、SqlPackage は操作中に必要に応じて認証を更新します。

サービスプリンシパルは、 Azure DevOps と GitHub アクションの両方の CI/CD パイプラインでサポートされています。

環境変数

接続のプール

SqlPackage によって行われるすべての接続に対して接続プールを有効にするには、 CONNECTION_POOLING_ENABLED 環境変数を True に設定します。この設定は、Microsoft 認証ライブラリ (MSAL) による調整を回避するために、Microsoft Entra のユーザー名とパスワード接続を使用した操作に推奨されます。

一時ファイル

SqlPackage 操作中、テーブルデータは圧縮前または圧縮解除後に一時ファイルに書き込まれます。大規模なデータベースの場合、これらのテンポラリ・ファイルは大量のディスク・スペースを占有する可能性がありますが、ロケーションを指定することはできます。エクスポート操作と抽出操作には、SqlPackage の既定値をオーバーライドする /p:TempDirectoryForTableData を指定する省略可能なプロパティが含まれています。

.NET API の GetTempPath は、SqlPackage 内の既定値を決定するために使用されます。

Windows の場合、次の環境変数が次の順序でチェックされ、最初に存在するパスが使用されます。

TMP環境変数で指定されたパス。
TEMP環境変数で指定されたパス。
USERPROFILE環境変数で指定されたパス。
Windows ディレクトリ。

Linux と macOS では、 TMPDIR 環境変数でパスが指定されていない場合は、デフォルトのパス /tmp/ が使用されます。

SqlPackage とデータベースユーザー

包含データベースユーザーは、SqlPackage 操作に含まれます。ただし、定義のパスワード部分は SqlPackage によってランダムに生成された文字列に設定され、既存の値は転送されません。新しいユーザーのパスワードは、 .bacpac のインポートまたは .dacpacのデプロイ後に安全な値にリセットすることをお勧めします。自動化された環境では、パスワード値は、SqlPackage に続く手順で、Azure Key Vault などのセキュリティで保護されたキーストアから取得できます。

拡張性

SqlPackage は、 Managed Extensibility Framework (MEF) による拡張性をサポートし、 共同作成者と呼ばれるカスタムコンポーネントを通じて高度なシナリオを可能にします。これらの拡張機能は、SqlPackage が .dacpac ファイルを発行する方法をカスタマイズできるため、チームは標準を適用したり、プロジェクト固有のロジックを自動化したりできます。デプロイ共同作成者は、デプロイ計画が生成された後、実行される前に、発行プロセスの一部として実行されます。これらの共同作成者は、 DeploymentPlanModifier クラスオブジェクトを使用してデプロイ計画にアクセスし、ステップを追加、削除、または並べ替えることができます。デプロイの拡張性の使用を開始するには、「デプロイ共同作成者を使用してデータベースのビルドとデプロイをカスタマイズする」を参照してください。

SqlPackage は、SqlPackage 実行可能ファイルと同じディレクトリ内のダイナミックリンクライブラリ (.dll ファイル) と、オプションのコマンドラインプロパティ /p:AdditionalDeploymentContributorPathsで指定された場所をスキャンすることで、共同作成者アセンブリを検出して読み込みます。これにより、柔軟なカスタマイズが可能になりますが、セキュリティに関する重要な考慮事項も生じます。

Von Bedeutung

SqlPackage は MEF を使用して実行時にダイナミックリンクライブラリ (.dll ファイル) を動的に読み込むため、SqlPackage 実行可能ファイルと共に配置されたアセンブリは、配置プロセスの一部として実行できます。悪意のあるアクターは、任意のコードを実行する改ざんされた拡張機能や承認されていない拡張機能を導入することで、この動作を悪用する可能性があります。

SqlPackage で使用されるコンパイル済みの拡張ファイルがセキュリティで保護され、信頼できるソースからのものであることを確認するのは、ユーザーの責任です。 SqlPackage フォルダへのアクセスを制御し、すべてのカスタムコンポーネントまたはサードパーティコンポーネントの整合性を検証することをお勧めします。

使用状況データ収集

SqlPackage には、匿名の機能の使用状況と診断データを収集して Microsoft に送信できるインターネット対応機能が含まれています。

SqlPackage は、SqlPackage の品質、セキュリティ、および信頼性を向上させるために Microsoft に送信され、分析される可能性のある標準的なコンピューター、使用、およびパフォーマンスの情報を収集する場合があります。

SqlPackage は、ユーザー固有の情報や個人情報を収集しません。診断目的で 1 人のユーザーを概算するために、SqlPackage は、実行されているコンピューターごとにランダムな GUID を生成し、送信するすべてのイベントにその値を使用します。

詳細については、「Microsoft プライバシーに関する声明」と「SQL Server のプライバシーの補足情報」を参照してください。

テレメトリレポートを無効にする

テレメトリの収集とレポートを無効にするには、環境変数 DACFX_TELEMETRY_OPTOUT を true または 1 に更新します。

支援

DacFx ライブラリと SqlPackage CLI ツールは、 Microsoft モダンライフサイクルポリシーに従います。すべてのセキュリティ更新プログラム、修正プログラム、および新機能は、メジャーバージョンの最新のポイントバージョンでのみリリースされます。 DacFx または SqlPackage のインストールを現在のバージョンに維持すると、該当するすべてのバグ修正をタイムリーに受け取ることができます。

SqlPackage に関するヘルプを参照し、機能要求を送信し、 DacFx GitHub リポジトリで問題を報告します。

サポートされる SQL 製品

SqlPackage と DacFx は、SqlPackage/DacFx リリースの時点でサポートされているすべての SQL バージョンをサポートします。たとえば、2022 年 1 月 14 日の SqlPackage リリースでは、2022 年 1 月 14 日でサポートされているすべてのバージョンの SQL がサポートされます。 SQL サポートポリシーの詳細については、SQL サポートポリシーを参照してください。

SQL Server に加えて、SqlPackage と DacFx は、Azure SQL Managed Instance、Azure SQL Database、Azure Synapse Analytics、および Microsoft Fabric の Synapse Data Warehouse をサポートしています。

次のステップ

SqlPackage 抽出詳細を確認する
SqlPackage 発行のの詳細を確認する
SqlPackage エクスポート詳細を確認する
SqlPackage インポートのの詳細を確認する
SqlPackage に関するトラブルシューティングの問題の詳細を確認する
DacFx GitHub リポジトリで SqlPackage に関するフィードバックを共有

次の方法で共有