SqlPackage

  • Artigo

O SqlPackage é um utilitário de linha de comando que automatiza as seguintes tarefas de desenvolvimento do banco de dados expondo algumas das APIs públicas da DACFx (Estrutura do Aplicativo da Camada de Dados):

  • Versão: retorna o número de build do aplicativo SqlPackage.

  • Extrair: cria um arquivo (.dacpac) do aplicativo da camada de dados que contém um esquema ou um esquema e os dados do usuário de um banco de dados SQL conectado.

  • Publicar: atualiza um esquema de banco de dados incrementalmente para que corresponda ao esquema de um arquivo .dacpac de origem. Se o banco de dados não existir no servidor, a operação de publicação o criará. Caso contrário, um banco de dados existente é atualizado.

  • Export: exporta um banco de dados SQL conectado, incluindo um esquema do banco de dados e dados do usuário para um arquivo BACPAC (.bacpac).

  • Import: importa os dados do esquema e da tabela de um arquivo BACPAC em um novo banco de dados de usuário.

  • DeployReport: cria um relatório em XML para declarar as alterações que uma ação de publicação realizaria.

  • DriftReport: cria um relatório em XML para declarar as alterações aplicadas a um banco de dados registrado desde o último registro.

  • Script: cria um script de atualização incremental Transact-SQL que atualiza o esquema de um destino para que corresponda ao esquema de origem.

A ferramenta linha de comando SqlPackage permite que você especifique essas ações com propriedades e parâmetros específicos da ação.

Baixe a versão mais recente . Para obter detalhes sobre a versão mais recente, confira as notas sobre a versão.

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.

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 {parameters} {properties} {SQLCMD variables}

Códigos de saída

Os comandos do SqlPackage retornam os seguintes códigos de saída:

  • 0 = êxito
  • diferente de zero = falha

Exemplo de uso

Outros exemplos estão disponíveis nas páginas de ação individuais.

Criando um arquivo .dacpac do esquema de banco de dados atual:

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

Parâmetros

Alguns parâmetros são compartilhados entre as ações SqlPackage. Abaixo é apresentada uma tabela que faz um resumo dos parâmetros. Para obter mais informações, clique nas páginas de ação específicas.

Parâmetro Forma abreviada Extrair Publicar Exportar Importaçãoação DeployReport DriftReport Script
/AccessToken: /at x x x x x x x
/ClientId: /cid x
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x x x x x x x
/DiagnosticsFile: /df x x x x x x x
/MaxParallelism: /mp x x x x x x x
/OutputPath: /op x x x
/OverwriteFiles: /of x x x x x x
/Profile: /pr x x x
/Properties: /p x x x x x x
/Quiet: /q x x x x x x x
/Secret: /secr x
/SourceConnectionString: /scs x x x x x
/SourceDatabaseName: /sdn x x x x x
/SourceEncryptConnection: /sec x x x x x
/SourceFile: /sf x x x x
/SourcePassword: /sp x x x x x
/SourceServerName: /ssn x x x x x
/SourceTimeout: /st x x x x x
/SourceTrustServerCertificate: /stsc x x x x x
/SourceUser: /su x x x x x
/TargetConnectionString: /tcs x x x x
/TargetDatabaseName: /tdn x x x x x
/TargetEncryptConnection: /tec x x x x x
/TargetFile: /tf x x x x
/TargetPassword: /tp x x x x x
/TargetServerName: /tsn x x x x x
/TargetTimeout: /tt x x x x x
/TargetTrustServerCertificate: /ttsc x x x x x
/TargetUser: /tu x x x x x
/TenantId: /tid x x x x x x x
/UniversalAuthentication: /ua x x x x x x x
/Variables: /v x x

Propriedades

As ações do SqlPackage dão suporte a um grande número de propriedades para modificar o comportamento padrão de uma ação. Para obter mais informações, clique nas páginas de ação específicas.

Comandos do utilitário

Versão

Exibe a versão do sqlpackage como um número de build. É possível usar a versão em solicitações interativas e em pipelines automatizados.

SqlPackage /Version

Ajuda

Você pode exibir informações de uso do SqlPackage usando /? ou /help:True.

SqlPackage /?

Para informações de parâmetro e propriedade específicas de uma determinada ação, use o parâmetro de ajuda além do parâmetro dessa ação.

SqlPackage /Action:Publish /?

Autenticação

O SqlPackage é autenticado por meio de métodos disponíveis no SqlClient. A configuração do tipo de autenticação pode ser feita por meio dos parâmetros de cadeia de conexão para cada ação do SqlPackage (/SourceConnectionString e /TargetConnectionString) ou por meio de parâmetros individuais para as propriedades de conexão. Há suporte para os seguintes métodos de autenticação em uma cadeia de conexão:

  • Os logons de autenticação do SQL Server
  • Autenticação do Active Directory (Windows)
  • autenticação do Microsoft Entra
    • Nome de usuário/senha
    • Autenticação integrada
    • Autenticação universal
    • Identidade gerenciada
    • Entidade de serviço

