SqlPackage

  • [アーティクル]

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

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

Note

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

サポート性

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

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

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

デプロイ

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

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

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

  • DeployReport: 公開アクションによって行われる変更に関する XML レポートを作成します。

  • DriftReport:登録されたデータベースに対して最終登録以降に適用された変更に関する XML レポートを作成します。

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

コマンド ライン構文

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

SqlPackage {parameters} {properties} {SQLCMD variables}

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

ユーティリティ コマンド

Version

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

SqlPackage /Version

Help

/? または /help:True を使用して、SqlPackage の使用方法に関する情報を表示できます。

SqlPackage /?

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

SqlPackage /Action:Publish /?

認証

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

  • SQL Server 認証
  • Active Directory (Windows) 認証
  • Microsoft Entra 認証
    • ユーザー名/パスワード
    • 統合認証
    • ユニバーサル認証
    • 管理対象 ID
    • サービス プリンシパル

マネージド ID

Note

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

サービス プリンシパル

Note

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

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

環境変数

接続のプール

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

一時ファイル

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 には、匿名機能の使用状況と診断データを収集して 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 のリリース時にサポートされているすべてのサポートされている SQL バージョンをサポートします。 たとえば、2022 年 1 月 14 日の SqlPackage リリースでは、2022 年 1 月 14 日にサポートされている SQL のすべてのバージョンをサポートしています。 SQL のサポート ポリシーの詳細については、SQL のサポート ポリシーに関するページを参照してください。

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

次のステップ