Partilhar via

SqlPackage

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 Data-Tier Application Framework (DacFx). Os principais casos de uso do SqlPackage se concentram na portabilidade e implantações de banco de dados para a família de bancos de dados SQL Server, Azure SQL e Azure Synapse Analytics. O SqlPackage pode ser automatizado usando ações do Azure Pipelines e GitHub ou outras ferramentas de CI/CD.

Faça o download da versão mais recente. Para obter detalhes sobre a versão mais recente, consulte as notas de versão .

Observação

Embora o Microsoft Entra ID seja o novo nome para o Azure Ative Directory (Azure AD), para evitar a interrupção de ambientes existentes, o Azure AD ainda permanece 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

Portabilidade de banco de dados é a capacidade de mover um esquema de banco de dados e dados entre diferentes instâncias do SQL Server, Azure SQL e 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 suporta a portabilidade do banco de dados por meio das ações Export e Import, 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 fazer referência aos dados armazenados no Armazenamento de Blobs do Azure.

  • Export: Exporta um banco de dados SQL conectado - incluindo esquema de 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 para um novo banco de dados de usuários.

Implementaçõ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 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 dados do usuário de um banco de dados SQL conectado. SqlPackage permite implantações em bancos de dados novos ou existentes a partir 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 ficheiro de aplicação de camada de dados (.dacpac) contendo o esquema ou o esquema e os dados do utilizador de uma base de dados SQL ligada.

  • Publish: 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 realizaria.

  • DriftReport: Cria um relatório XML que representa as alterações aplicadas a um banco de dados registrado desde que ele 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 de Linha de Comando

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

SqlPackage {parameters} {properties} {SQLCMD variables}

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

Comandos úteis

Versão

Exibe a versão do sqlpackage como um número de compilação. 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 obter informações de parâmetros e propriedades específicas de uma ação específica, use o parâmetro help além do parâmetro dessa ação.

SqlPackage /Action:Publish /?

Autenticação

SqlPackage autentica usando métodos disponíveis em SqlClient. A configuração do tipo de autenticação pode ser realizada por meio dos parâmetros da cadeia de conexão para cada ação SqlPackage (/SourceConnectionString e /TargetConnectionString) ou por meio de parâmetros individuais para propriedades de conexão. Os seguintes métodos de autenticação são suportados em uma cadeia de conexão:

  • Autenticação do SQL Server
  • Autenticação do Ative 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

Microsoft Entra ID era anteriormente conhecido como Azure Ative 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 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 gerenciamento de credenciais. Quando a identidade gerenciada é configurada para o ambiente onde a ação SqlPackage é executada, a ação SqlPackage pode usar essa identidade para autenticar no Azure SQL. 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 identidade gerenciada atribuída ao sistema é:

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

As identidades geridas são suportadas nos pipelines de CI/CD do Azure DevOps e das ações do GitHub.

Entidade de serviço

Observação

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

As entidades de serviço de aplicativo Microsoft Entra são objetos de segurança dentro de um aplicativo 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 Azure SQL. 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 um principal de serviço, 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 do 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 o ID do cliente principal de serviço e o segredo para 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 do principal de serviço são passadas na cadeia de ligação, o parâmetro "/at" não é necessário e o SqlPackage atualiza a autenticação conforme necessário durante a operação.

As entidades de serviço têm suporte tanto em Azure DevOps como em pipelines de CI/CD do GitHub Actions.

Variáveis de ambiente

Agrupamento de conexões

O pool de conexões pode ser habilitado para todas as conexões feitas por 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 Biblioteca de Autenticação da Microsoft (MSAL).

Ficheiros temporários

Durante as operações SqlPackage, os dados da tabela são gravados em arquivos temporários antes da compactação ou após a descompressã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 para especificar /p:TempDirectoryForTableData e substituir o valor padrão do SqlPackage.

A API .NET GetTempPath é usada para determinar o valor padrão dentro de SqlPackage.

Para o Windows, as seguintes variáveis de ambiente são verificadas na seguinte ordem e o primeiro caminho existente é 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 TMPDIR variável de ambiente, o caminho /tmp/ padrão será usado.

SqlPackage e usuários de banco de dados

Os usuários de banco de dados contidos são incluídos nas operações SqlPackage. No entanto, a parte de senha da definição é definida como uma cadeia de caracteres gerada aleatoriamente por SqlPackage, o valor existente não é transferido. É recomendável que a senha do novo utilizador seja redefinida para um valor seguro após a importação de um .bacpac ou a implantação de um .dacpacarquivo. Em um ambiente automatizado, os valores de senha podem ser recuperados de um armazenamento de chaves seguro, como o Cofre de Chaves do Azure, em uma etapa após SqlPackage.

Extensibilidade

SqlPackage suporta extensibilidade através do Managed Extensibility Framework (MEF), permitindo cenários avançados através de componentes personalizados chamados contribuidores. Essas extensões podem personalizar como o SqlPackage publica .dacpac arquivos, permitindo que as equipes apliquem padrões ou automatizem a lógica específica do projeto. Os componentes de implementação são executados como parte integrada no processo de publicação, depois de 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 implantação, consulte Usar colaboradores de implantação para personalizar a compilação e a implantação do banco de dados.

SqlPackage deteta e carrega assemblies de colaborador ao procurar bibliotecas de ligação dinâmica (ficheiros .dll) no mesmo diretório que o executável SqlPackage, bem como nos locais especificados através da propriedade /p:AdditionalDeploymentContributorPaths de linha de comando opcional. Embora isso permita uma personalização flexível, também introduz considerações de segurança importantes.

Importante

Como o SqlPackage utiliza o MEF para carregar dinamicamente bibliotecas de vínculo dinâmico (ficheiros .dll) em tempo de execução, quaisquer assemblagens colocadas ao lado do executável SqlPackage podem ser executadas como parte do processo de implantação. Um agente 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 venham de fontes confiáveis. Recomendamos controlar o acesso à pasta SqlPackage e validar a integridade de todos os componentes personalizados ou de terceiros.

Recolha de dados de utilizaçã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.

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

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, SqlPackage gera um GUID aleatório para cada computador em que é executado e usa esse valor para todos os eventos enviados.

Para obter detalhes, consulte a Declaração de Privacidade da Microsofte o suplemento de Privacidade do SQL Server.

Desativar 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 SqlPackage CLI 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çados apenas na versão pontual mais recente da versão principal. Manter suas instalações DacFx ou SqlPackage na versão atual ajuda a garantir que você receba todas as correções de bugs aplicáveis em tempo hábil.

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

Ofertas SQL suportadas

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

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

Próximos passos

  • Last updated on