SqlPackage

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

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

移植性

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

• Export: 接続されている SQL データベースを、データベース スキーマとユーザー データを含め、BACPAC ファイル (.bacpac) にエクスポートします。

• Import: BACPAC ファイルから新しいユーザー データベースにスキーマとテーブル データをインポートします。

デプロイメント

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

• Extract: 接続されている SQL データベースから、スキーマまたはスキーマとユーザー データを含め、データ層アプリケーション (.dacpac) ファイルを作成します。

• Publish: ソース .dacpac ファイルのスキーマに合わせてデータベース スキーマの増分更新を行います。 データベースがサーバーに存在しない場合は、公開操作によって作成されます。 存在する場合は、既存のデータベースが更新されます。

• DeployReport: Publish アクションが実行する変更を表す XML レポートを作成します。

• DriftReport: 登録されたデータベースの前回の登録以降に適用された変更を表す XML レポートを作成します。

• Script: ソースのスキーマに合わせてターゲットのスキーマを更新する、Transact-SQL の増分更新スクリプトを作成します。

コマンド ライン構文

SqlPackage を使うと、コマンド ラインで指定したパラメーター、プロパティ、SQLCMD 変数を使って、指定した操作を開始できます。

SqlPackage {parameters} {properties} {SQLCMD variables}

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

ユーティリティ コマンド

Version

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 が推奨される認証方法です。 この方法では、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 Actions の両方の CI/CD パイプラインでサポートされます。

サービス プリンシパル

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 Actions の両方の CI/CD パイプラインでサポートされます。

環境変数

接続のプール

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

一時ファイル

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

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

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

1. TMP 環境変数で指定されたパス。
2. TEMP 環境変数で指定されたパス。
3. USERPROFILE 環境変数で指定されたパス。
4. 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 で指定された場所をスキャンすることで、共同作成者アセンブリを検出して読み込みます。 これにより、柔軟なカスタマイズが可能になりますが、セキュリティに関する重要な考慮事項も生じます。

使用状況データ収集

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

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

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

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

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

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

支援

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

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

サポートされる SQL 製品

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

SQL Server に加えて、SqlPackage と DacFx では、Microsoft Fabric で Azure SQL Managed Instance、Azure SQL Database、Azure Synapse Analytics、Synapse Data Warehouse がサポートされています。

次のステップ

• SqlPackage Extract について詳しく学習する
• SqlPackage Publish について詳しく学習する
• SqlPackage Export について詳しく学習する
• SqlPackage Import について詳しく学習する
• SqlPackage の問題のトラブルシューティングについて詳しく学習する
• DacFx GitHub リポジトリで SqlPackage に関するフィードバックを共有する