Compartilhar via

SqlPackage

O SqlPackage é um utilitário de linha de comando que automatiza as tarefas de desenvolvimento do banco de dados expondo algumas das APIs públicas Data-Tier do DacFx (Application Framework). Os principais casos de uso do SqlPackage se concentram na portabilidade e nas implantações do banco de dados para o SQL Server, o SQL do Azure e a família de bancos de dados do Azure Synapse Analytics. O SqlPackage pode ser automatizado usando o Azure Pipelines e as ações do GitHub 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 do banco de dados é a capacidade de mover um esquema de banco de dados e dados entre instâncias diferentes 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 do SQL Server local ou do SQL Server para o Banco de Dados SQL do Azure são exemplos de portabilidade do banco de dados. O SqlPackage dá suporte à portabilidade do banco de dados por meio das ações de Exportação e Importação , que criam e consomem arquivos BACPAC. O SqlPackage também dá 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 os dados de referência armazenados no Armazenamento de Blobs do Azure.

  • Exportar: exporta um banco de dados SQL conectado – incluindo o esquema de banco de dados e os dados do usuário – para um arquivo BACPAC (.bacpac).

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

Implantações

As implantações de banco de dados são o processo de atualização de 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 dá 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) que contém o esquema ou os dados do esquema e do usuário de um banco de dados SQL conectado. O SqlPackage habilita implantações em bancos de dados novos ou existentes do mesmo artefato (.dacpac) criando automaticamente um plano de implantação que aplica 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 .

  • Extract: 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 incrementalmente um esquema de banco de dados para corresponder 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 será atualizado.

  • DeployReport: cria um relatório XML que representa as alterações que uma ação de publicação faria.

  • DriftReport: cria um relatório XML que representa as alterações aplicadas a um banco de dados registrado desde que foi registrado pela última vez.

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

Sintaxe da linha de comando

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

SqlPackage {parameters} {properties} {SQLCMD variables}

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

Comandos de utilidade

Versão

Exibe a versão do sqlpackage como um número de build. Pode ser usado em prompts interativos 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 ação específica, use o parâmetro de ajuda além do parâmetro dessa ação.

SqlPackage /Action:Publish /?

Autenticação

O SqlPackage autentica-se usando métodos disponíveis no SqlClient. A configuração do tipo de autenticação pode ser realizada 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 propriedades de conexão. Os seguintes métodos de autenticação têm suporte em uma cadeia de conexão:

  • Autenticação do SQL Server
  • Autenticação do Active Directory (Windows)
  • autenticação do Microsoft Entra
    • Nome de utilizador/palavra-passe
    • Autenticação integrada
    • Autenticação universal
    • Identidade gerenciada
    • Entidade de serviço

Identidade gerenciada

Observação

O Microsoft Entra ID era anteriormente 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 o SqlPackage em runtime, pois o SqlPackage usa identidades gerenciadas para se conectar a bancos de dados que dão suporte à autenticação do Microsoft Entra e para obter tokens do Microsoft Entra, sem gerenciamento de credenciais. Quando a identidade gerenciada é configurada para o ambiente em que a ação SqlPackage é executada, a ação SqlPackage pode usar essa identidade para autenticar no SQL do Azure. Para obter mais informações sobre como configurar uma identidade gerenciada para seu ambiente, consulte a documentação de identidade gerenciada.

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

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

As identidades gerenciadas têm suporte em pipelines de CI/CD do Azure DevOps e nas ações do GitHub.

Entidade de serviço

Observação

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

As entidades de serviço de aplicativo do Microsoft Entra são objetos de segurança dentro de 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 um principal de serviço para seu ambiente, consulte a documentação do principal de serviço.

Ao usar o SqlPackage com um principal de serviço, você pode recuperar um token de acesso e passá-lo para o SqlPackage. O token de acesso pode ser recuperado usando o módulo do Azure PowerShell ou a CLI do Azure. Nesse processo, o sistema de invocação mantém o controle sobre a atualização ou invalidação de token. O token de acesso pode ser passado para SqlPackage usando o /at parâmetro.

# 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;"

Como alternativa, você pode passar a ID do cliente da entidade de serviço e o segredo para o SqlPackage na cadeia de conexão. O formato da cadeia de conexão inclui Authentication=Active Directory Service Principal; e User Id=AppId; Password=<password>. Quando as credenciais da entidade de serviço são aprovadas na cadeia de conexão, o parâmetro /at não é necessário e o SqlPackage atualiza a autenticação conforme necessário durante a operação.

