SqlPackage

SqlPackage は、パブリックのデータ層アプリケーション フレームワーク (DacFx) API の一部を公開することで、次のデータベース開発タスクを自動化するコマンドライン ユーティリティです。

  • バージョン:SqlPackage アプリケーションのビルド番号が返されます。

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

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

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

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

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

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

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

SqlPackage コマンド ライン ツールでは、これらの操作と共に、操作固有のパラメーターおよびプロパティを指定できます。

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

Note

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

コマンド ライン構文

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

SqlPackage {parameters} {properties} {SQLCMD variables}

終了コード

SqlPackage コマンドは次の終了コードを返します。

  • 0 = 成功
  • nonzero = failure

使用例

その他の例については、個々のアクション ページを参照してください。

現在のデータベース スキーマの .dacpac ファイルを作成する:

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

パラメーター

SqlPackage アクション間で共有されるパラメーターもあります。 パラメーターについてまとめた表を次に示します。詳細については、特定のアクション ページをクリックしてください。

パラメーター 短い形式 抽出 発行 エクスポート [インポート] DeployReport DriftReport スクリプト
/AccessToken: /at x x x x x x x
/ClientId: /cid x
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x x x x x x x
/DiagnosticsFile: /df x x x x x x x
/MaxParallelism: /mp x x x x x x x
/OutputPath: /op x x x
/OverwriteFiles: /of x x x x x x
/Profile: /pr x x x
/Properties: /p x x x x x x
/Quiet: /q x x x x x x x
/Secret: /secr x
/SourceConnectionString: /scs x x x x x
/SourceDatabaseName: /sdn x x x x x
/SourceEncryptConnection: /sec x x x x x
/SourceFile: /sf x x x x
/SourcePassword: /sp x x x x x
/SourceServerName: /ssn x x x x x
/SourceTimeout: /st x x x x x
/SourceTrustServerCertificate: /stsc x x x x x
/SourceUser: /su x x x x x
/TargetConnectionString: /tcs x x x x
/TargetDatabaseName: /tdn x x x x x
/TargetEncryptConnection: /tec x x x x x
/TargetFile: /tf x x x x
/TargetPassword: /tp x x x x x
/TargetServerName: /tsn x x x x x
/TargetTimeout: /tt x x x x x
/TargetTrustServerCertificate: /ttsc x x x x x
/TargetUser: /tu x x x x x
/TenantId: /tid x x x x x x x
/UniversalAuthentication: /ua x x x x x x x
/Variables: /v x x

プロパティ

SqlPackage アクションは、アクションの既定の動作を変更する多数のプロパティをサポートしています。 詳細については、各アクション ページをクリックしてください。

ユーティリティ コマンド

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

Note

Microsoft Entra ID は、Azure Active Directory (Azure AD) の新しい名前です。 現時点ではドキュメントは更新中です。

自動化された環境では、Microsoft Entra マネージド ID が推奨される認証方法になります。 このメソッドでは、実行時に SqlPackage に資格情報を渡す必要はありません。 SqlPackage アクションが実行される環境に対してマネージド ID が構成されている場合、SqlPackage アクションはその ID を使用して Azure SQL に対する認証を行うことができます。 ご利用の環境に合わせたマネージド ID の構成の詳細については、マネージド ID のドキュメントに関するページをご覧ください。

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

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

環境変数

接続のプール

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_OPTOUTtrue または 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 のサポート ポリシーに関するページを参照してください。

次のステップ