Propriedades e parâmetros da ação Import do SqlPackage

  • Artigo

A ação Import do SqlPackage importa o esquema e os dados de tabela de um arquivo BACPAC (.bacpac) para um banco de dado novo ou vazio no SQL Server ou no Banco de Dados SQL do Azure. No momento da operação de importação para um banco de dados existente, o banco de dados de destino não pode conter nenhum objeto de esquema definido pelo usuário. Como alternativa, será possível criar um banco de dados usando uma ação de importação quando um usuário autenticado tem permissões para criar um banco de dados.

Observação

Embora o Microsoft Entra ID seja o novo nome do Azure Active Directory (Azure AD), para evitar a interrupção de ambientes existentes, o Azure AD ainda permanecerá em alguns elementos codificados, como campos de interface do usuário, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Observação

A ação import do SqlPackage tem um melhor desempenho em bancos de dados com menos de 200 GB. Para bancos de dados maiores, o ideal é otimizar a operação usando as propriedades disponíveis neste artigo e as dicas apresentadas em Solução de problemas com o SqlPackage.

Sintaxe da linha de comando

O SqlPackage inicia as ações especificadas usando os parâmetros, as propriedades e as variáveis do sqlcmd especificados na linha de comando.

SqlPackage /Action:Import {parameters} {properties}

Exemplos

# example import to Azure SQL Database using SQL authentication and a connection string
SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Persist Security Info=False;User ID=sqladmin;Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

# example import using short form parameter names
SqlPackage /a:Import /tsn:"{yourserver}.database.windows.net,1433" /tdn:"AdventureWorksLT" /tu:"sqladmin" \
    /tp:"{your_password}" /sf:"C:\AdventureWorksLT.bacpac"

# example import using Microsoft Entra managed identity
SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
    /TargetConnectionString:"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 import connecting using Microsoft Entra username and password
SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
    /TargetConnectionString:"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 import connecting using Microsoft Entra universal authentication
SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" /UniversalAuthentication:True \
    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

# example import 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:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
    /TargetConnectionString:"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:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Parâmetros da ação Import

Parâmetro Forma abreviada Valor Descrição
/AccessToken: /at: {string} Especifica o token de acesso da autenticação com base em token a ser utilizado quando se conectar ao banco de dados de destino.
/Action: /a: Importar Especifica a ação a ser executada.
/AzureCloudConfig: /acc: {string} Especifica os pontos de extremidade personalizados para conectar ao Microsoft Entra ID no formato: AzureActiveDirectoryAuthority={value};DatabaseServicePrincipalName={value}".
/Diagnostics: /d: {True|False} Especifica se o log de diagnósticos é emitido como saída para o console. Usa False como padrão.
/DiagnosticsFile: /df: {string} Especifica um arquivo para armazenar logs de diagnóstico.
/MaxParallelism: /mp: {int} Especifica o grau de paralelismo para operações simultâneas que são executadas em um banco de dados. O valor padrão é 8.
/ModelFilePath: /mfp: {string} Especifica o caminho do arquivo para substituir model.xml no arquivo de origem. O uso dessa configuração pode resultar em falha na implantação e/ou perda de dados indesejada. Essa configuração é destinada somente para o uso durante a solução de problemas com publicação, importação ou geração de script.
/Properties: /p: {PropertyName}={Value} Especifica um par nome-valor para uma propriedade específica da ação; {PropertyName}={Value}.
/Quiet: /q: {True|False} Especifica se os comentários detalhados serão suprimidos. Usa False como padrão.
/SourceFile: /sf: {string} Especifica um arquivo de origem a ser usado como a origem da ação do armazenamento local. Se esse parâmetro for usado, nenhum outro parâmetro de origem deverá ser válido.
/TargetConnectionString: /tcs: {string} Especifica uma cadeia de conexão válida do SQL Server/do Azure para o banco de dados de destino. Se esse parâmetro for especificado, ele deverá ser usado exclusivamente entre todos os outros parâmetros de destino.
/TargetDatabaseName: /tdn: {string} Especifica uma substituição do nome do banco de dados que é o destino da ação do SqlPackage.
/TargetEncryptConnection: /tec: {Optional|Mandatory|Strict|True|False} Especifica se a criptografia SQL deve ser usada para a conexão de banco de dados de destino. O valor padrão é True.
/TargetHostNameInCertificate: /thnic: {string} Especifica o valor usado para validar o certificado TLS/SSL do SQL Server de destino quando a camada de comunicação é criptografada usando TLS.
/TargetPassword: /tp: {string} Para cenários de autenticação do SQL Server, define a senha a ser usada para acessar o banco de dados de destino.
/TargetServerName: /tsn: {string} Define o nome do servidor que hospeda o banco de dados de destino.
/TargetTimeout: /tt: {int} Especifica o tempo limite para estabelecer uma conexão com o banco de dados de destino em segundos. No Microsoft Entra ID, recomendamos que esse valor seja maior ou igual a 30 segundos.
/TargetTrustServerCertificate: /ttsc: {True|False} Especifica se o protocolo TLS será usado para criptografar a conexão de banco de dados de destino e ignorar a verificação da cadeia de certificados para validar a confiança. O valor padrão é Falso.
/TargetUser: /tu: {string} Para cenários de autenticação do SQL Server, define o usuário do SQL Server a ser utilizado para acessar o banco de dados de destino.
/TenantId: /tid: {string} Representa a ID do locatário ou o nome de domínio do Microsoft Entra. Essa opção é necessária para dar suporte a usuários convidados ou importados do Microsoft Entra e a contas Microsoft, como outlook.com, hotmail.com ou live.com. Se esse parâmetro for omitido, a ID de locatário padrão do Microsoft Entra ID será usada, supondo que o usuário autenticado seja um usuário nativo desse AD. No entanto, nesse caso, não há suporte para usuários convidados ou importados e/ou contas da Microsoft hospedadas nesse Microsoft Entra ID, e a operação falhará.
Para saber mais, confira Autenticação universal com o Banco de Dados SQL e Azure Synapse Analytics (suporte do SSMS para MFA).
/ThreadMaxStackSize: /tmss: {int} Especifica o tamanho máximo em megabytes para o thread que executa a ação do SqlPackage. Essa opção só deve ser usada ao encontrar exceções de excedente de pilha que ocorrem durante a análise de instruções Transact-SQL muito grandes.
/UniversalAuthentication: /ua: {True|False} Especifica se a autenticação universal deve ser usada. Quando definido como True, o protocolo de autenticação interativo é ativado para dar suporte a MFA (autenticação multifator). Essa opção também pode ser usada para autenticação do Microsoft Entra sem MFA, usando um protocolo interativo que exige que o usuário digite seu nome de usuário e senha ou autenticação integrada (credenciais do Windows). Quando /UniversalAuthentication está definido como True, nenhuma autenticação do Microsoft Entra pode ser especificada em SourceConnectionString (/scs). Quando /UniversalAuthentication está definido como False, a autenticação do Microsoft Entra deve ser especificada em SourceConnectionString (/scs).
Para saber mais, confira Autenticação universal com o Banco de Dados SQL e Azure Synapse Analytics (suporte do SSMS para MFA).