As identidades gerenciadas têm suporte em pipelines de CI/CD do Azure DevOps e nas ações dos pipelines CI/CD doGitHub.

Variáveis de ambiente

Agrupamento de conexões

O pool de conexões pode ser habilitado para todas as conexões feitas pelo SqlPackage definindo a variável de CONNECTION_POOLING_ENABLED ambiente como True. Essa configuração é recomendada para operações com conexões de nome de usuário e senha 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 sua 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.

O GetTempPath da API do .NET é usado para determinar o 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 TMP ambiente.
  2. O caminho especificado pela variável de TEMP ambiente.
  3. O caminho especificado pela variável de USERPROFILE ambiente.
  4. O diretório do Windows.

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

Usuários do SqlPackage e do banco de dados

Os usuários contidos no banco de dados são incluídos nas operações do SqlPackage. No entanto, a parte da senha da definição é definida como uma cadeia de caracteres gerada aleatoriamente pelo SqlPackage, o valor existente não é transferido. É recomendável que a senha do novo usuário seja redefinida para um valor seguro após a importação de um .bacpac ou da 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.

Extensibilidade

O SqlPackage dá suporte à extensibilidade por meio do MEF (Managed Extensibility Framework), habilitando cenários avançados por meio de componentes personalizados chamados colaboradores. Essas extensões podem personalizar como o SqlPackage publica .dacpac arquivos, permitindo que as equipes imponham padrões ou automatizem a lógica específica do projeto. Os colaboradores da implantação são executados como parte do processo de publicação, após o plano de implantação ser gerado, mas antes de ser executado. Esses colaboradores podem acessar e modificar o plano de implantação usando um DeploymentPlanModifier objeto de classe para adicionar, remover ou reordenar etapas. Para começar a usar a extensibilidade de implementação, consulte Usar colaboradores de implementação para personalizar a compilação e a implementação do banco de dados.

O SqlPackage descobre e carrega assemblies de colaboradores ao verificar bibliotecas de vínculo dinâmico (arquivos .dll) no mesmo diretório que o executável do SqlPackage, bem como nos locais especificados por meio da propriedade de linha de comando opcional /p:AdditionalDeploymentContributorPaths. Embora isso permita a personalização flexível, ela também apresenta considerações importantes de segurança.

Importante

Como o SqlPackage usa o MEF para carregar dinamicamente bibliotecas de vínculo dinâmico (arquivos .dll) em runtime, todos os assemblies colocados ao lado do executável do SqlPackage poderão ser executados como parte do processo de implantação. Um ator mal-intencionado pode explorar esse comportamento introduzindo extensões adulteradas ou não autorizadas que executam código arbitrário.

É sua responsabilidade garantir que todos os arquivos de extensão compilados usados com SqlPackage sejam seguros e provenientes de fontes confiáveis. Recomendamos controlar o acesso à pasta SqlPackage e validar a integridade de todos os componentes personalizados ou de terceiros.

Coleta de dados de uso

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

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

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

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 o relatório de telemetria, atualize a variável DACFX_TELEMETRY_OPTOUT de ambiente para true ou 1.

Apoio

A biblioteca DacFx e a ferramenta CLI do SqlPackage seguem a Política de Ciclo de Vida Moderna da Microsoft. Todas as atualizações de segurança, correções e novos recursos são lançadas apenas na versão de ponto mais recente da versão principal. Manter as instalações do DacFx ou do SqlPackage na versão atual ajuda a garantir que você receba todas as correções de bug aplicáveis em tempo hábil.

Obtenha ajuda com o SqlPackage, envie solicitações de recursos e reporte problemas no repositório GitHub do DacFx.

Ofertas de SQL com suporte

O SqlPackage e o DacFx dão suporte a todas as versões do SQL com suporte no momento da versão do SqlPackage/DacFx. Por exemplo, uma versão do SqlPackage em 14 de janeiro de 2022 dá suporte a todas as versões com suporte do SQL em 14 de janeiro de 2022. Para obter mais informações sobre políticas de suporte do SQL, consulte a política de suporte do SQL.

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

Próximas etapas

  • Last updated on