Identidade gerenciada

Observação

O Microsoft Entra ID era conhecido como Azure Active Directory (Azure AD).

Em ambientes automatizados, a identidade gerenciada do Microsoft Entra é o método de autenticação recomendado. Esse método não requer a transferência de credenciais para o SqlPackage no runtime. Quando a identidade gerenciada é configurada para o ambiente em que a ação do SqlPackage é executada, a ação do SqlPackage pode usar essa identidade para efetuar a autenticação no SQL do Azure. Para obter mais informações sobre como configurar uma identidade gerenciada para o seu ambiente, confira a documentação da identidade gerenciada.

Um exemplo de cadeia de conexão que usa a identidade gerenciada atribuída pelo sistema é:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Variáveis de ambiente

Pool de conexões

O pool de conexões pode ser habilitado para todas as conexões feitas pelo SqlPackage definindo a variável de ambiente CONNECTION_POOLING_ENABLED como True. Essa configuração é recomendada para operações com conexões com nomes de usuário e senhas do Microsoft Entra para evitar a limitação pela MSAL (Biblioteca de Autenticação da Microsoft).

Arquivos temporários

Durante as operações do SqlPackage, os dados da tabela são gravados em arquivos temporários antes da compactação ou após a descompactação. Para bancos de dados grandes, esses arquivos temporários podem ocupar uma quantidade significativa de espaço em disco, mas a localização pode ser especificada. As operações de exportação e extração incluem uma propriedade opcional a ser especificada, /p:TempDirectoryForTableData, para substituir o valor padrão do SqlPackage.

A API .NET GetTempPath é usada para efetuar a determinação do valor padrão no SqlPackage.

Para o Windows, as seguintes variáveis de ambiente são verificadas na seguinte ordem e o primeiro caminho que existe é usado:

  1. O caminho especificado pela variável de ambiente TMP.
  2. O caminho especificado pela variável de ambiente TEMP.
  3. O caminho especificado pela variável de ambiente USERPROFILE.
  4. O diretório do Windows.

Para Linux e macOS, se o caminho não for especificado na variável de ambiente TMPDIR, o caminho padrão /tmp/ será usado.

SqlPackage e usuários de banco de dados

Os usuários do banco de dados independente são incluídos em operações do SqlPackage. No entanto, a parte da senha da definição é configurada como uma sequência gerada aleatoriamente pelo SqlPackage, e o valor existente não é transferido. É recomendado que a senha do novo usuário seja restaurada para um valor seguro após a importação de um .bacpac ou a implantação de um .dacpac. Em um ambiente automatizado, os valores de senha podem ser recuperados de um repositório de chaves seguro, como o Azure Key Vault, em uma etapa após o SqlPackage.

Coleta de dados de uso

O SqlPackage contém recursos habilitados para Internet que podem coletar e enviar os dados anônimos de diagnóstico e uso de recursos à Microsoft.

O SqlPackage pode coletar informações padrão do computador, de uso e de desempenho que podem ser transmitidas à Microsoft e analisadas com a finalidade de aprimorar a qualidade, a segurança e a confiabilidade do SqlPackage.

O SqlPackage não coleta informações pessoais ou específicas do usuário. Para ajudar a aproximar um único usuário para fins de diagnóstico, o SqlPackage realiza a geração de um GUID aleatório para cada computador em que é executado e usa esse valor para todos os eventos que envia.

Para obter detalhes, confira a Declaração de privacidade da Microsoft e Suplemento de Privacidade do SQL Server.

Desabilitar relatórios de telemetria

Para desabilitar a coleta e os relatórios de telemetria, atualize a variável de ambiente DACFX_TELEMETRY_OPTOUT para true ou 1.

Suporte

A biblioteca DacFx e a ferramenta da CLI do SqlPackage adotaram a Política de Ciclo de Vida Moderno da Microsoft. Todas as atualizações de segurança, correções e novos recursos são liberados somente na última versão da versão principal. Manter suas instalações do DacFx ou do SqlPackage na versão atual ajuda a garantir que você receba todas as correções de bugs aplicáveis ​​em tempo hábil.

Para obter ajuda com o SqlPackage, enviar solicitações de recursos e relatar problemas, use o repositório do DacFx do GitHub.

Ofertas de SQL com suporte

O SqlPackage e o DacFx oferecem suporte a todas as versões SQL com suporte no momento da liberação do SqlPackage ou do DacFx. Por exemplo, uma liberação do SqlPackage em 14 de janeiro de 2022 oferece suporte a todas as versões com suporte do SQL em 14 de janeiro de 2022. Para saber mais sobre as políticas de suporte do SQL, confira a política de suporte do SQL.

Próximas etapas