SqlPackage
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:
- O caminho especificado pela variável de ambiente
TMP
. - O caminho especificado pela variável de ambiente
TEMP
. - O caminho especificado pela variável de ambiente
USERPROFILE
. - 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
- Saiba mais sobre a ação Extract do SqlPackage
- Saiba mais sobre a ação Publish do SqlPackage
- Saiba mais sobre a ação Export do SqlPackage
- Saiba mais sobre a ação Import do SqlPackage
- Saiba mais sobre a solução de problemas para o SqlPackage
- Compartilhe um feedback sobre o SqlPackage no repositório do DacFx do GitHub
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de