SqlPackage

  • Artigo

O SqlPackage é um utilitário de linha de comando que automatiza as tarefas de desenvolvimento de banco de dados, expondo algumas das APIs públicas do Estrutura do Aplicativo da Camada de Dados (DacFx). Os principais casos de uso do SqlPackage se concentram na portabilidade e nas implantações de banco de dados para a família de bancos de dados SQL Server, SQL do Azure e Azure Synapse Analytics. O SqlPackage pode ser automatizado usando Azure Pipelines e GitHub Actions ou outras ferramentas de CI/CD.

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.

Portabilidade

A portabilidade de banco de dados é a capacidade de mover um esquema de banco de dados e os dados entre diferentes instâncias do SQL Server, do SQL do Azure e do Azure Synapse Analytics. Exportar um banco de dados do Banco de Dados SQL do Azure para uma instância local do SQL Server ou do SQL Server para o Banco de Dados SQL do Azure são exemplos de portabilidade de banco de dados. O SqlPackage oferece suporte à portabilidade do banco de dados por meio das ações Exportar e Importar, que criam e consomem arquivos BACPAC. O SqlPackage também oferece suporte à portabilidade do banco de dados por meio das ações Extrair e Publicar, que criam e consomem arquivos DACPAC que podem conter os dados diretamente ou fazer referência aos dados armazenados no Armazenamento de Blobs do Azure.

  • 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.

Implantações

As implantações de banco de dados são o processo de atualizar um esquema de banco de dados para corresponder a um estado desejado, como adicionar colunas a uma tabela ou alterar o conteúdo de um procedimento armazenado. O SqlPackage oferece suporte a implantações de banco de dados por meio das ações Publicar e Extrair. A ação Publicar atualiza um esquema de banco de dados para corresponder ao conteúdo de um arquivo .dacpac de origem, enquanto a ação Extrair cria um arquivo de aplicativo da camada de dados (.dacpac) contendo o esquema ou esquema e os dados do usuário de um banco de dados SQL conectado. O SqlPackage permite implantações em bancos de dados novos ou existentes do mesmo artefato (.dacpac) criando automaticamente um plano de implantação que aplicará as alterações necessárias ao banco de dados de destino. O plano de implantação pode ser revisado antes de aplicar as alterações ao banco de dados de destino com as ações Script ou DeployReport.

  • 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.

  • 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.

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}

Mais informações sobre a sintaxe de linha de comando do SqlPackage são detalhadas nas páginas da referência da CLI do SqlPackage e ações individuais.

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 passagem de credenciais para SqlPackage em tempo de execução, pois o SqlPackage usa identidades gerenciadas para se conectar a bancos de dados que oferecem suporte à autenticação do Microsoft Entra e para obter tokens do Microsoft Entra sem o gerenciamento de credenciais. 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;

As identidades gerenciadas são compatíveis com os pipelines de CI/CD do Azure DevOps e do GitHub Actions.

Entidade de serviço

Observação

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

As entidades de serviço do serviço de aplicativo do Microsoft Entra são objetos de segurança em um aplicativo do Microsoft Entra que definem o que um aplicativo pode fazer em um determinado locatário. Eles são configurados no portal do Azure durante o processo de registro do aplicativo e configurados para acessar recursos do Azure, como o SQL do Azure. Para obter mais informações sobre como configurar uma entidade de serviço para seu ambiente, consulte a Documentação da entidade de serviço.

Ao usar o SqlPackage com uma entidade de serviço, talvez seja necessário recuperar o token de acesso e passá-lo para SqlPackage. O token de acesso pode ser recuperado via módulo do Azure PowerShell ou a CLI do Azure. O token de acesso pode ser passado para o SqlPackage por meio do parâmetro /at.

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /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:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

As entidades de serviço são compatíveis com os pipelines de CI/CD do Azure DevOps e do GitHub Actions.

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.

Além do SQL Server, o SqlPackage e o DacFx oferecem suporte à Instância Gerenciada de SQL do Azure, ao Banco de Dados SQL do Azure, ao Azure Synapse Analytics e ao Synapse Data Warehouse no Microsoft Fabric.

Próximas etapas