다음을 통해 공유

개발 파이프라인의 SqlPackage

SqlPackage는 여러 데이터베이스 개발 작업을 자동화하고 CI/CD 파이프라인에 통합할 수 있는 명령줄 유틸리티입니다.

참고 항목

파이프라인 자동화를 위해서는 SQL Server Management Studio 또는 Visual Studio를 비롯한 다른 애플리케이션과 번들로 제공되는 SqlPackage 실행 파일보다 SqlPackage의 독립 실행형 설치를 활용하는 것이 권장됩니다. SqlPackage의 독립 실행형 설치는 더 자주 업데이트되며 다른 애플리케이션의 릴리스 주기와 연결되지 않습니다.

SqlPackage가 전역 dotnet 도구로 설치되어 있는 경우(권장) 모든 디렉터리에서 간단히 sqlpackage 파이프라인에서 호출할 수 있습니다. SqlPackage가 독립 실행형 실행 파일로 설치된 경우 파이프라인에서 실행 파일의 전체 경로를 지정해야 합니다. Windows에서 SqlPackage의 독립 실행형 설치는 경로 C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi)에서 사용할 수 있습니다. Windows 및 Linux 환경 모두에서 .NET용 자체 포함 .zip SqlPackage를 다운로드하는 경우 실행 파일을 선택한 위치로 추출할 수 있습니다.

관리되는 가상 환경

GitHub Actions 호스트된 실행기 및 Azure Pipelines 가상 머신 이미지에 사용되는 가상 환경은 실행기 이미지 GitHub 리포지토리에서 관리됩니다. SqlPackage는 여러 windows-latest 및 ubuntu-22.04 환경에 포함되지만 더 이상 기본적으로 ubuntu-24.04 및 ubuntu-latest에 포함되지 않습니다. 실행기 이미지에 있는 이미지의 업데이트는 SqlPackage가 릴리스될 때마다 몇 주 이내에 수행됩니다.

관리되는 가상 환경에서는 파이프라인의 런타임에 SqlPackage를 설치합니다. 설치는 Azure Pipelines 및 GitHub Actions에서 별도의 단계로 수행되며 설치가 진행되는 동안 각 파이프라인 실행에 짧은 지연을 추가합니다. 런타임에 SqlPackage를 설치하려면 dotnet CLI를 사용하여 SqlPackage를 전역 도구로 설치하는 단계를 파이프라인에 추가합니다. 이 단계는 파이프라인의 SqlPackage 작업 전에 실행해야 합니다.

dotnet tool install --global Microsoft.SqlPackage

SqlPackage를 설치하기 전에 파이프라인에서 .NET 설치 단계를 수행해야 할 수 있습니다. .NET을 찾을 수 없다는 오류 메시지가 표시됩니다. 통합 작업을 사용하여 Azure Pipelines의 UseDotNet 작업 또는 GitHub Actions의 설치-dotnet 작업과 같은 작업을 구성합니다.

필요에 따라 설치 명령에 추가하여 설치할 SqlPackage 버전을 지정하거나 플래그를 --version <version> 사용하여 --prerelease 미리 보기 버전을 설치할 수 있습니다.

예: Azure DevOps Pipelines에 SqlPackage를 설치하는 단계

Azure DevOps Pipelines에서 UseDotNet 작업을 사용하여 .NET SDK를 설치한 다음 SqlPackage를 전역 도구로 설치할 수 있습니다. Microsoft에서 제공하는 Windows 에이전트를 사용하는 경우 SqlPackage가 이미 설치되어 있습니다 C:\Program Files\Microsoft SQL Server\170\DAC\bin. 자체 호스팅 에이전트를 사용하는 경우 호스트 환경에 SqlPackage를 설치하고 파이프라인에서 이 단계를 건너뛸 수도 있습니다.

- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '8.x'
- script: dotnet tool install --global Microsoft.SqlPackage --version <version>
  displayName: 'Install specific version of SqlPackage'

예: GitHub Actions에 SqlPackage를 설치하는 단계

GitHub Actions에서 설치-dotnet 작업을 사용하여 .NET SDK를 설치한 다음 SqlPackage를 전역 도구로 설치할 수 있습니다. GitHub에서 제공하는 Windows Runner를 사용하는 경우 SqlPackage가 이미 설치되어 있습니다 C:\Program Files\Microsoft SQL Server\170\DAC\bin. 자체 호스팅 실행기를 사용하는 경우 호스트 환경에 SqlPackage를 설치하고 워크플로에서 이 단계를 건너뛸 수도 있습니다.

- name: Setup .NET
  uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '8.x'
- name: Install SqlPackage
  run: dotnet tool install --global Microsoft.SqlPackage --version <version>

SqlPackage 버전 확인

문제 해결 활동 시 사용 중인 SqlPackage 버전을 알아야 합니다. /version 매개 변수로 SqlPackage를 실행하는 단계를 파이프라인에 추가하면 이 정보를 캡처할 수 있습니다. 이 문서에서는 Azure DevOps 및 GitHub 관리 환경을 기반으로 하는 예제를 제공하며, 자체 호스팅 환경에는 작업 디렉터리에 대한 다른 설치 경로가 있을 수 있습니다.

