SqlPackage를 사용하여 문제 및 성능 문제 해결

  • 아티클

일부 시나리오에서는 SqlPackage 작업이 예상보다 오래 걸리거나 완료하지 못합니다. 이 문서에서는 이러한 작업의 성능 문제를 해결하거나 개선하기 위해 자주 제안되는 몇 가지 전술에 대해 설명합니다. 사용 가능한 매개 변수 및 속성을 이해하기 위해 각 작업에 대한 특정 설명서 페이지를 읽는 것이 권장되며 이 문서는 SqlPackage 작업을 조사하는 시작점으로 사용됩니다.

전체 전략

일반적으로 SqlPackage의 .NET Core 버전을 통해 더 나은 성능을 얻을 수 있습니다.

  1. 운영 체제(Windows, macOS 또는 Linux)용 .NET Core에서 SqlPackage에 대한 zip을 다운로드합니다.
  2. 다운로드 페이지에서 지시하는 대로 보관 파일의 압축을 해제합니다.
  3. 명령 프롬프트를 열고 디렉터리(cd)를 SqlPackage 폴더로 변경합니다.

성능 향상 및 버그 수정이 정기적으로 릴리스되므로 사용 가능한 최신 버전의 SqlPackage를 사용하는 것이 중요합니다.

가져오기/내보내기 서비스에 대한 대체 SqlPackage

가져오기/내보내기 서비스를 사용하여 데이터베이스를 가져오거나 내보내려고 시도한 경우 SqlPackage를 사용하여 선택적 매개 변수 및 속성에 대한 더 많은 제어를 통해 동일한 작업을 수행할 수 있습니다.

가져오기의 경우 예제 명령은 다음과 같습니다.

./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>

내보내기의 경우 예제 명령은 다음과 같습니다.

./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>

사용자 이름 및 비밀번호 대신 다단계 인증을 사용하여 다단계 인증을 통해 Microsoft Entra 인증(기존의 Azure Active Directory)을 통해 인증할 수 있습니다. 사용자 이름 및 암호 매개 변수를 /ua:true 및 /tid:"yourdomain.onmicrosoft.com"으로 대체할 수 있습니다.

일반적인 문제

시간 제한 오류

시간 제한과 관련된 문제의 경우 다음 속성을 사용하여 SqlPackage와 SQL 인스턴스 간의 연결을 조정할 수 있습니다.

  • /p:CommandTimeout=: 쿼리가 실행될 때 명령 시간 제한(초)을 지정합니다. 기본값: 60
  • /p:DatabaseLockTimeout=: 데이터베이스 잠금 시간 제한(초)을 지정합니다. -1은 무기한 대기하는 데 사용할 수 있습니다(기본값: 60)
  • /p:LongRunningCommandTimeout=: 장기 실행 명령 시간 제한(초)을 지정합니다. 기본값 0은 무기한 대기하는 데 사용됩니다.

클라이언트 리소스 사용량

내보내기 및 추출 명령의 경우 테이블 데이터는 bacpac/dacpac 파일에 기록되기 전에 버퍼링하기 위해 임시 디렉터리에 전달됩니다. 이 스토리지 요구 사항은 클 수 있으며 내보낼 데이터의 전체 크기에 상대적입니다. /p:TempDirectoryForTableData=<path> 속성을 사용하여 대체 임시 디렉터리를 지정합니다.

스키마 모델은 메모리에서 컴파일되므로 큰 데이터베이스 스키마의 경우 SqlPackage를 실행하는 클라이언트 컴퓨터의 메모리 요구 사항이 중요할 수 있습니다.

낮은 서버 리소스 사용량

기본적으로 SqlPackage는 최대 서버 병렬 처리를 8로 설정합니다. 서버 리소스 사용량이 작은 경우 MaxParallelism 매개 변수 값을 늘리면 성능이 향상될 수 있습니다.

액세스 토큰

/AccessToken: 또는 /at: 매개 변수를 사용하면 SqlPackage에 대한 토큰 기반 인증을 사용할 수 있지만, 토큰을 명령에 전달하기가 어려울 수 있습니다. PowerShell에서 액세스 토큰 개체를 구문 분석하는 경우, 문자열 값을 명시적으로 전달하거나 토큰 속성에 대한 참조를 $() 안에 넣습니다. 예시:

$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken
# OR
SqlPackage /at:$($AccessToken_Object.Token)

연결

SqlPackage가 연결에 실패하는 경우 서버에서 암호화를 사용하도록 설정하지 않았거나 구성된 인증서가 신뢰할 수 있는 인증 기관(예: 자체 서명된 인증서)에서 발급되지 않을 수 있습니다. 암호화 없이 연결하거나 서버 인증서를 신뢰하도록 SqlPackage 명령을 변경할 수 있습니다. 가장 좋은 방법은 서버에 대한 신뢰할 수 있는 암호화된 연결을 설정할 수 있도록 하는 것입니다.

  • 암호화 없이 연결: /SourceEncryptConnection=False 또는 /TargetEncryptConnection=False
  • 트러스트 서버 인증서: /SourceTrustServerCertificate=True 또는 /TargetTrustServerCertificate=True

