SqlPackage 추출 매개 변수 및 속성
SqlPackage 추출 작업은 연결된 데이터베이스의 스키마를 DACPAC 파일(.dacpac)에 만듭니다. 기본적으로 데이터는 .dacpac 파일에 포함되지 않습니다. 데이터를 포함하려면 내보내기 작업을 활용하거나 추출 속성 ExtractAllTableData/TableData를 사용합니다.
참고 항목
Microsoft Entra ID는 Azure AD(Azure Active Directory)의 새 이름이지만, 기존 환경의 중단을 방지하기 위해 UI 필드, 연결 공급자, 오류 코드 및 cmdlet과 같은 일부 하드 코딩된 요소에는 여전히 Azure AD가 남아 있습니다. 이 문서에서는 두 이름을 혼용할 수 있습니다.
명령줄 구문
SqlPackage는 명령줄에 지정된 매개 변수, 속성 및 SQLCMD 변수를 사용하여 지정된 작업을 시작합니다.
SqlPackage /Action:Extract {parameters} {properties}
참고
SQL 인증 사용자와 같은 암호 자격 증명을 사용하는 데이터베이스를 추출하면 암호는 복잡성이 적합한 다른 암호로 바뀝니다. SqlPackage 또는 DacFx 사용자는 dacpac이 게시된 후 암호를 변경해야 합니다.
예
# example extract to create a schema-only .dacpac file connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=false /p:VerifyExtraction=true \
/SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
# example extract to create a .sql file containing the schema definition of the database
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /SourceServerName:{serverFQDN} \
/SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password} /p:ExtractTarget=File
# example extract to create a .dacpac file with data connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=true /p:VerifyExtraction=true \
/SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra managed identity
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Managed Identity;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra username and password
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra universal authentication
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" /UniversalAuthentication:True \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# example extract to create a schema-only .dacpac file connecting using an access token associated with a service principal
$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 /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/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:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
추출 작업 매개 변수
| 매개 변수 | 약식 | 값 | 설명 |
|---|---|---|---|
| /AccessToken: | /at: | {string} | 대상 데이터베이스에 연결할 때 사용할 액세스 토큰 기반 인증 액세스 토큰을 지정합니다. |
| /Action: | /a: | Extract | 수행할 작업을 지정합니다. |
| /AzureCloudConfig: | /acc: | {string} | Microsoft Entra ID에 연결하는 데 필요한 사용자 지정 엔드포인트를 AzureActiveDirectoryAuthority={value};DatabaseServicePrincipalName={value}" 형식으로 지정합니다. |
| /Diagnostics: | /d: | {True|False} | 진단 로깅이 콘솔로 출력되는지 여부를 지정합니다. 기본값은 False입니다. |
| /DiagnosticsFile: | /df: | {string} | 진단 로그를 저장할 파일을 지정합니다. |
| /DiagnosticsLevel: | /dl | {None|Off|Critical|오류|경고|정보|자세한 정보} | 필터링된 진단 파일의 추적 메시지 수준을 지정합니다. |
| /MaxParallelism: | /mp: | {int} | 데이터베이스에 대해 실행 중인 동시 작업에 대한 병렬 처리 수준을 지정합니다. 기본값은 8입니다. |
| /OverwriteFiles: | /of: | {True|False} | SqlPackage가 기존 파일을 덮어써야 할지 여부를 지정합니다. False를 지정하면 기존 파일이 나타나는 경우 SqlPackage에서 작업이 중단됩니다. 기본값은 True입니다. |
| /Properties: | /p: | {PropertyName}={Value} | 작업별 속성에 대한 이름 값 쌍을 지정합니다. {PropertyName}={Value}. |
| /Quiet: | /q: | {True|False} | 자세한 피드백을 무시할지 여부를 지정합니다. 기본값은 False입니다. |
| /SourceConnectionString: | /scs: | {string} | 원본 데이터베이스에 대한 유효한 SQL Server/Azure 연결 문자열을 지정합니다. 이 매개 변수를 지정한 경우 다른 모든 원본 매개 변수와 단독으로 연결 문자열이 사용됩니다. |
| /SourceDatabaseName: | /sdn: | {string} | 원본 데이터베이스의 이름을 정의합니다. |
| /SourceEncryptConnection: | /sec: | {Optional|Mandatory|Strict|True|False} | 원본 데이터베이스 연결에 대해 SQL 암호화를 사용할지 여부를 지정합니다. 기본값은 True입니다. |
| /SourceHostNameInCertificate: | /shnic: | {string} | TLS를 사용하여 통신 계층을 암호화할 때 원본 SQL Server TLS/SSL 인증서의 유효성을 검사하는 데 사용되는 값을 지정합니다. |
| /SourcePassword: | /sp: | {string} | SQL Server 인증 시나리오에서 원본 데이터베이스에 액세스하는 데 사용할 암호를 정의합니다. |
| /SourceServerName: | /ssn: | {string} | 원본 데이터베이스를 호스팅하는 서버의 이름을 정의합니다. |
| /SourceTimeout: | /st: | {int} | 원본 데이터베이스에 대한 연결을 설정하는 데 대한 제한 시간(초)을 지정합니다. |
| /SourceTrustServerCertificate: | /stsc: | {True|False} | 원본 데이터베이스 연결을 암호화하고 신뢰의 유효성을 검증하기 위한 인증서 체인 검색을 건너뛰는 데 TLS를 사용할지 여부를 지정합니다. 기본값은 False입니다. |
| /SourceUser: | /su: | {string} | SQL Server 인증 시나리오에서 원본 데이터베이스에 액세스하는 데 사용할 SQL Server 사용자를 정의합니다. |
| /TargetFile: | /tf: | {string} | 데이터베이스 대신 작업 대상으로 사용될 로컬 스토리지의 대상 파일(.dacpac 파일)을 지정합니다. 이 매개 변수를 사용하는 경우 다른 대상 매개 변수가 무효화됩니다. 이 매개 변수는 데이터베이스 대상만 지원하는 동작에는 유효하지 않습니다. |
| /TenantId: | /tid: | {string} | Microsoft Entra 테넌트 ID 또는 도메인 이름을 나타냅니다. 이 옵션은 outlook.com, hotmail.com 또는 live.com과 같은 Microsoft 계정뿐만 아니라 게스트 또는 가져온 Microsoft Entra 사용자를 지원해야 합니다. 이 매개 변수를 생략하면 인증된 사용자가 이 테넌트의 기본 사용자라고 가정하여 Microsoft Entra ID의 기본 테넌트 ID가 사용됩니다. 그러나 이 경우 이 Microsoft Entra ID에서 호스트되는 모든 게스트 또는 가져온 사용자 및/또는 Microsoft 계정은 지원되지 않으며 작업이 실패합니다. 자세한 내용은 SQL Database 및 Azure Synapse Analytics를 사용하여 유니버설 인증(MFA에 대한 SSMS 지원)을 참조하세요. |
| /ThreadMaxStackSize: | /tmss: | {int} | SqlPackage 작업을 실행하는 스레드의 최대 크기(MB)를 지정합니다. 이 옵션은 매우 큰 Transact-SQL 문을 구문 분석할 때 발생하는 스택 오버플로 예외가 발생하는 경우에만 사용해야 합니다. |
| /UniversalAuthentication: | /ua: | {True|False} | 유니버설 인증을 사용해야 하는지 여부를 지정합니다. True로 설정되면 대화형 인증 프로토콜이 MFA를 지원하도록 활성화됩니다. 이 옵션은 사용자가 사용자 이름 및 암호 또는 통합 인증(Windows 자격 증명)을 입력해야 하는 대화형 프로토콜을 사용하여 MFA가 없는 Microsoft Entra 인증에도 사용할 수 있습니다. /UniversalAuthentication을 True로 설정하면 SourceConnectionString(/scs)에 Microsoft Entra 인증을 지정할 수 없습니다. /UniversalAuthentication을 False로 설정하면 SourceConnectionString(/scs)에 Microsoft Entra 인증을 지정해야 합니다. 자세한 내용은 SQL Database 및 Azure Synapse Analytics를 사용하여 유니버설 인증(MFA에 대한 SSMS 지원)을 참조하세요. |
Extract 동작과 관련된 속성
| 속성 | 값 | Description |
|---|---|---|
| /p: | AzureSharedAccessSignatureToken=(STRING) | Azure SAS(공유 액세스 서명) 토큰입니다. Parquet 파일의 데이터가 포함된 Azure Synapse Analytics 및 SqlPackage용 SqlPackage를 참조하세요. |
| /p: | AzureStorageBlobEndpoint=(STRING) | Azure Blob Storage 엔드포인트. Parquet 파일의 데이터가 포함된 Azure Synapse Analytics 및 SqlPackage용 SqlPackage를 참조하세요. |
| /p: | AzureStorageContainer=(STRING) | Azure Blob Storage 컨테이너. Parquet 파일의 데이터가 포함된 Azure Synapse Analytics 및 SqlPackage용 SqlPackage를 참조하세요. |
| /p: | AzureStorageKey=(STRING) | Azure 스토리지 계정 키. Parquet 파일의 데이터가 포함된 Azure Synapse Analytics 및 SqlPackage용 SqlPackage를 참조하세요. |
| /p: | AzureStorageRootPath=(STRING) | 컨테이너 내의 스토리지 루트 경로입니다. 이 속성이 없으면 경로는 기본적으로 servername/databasename/timestamp/로 설정됩니다. Parquet 파일의 데이터가 포함된 Azure Synapse Analytics 및 SqlPackage용 SqlPackage를 참조하세요. |
| /p: | CommandTimeout=(INT32 '60') | SQL Server에 대한 쿼리를 실행할 때 명령 시간 제한(초)을 지정합니다. |
| /p: | CompressionOption=({Normal|Maximum|Fast|SuperFast|NotCompressed} 'Normal') | 압축 형식을 지정합니다. |
| /p: | DacApplicationDescription=(STRING) | DACPAC 메타데이터에 저장할 애플리케이션 설명을 정의합니다. |
| /p: | DacApplicationName=(STRING) | DACPAC 메타데이터에 저장할 애플리케이션 이름을 정의했습니다. 기본값은 데이터베이스 이름입니다. |
| /p: | DacMajorVersion=(INT32 '1') | DACPAC 메타데이터에 저장할 주 버전을 정의합니다. |
| /p: | DacMinorVersion=(INT32 '0') | DACPAC 메타데이터에 저장할 부 버전을 정의합니다. |
| /p: | DatabaseLockTimeout=(INT32 '60') | SQLServer에 대해 쿼리를 실행할 때의 데이터베이스 잠금 시간 제한(초)를 지정합니다. 무기한 대기하려면 -1을 사용합니다. |
| /p: | ExtractAllTableData=(BOOLEAN 'False') | 모든 사용자 테이블의 데이터를 추출하는지 여부를 나타냅니다. 'true'인 경우 모든 사용자 테이블의 데이터가 추출되며 데이터 추출을 위해 개별 사용자 테이블을 지정할 수 없습니다. 'false'인 경우 데이터를 추출할 하나 이상의 사용자 테이블을 지정합니다. |
| /p: | ExtractApplicationScopedObjectsOnly=(BOOLEAN 'True') | True인 경우 지정된 원본에 대해 애플리케이션 범위 개체만 추출합니다. False인 경우 지정된 원본에 대해 모든 개체를 추출합니다. |
| /p: | ExtractReferencedServerScopedElements=(BOOLEAN 'True') | True인 경우 원본 데이터베이스 개체에서 참조하는 로그인, 서버 감사 및 자격 증명 개체를 추출합니다. |
| /p: | ExtractTarget=({DacPac|File|Flat|ObjectType|Schema|SchemaObjectType} 'DacPac') | 데이터베이스 스키마의 대체 출력 형식을 지정합니다. 기본값은 .dacpac 단일 파일을 출력하는 'DacPac'입니다. 추가 옵션은 'SchemaObjectType'(각 스키마 및 개체 형식의 폴더에 있는 파일), 'Schema'(각 스키마의 폴더에 있는 파일), 'ObjectType'(각 개체 형식의 폴더에 있는 파일), 'Flat'(동일한 폴더에 있는 모든 파일) 또는 'File'(단일 파일 1개)로 구성된 하나 이상의 .sql 파일을 출력합니다. |
| /p: | ExtractUsageProperties=(BOOLEAN 'False') | 테이블 행 개수, 인덱스 크기를 비롯한 사용 속성을 데이터베이스에서 추출할지를 지정합니다. |
| /p: | HashObjectNamesInLogs=(BOOLEAN 'False') | 로그의 모든 개체 이름을 임의의 해시 값으로 바꿀지 여부를 지정합니다. |
| /p: | IgnoreExtendedProperties=(BOOLEAN 'False') | 확장된 속성을 무시할지 여부를 지정합니다. |
| /p: | IgnorePermissions=(BOOLEAN 'True') | 권한을 무시할지 여부를 지정합니다. |
| /p: | IgnoreUserLoginMappings=(BOOLEAN 'False') | 사용자와 로그인 간의 관계를 무시할지 여부를 지정합니다. |
| /p: | LongRunningCommandTimeout=(INT32 '0') | SQL Server에 대한 쿼리를 실행할 때 장기 명령 시간 제한(초)을 지정합니다. 무기한 대기하려면 0을 사용합니다. |
| /p: | Storage=({File|Memory}) | 추출 중에 사용되는 스키마 모델에 대한 지원 스토리지 유형을 지정합니다. 'Memory'는 SqlPackage의 .NET Core 버전에 대한 기본값입니다. 'File'은 SqlPackage의 .NET Framework 버전에 대해서만 사용할 수 있으며, 기본값입니다. |
| /p: | TableData=(STRING) | 데이터를 추출할 테이블을 나타냅니다. schema_name.table_identifier 형식에서 이름 부분이 괄호로 묶이거나 묶이지 않은 형태로 테이블 이름을 지정하십시오. 이 속성은 여러 옵션을 나타내기 위해 여러 번 지정할 수 있습니다. 추출된 데이터와 Parquet 파일에 모두 .dacpac 적용됩니다. |
| /p: | TempDirectoryForTableData=(STRING) | 패키지 파일에 기록되기 전에 테이블 데이터를 버퍼링하는 데 사용되는 임시 디렉터리를 지정합니다. |
| /p: | VerifyExtraction=(BOOLEAN 'False') | 추출된 스키마 모델을 확인할지 여부를 지정합니다. |
다음 단계
- SqlPackage에 대해 자세히 알아봅니다.
- SqlPackage 문제 해결