Propriedades específicas da ação Import

Propriedade Valor Descrição
/p: CommandTimeout=(INT32 '60') Especifica o tempo limite do comando em segundos ao executar consultas com relação ao SQL Server.
/p: DatabaseEdition=({ Basic | Standard | Premium | DataWarehouse | GeneralPurpose | BusinessCritical | Hyperscale | Default } 'Default') Define a edição de um Banco de Dados SQL do Azure. Confira as Camadas de serviço do Banco de Dados SQL do Azure.
/p: DatabaseLockTimeout=(INT32 '60') Especifica o tempo limite de bloqueio do banco de dados em segundos ao executar consultas em SQL Server. Use -1 para esperar indefinidamente.
/p: DatabaseMaximumSize=(INT32 '0') Define o tamanho máximo, em GB, de um Banco de Dados SQL do Azure.
/p: DatabaseServiceObjective=(STRING) Define o nível de desempenho de um Banco de Dados SQL do Azure, assim como "P0" ou "S1".
/p: DisableIndexesForDataPhase=(BOOLEAN 'True') Quando true (padrão), desabilita os índices antes de importar dados. Quando for False, os índices não serão reconstruídos.
/p: DisableParallelismForEnablingIndexes=(BOOLEAN 'False') Não use paralelismo ao reconstruir índices ao importar dados para o SQL Server.
/p: HashObjectNamesInLogs=(BOOLEAN 'False') Especifica se todos os nomes de objetos nos logs devem ser substituídos por um valor de hash aleatório.
/p: ImportContributorArguments=(STRING) Especifica argumentos de colaborador de implantação para os colaboradores de implantação. Essa propriedade deve ser uma lista de valores delimitada por ponto e vírgula.
/p: ImportContributorPaths=(STRING) Especifica caminhos cara carregar outros colaboradores de importação. Essa propriedade deve ser uma lista de valores delimitada por ponto e vírgula.
/p: ImportContributors=(STRING) Especifica que colaboradores da implantação devem ser executados quando o bacpac for importado. Essa propriedade deve ser uma lista de IDs ou nomes de colaborador de compilação totalmente qualificados delimitada por ponto e vírgula.
/p: LongRunningCommandTimeout=(INT32 '0') Especifica o tempo limite do comando de execução prolongada em segundos ao executar consultas com relação ao SQL Server. Use 0 para esperar indefinidamente.
/p: PreserveIdentityLastValues=(BOOLEAN 'False') Especifica se os últimos valores das colunas de identidade devem ser preservados durante a implantação.
/p: RebuildIndexesOfflineForDataPhase=(BOOLEAN 'False') Quando for True, recompilará os índices offline depois de importar os dados para o SQL Server.
/p: Storage=({File|Memory}) Especifica como os elementos são armazenados ao criar o modelo de banco de dados. Por razões de desempenho, o padrão é InMemory. Para bancos de dados grandes, é necessário realizar armazenamento de backup de arquivos.

Próximas etapas