SQL 인스턴스에 연결할 때 다음 경고 메시지가 표시되어 명령줄 매개 변수가 서버에 연결하기 위해 변경이 필요할 수 있음을 나타냅니다.

The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
The connection string provided contains encryption settings which may lead to connection failure if the server is not properly configured.

SqlPackage의 연결 보안 변경에 대한 자세한 내용은 SqlPackage 161 연결 보안 개선에서 확인할 수 있습니다.

제약 조건에 대한 가져오기 작업 오류 2714

가져오기 작업을 수행할 때 개체가 이미 있는 경우 오류 2714가 표시될 수 있습니다.

*** Error importing database:Could not import package.
Error SQL72014: Core Microsoft SqlClient Data Provider: Msg 2714, Level 16, State 5, Line 1 There is already an object named 'DF_Department_ModifiedDate_0FF0B724' in the database.
Error SQL72045: Script execution error.  The executed script:
ALTER TABLE [HumanResources].[Department]
    ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];

이 오류를 해결하는 원인과 해결 방법은 다음과 같습니다.

  1. 가져오는 대상이 빈 데이터베이스인지 확인합니다.
  2. 데이터베이스에 기본값 특성을 사용하는 제약 조건(SQL Server가 제약 조건에 임의 이름을 할당하는 경우)과 명시적으로 명명된 제약 조건이 있는 경우 동일한 이름의 제약 조건이 두 번 생성될 수 있습니다. 명시적으로 명명된 모든 제약 조건(기본값 사용 안 됨) 또는 모든 시스템 정의 이름(기본값 사용)을 사용해야 합니다.
  3. 수동으로 model.xml을 편집하고 오류가 발생한 이름을 고유한 이름으로 바꾸어 제약 조건의 이름을 바꿉니다. 이 옵션은 Microsoft 지원에서 지시하고 .bacpac 손상의 위험을 초래하는 경우에만 수행해야 합니다.

진단

로그는 문제 해결에 필수적입니다. /DiagnosticsFile:<filename> 매개 변수를 사용하여 진단 로그를 파일에 캡처합니다.

SqlPackage를 실행하기 전에 환경 변수 DACFX_PERF_TRACE=true를 설정하여 추가적인 성능 관련 추적 데이터를 로그할 수 있습니다. PowerShell에서 이 환경 변수를 설정하려면 다음 명령을 사용합니다.

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

가져오기 작업 팁

대용량 테이블 또는 많은 인덱스가 있는 테이블을 포함하는 가져오기의 경우 /p:RebuildIndexesOfflineForDataPhase=True 또는 /p:DisableIndexesForDataPhase=False를 사용하면 성능이 향상될 수 있습니다. 이러한 속성은 인덱스 다시 빌드 작업이 오프라인으로 발생하거나 발생하지 않도록 각각 수정합니다. 이러한 속성 및 기타 속성을 사용하여 SqlPackage 가져오기 작업을 조정할 수 있습니다.

내보내기 작업 팁

내보내기 중 성능 저하의 일반적인 원인은 확인되지 않은 개체 참조이며, 이로 인해 SqlPackage가 개체를 여러 번 확인하려고 시도합니다. 예를 들어 테이블을 참조하는 뷰가 정의되고 테이블이 데이터베이스에 더 이상 존재하지 않습니다. 해결되지 않은 참조가 내보내기 로그에 표시되는 경우 데이터베이스의 스키마를 수정하여 내보내기 성능을 향상시키는 것이 좋습니다.

내보내기 중에 OS 디스크 공간이 제한되고 부족해지는 시나리오에서는 /p:TempDirectoryForTableData를 사용하여 내보낼 데이터가 대체 디스크에서 버퍼링될 수 있습니다. 이 작업에 필요한 공간은 클 수 있으며 전체 데이터베이스 크기를 기준으로 합니다. 이러한 속성 및 기타 속성을 사용하여 SqlPackage 내보내기 작업을 조정할 수 있습니다.

내보내기 프로세스 중에 테이블 데이터는 bacpac 파일에서 압축됩니다. Fast, SuperFast 또는 NotCompressed로 설정된 /p:CompressionOption을 사용하면 출력 bacpac 파일을 덜 압축하면서 내보내기 프로세스 속도를 향상시킬 수 있습니다.

스키마 유효성 검사를 건너뛰면서 데이터베이스 스키마 및 데이터를 가져오려면 /p:VerifyExtraction=False 속성을 사용하여 내보내기를 수행합니다.

Azure SQL Database

다음 팁은 Azure VM(가상 머신)에서 Azure SQL Database에 대해 가져오기 또는 내보내기를 실행하는 데만 적용됩니다.

  • 최상의 성능을 위해 중요 비즈니스용 또는 프리미엄 계층 데이터베이스를 사용합니다.
  • VM에서 SSD 스토리지를 사용하고 bacpac의 압축을 풀 충분한 공간이 있는지 확인합니다.
  • 데이터베이스와 동일한 지역의 VM에서 SqlPackage를 실행합니다.
  • 가속화된 네트워킹을 VM에 사용하도록 설정합니다.

PowerShell 스크립트를 활용하여 가져오기 작업에 대한 자세한 내용은 진행 중 얻은 개선 사항 #211: SQLPackage 가져오기 프로세스 모니터링을 참조하세요.

관련 콘텐츠