Azure Pipelines (애저 파이프라인스)

Azure Pipeline에서 스크립트 키워드는 SqlPackage 버전 번호를 반환합니다.

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

GitHub Actions (GitHub 액션)

GitHub Action 워크플로에서 실행 키워드는 SqlPackage 버전 번호를 반환합니다.

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

빌드 번호 15.0.4897.1을 표시하는 GitHub 작업 출력

파이프라인 에이전트에서 SqlPackage 업데이트

일부 시나리오에서는 파이프라인 환경에 설치된 SqlPackage의 현재 버전이 충분하지 않을 수 있습니다. 환경을 직접 수정할 수 없는 경우 파이프라인을 실행하는 동안 추가 단계를 사용하여 최신 버전의 SqlPackage를 설치할 수 있습니다. 파이프라인에서 DacPac 또는 BacPac 작업을 실행하기 전에 설치 단계를 실행하는 것이 중요합니다. 버전 확인 단계와 함께 이 작업을 사용하면 업그레이드가 정상적으로 완료되었는지 확인할 수 있습니다.

Azure Pipelines, Windows 기반 에이전트

Azure Pipeline에서 PowerShell 작업을 사용하는 경우 원하는 DacFx 설치 관리자를 다운로드하고 자동으로 설치하는 단계를 Azure Pipeline에 추가할 수 있습니다.

- 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

GitHub Actions, Linux 기반 러너

GitHub Action 워크플로에서 실행 키워드를 사용하여 SqlPackage를 설치, 제거 또는 업데이트하는 명령을 실행할 dotnet tool 수 있습니다. 다음 예제에서는 SqlPackage를 최신 미리 보기 버전으로 업데이트하는 방법을 보여줍니다.

- name: Update SqlPackage
  run: dotnet tool update --global Microsoft.SqlPackage --prerelease

자체 호스팅 가상 환경

자체 호스팅 Azure DevOps 에이전트 또는 GitHub Actions 실행기 같은 자체 호스팅 가상 환경에서 관리되는 가상 환경에 설명된 대로 호스트 환경에 SqlPackage를 설치하거나 런타임에 SqlPackage를 설치할 수 있습니다. 호스트 환경에 SqlPackage를 설치하는 경우 해당 호스트에서 실행되는 파이프라인은 런타임에 SqlPackage를 설치할 필요가 없으므로 파이프라인 실행 속도를 높일 수 있습니다. SqlPackage가 호스트에 설치된 경우 SqlPackage 를 정기적으로 업데이트하여 최신 버전으로 환경을 유지 관리해야 합니다.

Azure Container Apps 작업은 각 워크플로 호출에 필요에 따라 배포되는 컨테이너에 자체 호스팅 실행기를 배포하는 데 사용할 수 있습니다. Container Apps 작업을 사용하면 Dockerfile에 정의된 대로 환경을 제어하고 필요에 따라 SqlPackage 및 기타 도구를 설치합니다. 자체 호스팅 실행기는 컨테이너 이미지에 설치 단계를 포함하여 특정 버전의 SqlPackage에서 실행되도록 구성할 수 있습니다. 예를 들어, 이 자습서에는 curl과 jq을 설치하는 Dockerfile이 포함되어 있습니다.

.NET 8.0 및 SqlPackage를 설치하는 컨테이너 이미지를 생성하도록 이 예제를 수정할 수 있습니다.

FROM ghcr.io/actions/actions-runner:2.323.0

USER root

# install dotnet sdk and sqlpackage
RUN apt-get update && apt-get install -y dotnet-sdk-8.0 && \
    dotnet tool install --tool-path /usr/local/bin/ Microsoft.SqlPackage

COPY entrypoint.sh ./entrypoint.sh
RUN chmod +x ./entrypoint.sh

USER runner

ENTRYPOINT ["./entrypoint.sh"]

배포 현황 추적

SqlPackage와 관련된 일부 파일을 캡처하여 파이프라인을 재현하고 배포 추적을 개선할 수 있습니다. 구현 및 사용 사례는 특정 아키텍처 및 자동화 환경에 따라 달라집니다.

파이프라인 에이전트에서 SqlPackage 진단 가져오기

SqlPackage의 진단 정보는 명령줄에서 /DiagnosticsFile 매개 변수를 통해 사용할 수 있습니다. 이 매개 변수는 Azure Pipelines 및 GitHub Actions와 같은 가상 환경에서 사용할 수 있습니다. 진단 정보는 작업 디렉터리의 파일에 기록됩니다. 파일 이름은 /DiagnosticsFile 매개 변수에 의해 결정됩니다.

Azure Pipelines (애저 파이프라인스)

/DiagnosticsFile Azure Pipeline SqlAzureDacpacDeployment 구성의 "추가 SqlPackage 인수" 필드에 매개 변수를 추가하면 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 Actions (GitHub 액션)

/DiagnosticsFile GitHub Action sql-action 구성의 "인수" 필드에 매개 변수를 추가하면 SqlPackage 진단 정보가 지정된 파일에 기록됩니다. SQL 작업 태스크에 따라 다음 예제와 같이 아티팩트를 게시하여 가상 환경 외부에서 진단 파일을 사용할 수 있습니다.

- 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'

관련 콘텐츠