開発パイプラインでの SqlPackage

SqlPackage は、いくつかのデータベース開発タスクを自動化するコマンドライン ユーティリティであり、CI/CD パイプラインに組み込むことができます。

仮想環境

注意

SQL Server Management Studio や Visual Studio などの他のアプリケーションにバンドルされている SqlPackage 実行可能ファイルを使用するよりも、SqlPackage のスタンドアロン インストールをパイプラインの自動化に使用することが推奨されます。 SqlPackage のスタンドアロン インストールはより頻繁に更新され、他のアプリケーションのリリース周期に関連付けられていません。

Windows では、SqlPackage のスタンドアロン インストールは、パス C:\Program Files\Microsoft SQL Server\160\DAC\bin (DacFx.msi) または %USERPROFILE%\.dotnet\tools (dotnet tool) で使用できます。 Linux では、SqlPackage のスタンドアロン インストールはパス ~/.dotnet/tools (dotnet tool) で使用できます。 Windows 環境と Linux 環境の両方で、.NET Core 用の自己完結型 .zip SqlPackage をダウンロードした場合は、任意の場所に実行可能ファイルを抽出できます。

マネージド仮想環境

GitHub Actions でホストされているランナーと Azure Pipelines VM イメージに使用される仮想環境は、runner-images GitHub リポジトリで管理されます。 SqlPackage は、windows-latestubuntu-latest など、複数の環境に含まれています。 runner-images のイメージへの更新は、SqlPackage の各リリースの数週間以内に行われます。

セルフホステッド仮想環境

セルフホステッド Azure DevOps エージェントなどのセルフホステッド仮想環境で、定期的にアプリケーションを更新して、環境を最新バージョンで維持します。

デプロイの追跡

SqlPackage に関連するいくつかのファイルをキャプチャして、パイプラインを再現し、展開の追跡を向上させることができます。 実装と使用例は、特定のアーキテクチャと自動化環境によって異なります。

  • DACPAC ファイル
  • 任意のアクションからの診断ファイルの出力: 任意の SqlPackage アクションで /DiagnosticsFile: パラメーターを使用します。「パイプライン エージェントでの SqlPackage 診断を取得する」を参照してください
  • 発行アクションの前のスクリプト アクションからの出力: 発行アクションを呼び出す前に、スクリプト SqlPackage アクションを使用します

その他の SqlPackage の例

SqlPackage のバージョンを確認する

トラブルシューティング作業中は、使用されている SqlPackage のバージョンを把握しておくことが重要です。 この情報の把握は、/version パラメーターを指定して SqlPackage を実行するステップをパイプラインに追加することで実行できます。 以下に示す例は、Microsoft と GitHub によって管理される環境に基づいており、自己ホスト型の環境では作業ディレクトリのインストール パスが異なっている場合があります。

Azure Pipelines

Azure Pipeline では、script キーワードは SqlPackage のバージョン番号を返します。

- script: SqlPackage /version
  workingDirectory: 'C:\Program Files\Microsoft SQL Server\160\DAC\bin\'
  displayName: 'get sqlpackage version'

GitHub のアクション

GitHub Action ワークフローでは、run キーワードは SqlPackage のバージョン番号を返します。

- name: get sqlpackage version
  working-directory: 'C:\Program Files\Microsoft SQL Server\160\DAC\bin\'
  run: ./SqlPackage /version

ビルド番号 15.0.4897.1 を表示している GitHub アクションの出力表示

パイプライン エージェントでの SqlPackage 診断を取得する

SqlPackage からの診断情報は、コマンド ラインでパラメーター /DiagnosticsFile を使用して取得できます。これは、Azure Pipelines や GitHub Actions などの仮想環境で使用できます。 診断情報は、作業ディレクトリ内のファイルに書き込まれます。 ファイル名は、/DiagnosticsFile パラメーターによって指定されます。

Azure Pipelines

Azure Pipeline の SqlAzureDacpacDeployment 構成の [SqlPackage のその他の引数] フィールドに /DiagnosticsFile パラメーターを追加すると、指定したファイルに SqlPackage 診断情報が書き込まれます。 SqlAzureDacpacDeployment タスクに従って、次の例に示すようにパイプライン成果物を公開することで、仮想環境の外部で診断ファイルを使用できるようになります。

- task: SqlAzureDacpacDeployment@1
  inputs:
    azureSubscription: '$(azuresubscription)'
    AuthenticationType: 'server'
    ServerName: '$(servername)'
    DatabaseName: '$(databasename)'
    SqlUsername: '$(sqlusername)'
    SqlPassword: '$(sqladminpassword)'
    deployType: 'DacpacTask'
    DeploymentAction: 'Publish'
    DacpacFile: '$(Build.Repository.LocalPath)\$(dacpacname).dacpac'
    AdditionalArguments: '/DiagnosticsFile:$(System.DefaultWorkingDirectory)/output.log'
    IpDetectionMethod: 'AutoDetect'

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(System.DefaultWorkingDirectory)/output.log'
    artifact: 'Diagnostic File'
    publishLocation: 'pipeline'

パイプライン実行の後、[公開された成果物] の下にある実行の概要ページから診断ファイルをダウンロードできます。

GitHub のアクション

GitHub アクションの sql-action 構成の "arguments" フィールドに /DiagnosticsFile パラメーターを追加すると、SqlPackage 診断情報が指定されたファイルに書き込まれます。 sql-action タスクに従って、次の例に示すように、成果物を公開することで仮想環境の外部で診断ファイルを使用できるようになります。

- name: Azure SQL Deploy
  uses: Azure/sql-action@v2
  with:
    # The connection string, including authentication information, for the Azure SQL Server database.
    connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
    # Path to DACPAC file to deploy
    path: .\DatabaseProjectAdventureWorksLT\bin\Release\DatabaseProjectAdventureWorksLT.dacpac
    action: publish
    # additional SqlPackage arguments
    arguments: /DiagnosticsFile:DatabaseProjectAdventureWorksLT/DiagnosticLog.log

- uses: actions/upload-artifact@v2
  with:
    name: 'DiagnosticLog.txt'
    path: 'DatabaseProjectAdventureWorksLT/DiagnosticLog.log'

パイプライン エージェント上の SqlPackage を更新する

シナリオによっては、パイプライン環境にインストールされている SqlPackage の現在のバージョンでは不十分な場合があります。 環境を直接変更できない場合は、パイプライン実行の間に追加ステップを使用して新しいバージョンの SqlPackage をインストールすることができます。 パイプラインで DacPac または BacPac の操作を実行する前に、インストール手順を実行することが重要です。 このタスクをバージョンを確認する手順と組み合わせることで、アップグレードが期待とおりに完了したことを確認することができます。

Azure Pipelines

Azure パイプラインで PowerShell タスクが使用される場合は、目的の MSI をダウンロードしてサイレント インストールする手順を Azure パイプラインに追加することができます。

- task: PowerShell@2
  displayName: 'upgrade sqlpackage'
  inputs:
    targetType: 'inline'
    script: |
      # use evergreen or specific dacfx msi link below
      wget -O DacFramework.msi "https://aka.ms/dacfx-msi"
      msiexec.exe /i "DacFramework.msi" /qn

次の手順