Partilhar via

utilitário sqlcmd

  • Artigo

Aplica-se a:Banco de Dados SQL do AzureAzureInstância Gerida SQL do AzureAzure Synapse AnalyticsAnalytics Platform System (PDW)Base de Dados SQL no Microsoft Fabric

O utilitário sqlcmd permite inserir instruções Transact-SQL, procedimentos do sistema e arquivos de script por meio de vários modos:

  • No prompt de comandos.
  • No Editor de Consultas em modo SQLCMD.
  • Em um arquivo de script do Windows.
  • Em uma etapa de trabalho do sistema operacional (cmd.exe) de um trabalho do SQL Server Agent.

Observação

Embora o Microsoft Entra ID seja o novo nome para o Azure Active Directory (Azure AD), para evitar a perturbação de ambientes existentes, o Azure AD ainda permanece em alguns elementos codificados, como campos da interface do utilizador, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Descubra qual versão você instalou

Existem duas versões do sqlcmd:

  • O go-mssqldbbaseado em sqlcmd, às vezes estilizado como go-sqlcmd. Esta versão é uma ferramenta autônoma que você pode baixar independentemente do SQL Server.

  • O sqlcmd baseado em ODBC, disponível com o SQL Server ou os Utilitários de Linha de Comando da Microsoft, e parte do pacote mssql-tools no Linux.

Para determinar a versão instalada, execute a seguinte instrução na linha de comando:

sqlcmd "-?"

sqlcmd "-?"

sqlcmd -?

Se você estiver usando a nova versão do sqlcmd (Go), a saída será semelhante ao exemplo a seguir:

Version: 1.3.1

Verificar versão

Você pode usar sqlcmd --version para determinar qual versão está instalada. Você deve ter pelo menos a versão 1.0.0 instalada.

Importante

A instalação do sqlcmd (Go) por meio de um gerenciador de pacotes substitui sqlcmd (ODBC) por sqlcmd (Go) no caminho do ambiente. Todas as sessões de linha de comando atuais devem ser fechadas e reabertas para que isso entre em vigor. sqlcmd (ODBC) não será removido e ainda pode ser usado especificando o caminho completo para o executável. Você também pode atualizar sua variável PATH para indicar qual tem precedência. Para fazer isso no Windows 11, abra Configurações do sistema e vá para Sobre > Configurações avançadas do sistema. Quando Propriedades do Sistema for aberto, selecione o botão Variáveis de Ambiente. Na metade inferior, em Variáveis do sistema, selecione Caminho e, em seguida, selecione Editar. Se o local sqlcmd (Go) for salvo em (C:\Program Files\sqlcmd é padrão) e estiver listado antes de C:\Program Files\Microsoft SQL Server\<version>\Tools\Binn, então sqlcmd (Go) será usado. Você pode inverter a ordem para tornar sqlcmd (ODBC) o padrão novamente.

Baixe e instale o sqlcmd

sqlcmd (Go) pode ser instalado em várias plataformas, no Microsoft Windows, macOS e Linux. As versões mais recentes que a 1.6 podem não estar disponíveis em todos os gerenciadores de pacotes. Ainda não há data prevista para a sua disponibilidade.

winget (CLI do Gerenciador de Pacotes do Windows)

  1. Instale o Cliente do Gerenciador de Pacotes do Windows, se ainda não o tiver.

  2. Execute o seguinte comando para instalar sqlcmd (Go).

    winget install sqlcmd

Achocolatado

  1. Instale Chocolatey se ainda não o tiver.

  2. Execute o seguinte comando para instalar sqlcmd (Go).

    choco install sqlcmd

Download direto

  1. Baixe o ficheiro -windows-amd64.zip ou -windows-arm.zip correspondente da última versão do mais recente do sqlcmd (Go), do repositório de código do GitHub.

  2. Extraia o arquivo sqlcmd.exe da pasta zip baixada.

Pré-instalado

Azure Cloud Shell

Pode experimentar o utilitário sqlcmd, identificado como e, do Azure Cloud Shell, pois vem pré-instalado por padrão.

Azure Data Studio

Para executar instruções SQLCMD no Azure Data Studio, selecione Habilitar SQLCMD na barra de ferramentas do editor.

SQL Server Management Studio (SSMS)

Para executar instruções SQLCMD no SQL Server Management Studio (SSMS), selecione Modo SQLCMD na lista suspensa do Menu de Consulta na barra de navegação superior.

O SSMS usa o Microsoft .NET Framework SqlClient para execução no modo regular e SQLCMD no Editor de Consultas. Quando sqlcmd é executado a partir da linha de comando, sqlcmd usa o driver ODBC. Como diferentes opções padrão podem ser aplicadas, você pode ver um comportamento diferente ao executar a mesma consulta no SSMS no Modo SQLCMD e no utilitário sqlcmd.

Sintaxe

Usage:
  sqlcmd [flags]
  sqlcmd [command]

Examples:
# Install/Create, Query, Uninstall SQL Server
  sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
  sqlcmd open ads
  sqlcmd query "SELECT @@version"
  sqlcmd delete
# View configuration information and connection strings
  sqlcmd config view
  sqlcmd config cs

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Modify sqlconfig files using subcommands like "sqlcmd config use-context mssql"
  create      Install/Create SQL Server, Azure SQL, and Tools
  delete      Uninstall/Delete the current context
  help        Help about any command
  open        Open tools (e.g ADS) for current context
  query       Run a query against the current context
  start       Start current context
  stop        Stop current context

Flags:
  -?, --?                  help for backwards compatibility flags (-S, -U, -E etc.)
  -h, --help               help for sqlcmd
      --sqlconfig string   configuration file (default "/Users/<currentUser>/.sqlcmd/sqlconfig")
      --verbosity int      log level, error=0, warn=1, info=2, debug=3, trace=4 (default 2)
      --version            print version of sqlcmd

Use "sqlcmd [command] --help" for more information about a command.

Para obter informações mais detalhadas sobre sintaxe e uso do sqlcmd, consulte de sintaxe sqlcmd ODBC .

Quebrando alterações do sqlcmd (ODBC)

Várias opções e comportamentos são alterados no utilitário sqlcmd (Go). Para obter a lista mais up-toatualizada de sinalizadores ausentes para compatibilidade com versões anteriores, visite a discussão no GitHub Priorizar a implementação de sinalizadores para compatibilidade com versões anteriores.

  • Em versões anteriores do sqlcmd (Go), a opção -P foi temporariamente removida e as senhas para a Autenticação do SQL Server só podiam ser fornecidas por meio destes mecanismos:

    • A variável de ambiente SQLCMDPASSWORD
    • O comando :CONNECT
    • Quando solicitado, o usuário pode digitar a senha para concluir uma conexão

  • -r requer um argumento 0 ou 1

  • -R interruptor é removido.

  • O interruptor -I foi removido. Para desativar o comportamento do identificador entre aspas, adicione SET QUOTED IDENTIFIER OFF nos seus scripts.

  • -N agora usa um valor de cadeia de caracteres que pode ser um dos true, falseou disable para especificar a opção de criptografia. (default é o mesmo que omitir o parâmetro)

    • Se -N e -C não forem fornecidos, sqlcmd negociará a autenticação com o servidor sem validar o certificado do servidor.
    • Se -N for fornecido, mas -C não, o sqlcmd exigirá a validação do certificado do servidor. Um valor false para criptografia ainda pode levar à criptografia do pacote de login.
    • Se -N e -C forem fornecidos, sqlcmd usará seus valores para negociação de criptografia.
    • Mais informações sobre a negociação de criptografia cliente/servidor podem ser encontradas em MS-TDS PRELOGIN.

  • -u O arquivo de saída Unicode gerado tem a marca de ordem de bytes (BOM) UTF-16 Little-Endian gravada nele.

  • Alguns comportamentos que foram mantidos para manter a compatibilidade com OSQL podem ser alterados, como o alinhamento de cabeçalhos de coluna para alguns tipos de dados.

  • Todos os comandos devem caber em uma linha, mesmo EXIT. O modo interativo não verifica se há parênteses abertos ou aspas para comandos e não solicita linhas sucessivas. Esse comportamento é diferente da versão ODBC, que permite que a consulta executada por EXIT(query) abranja várias linhas.

As conexões do utilitário sqlcmd (Go) são limitadas a conexões TCP. Os pipes nomeados não são suportados neste momento no driver go-mssqldb.

Melhorias

  • :Connect agora tem um parâmetro -G opcional para selecionar um dos métodos de autenticação do Banco de Dados SQL do Azure - SqlAuthentication, ActiveDirectoryDefault, ActiveDirectoryIntegrated, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity, ActiveDirectoryPassword. Para obter mais informações, consulte autenticação do Microsoft Entra. Se -G não for fornecida, a segurança integrada ou a autenticação do SQL Server será usada, dependendo da presença de um parâmetro de nome de usuário -U.

  • O novo parâmetro de linha de comando --driver-logging-level permite que você veja traços do driver go-mssqldb. Use 64 para ver todos os vestígios.

  • sqlcmd agora pode imprimir resultados usando um formato vertical. Use a nova opção de linha de comando -F vertical para defini-la. A variável de script SQLCMDFORMAT também a controla.

Opções de linha de comando

-Um

Entra no SQL Server com uma conexão de administrador (DAC) dedicada. Esse tipo de conexão é usado para solucionar problemas de um servidor. Esta ligação funciona apenas com computadores servidores que suportam DAC. Se o DAC não estiver disponível, sqlcmd gerará uma mensagem de erro e será encerrado. Para obter mais informações sobre o DAC, consulte conexão de diagnóstico para administradores de banco de dados. A opção -A não é suportada com a opção -G. Ao se conectar ao Banco de Dados SQL do Azure usando -A, você deve ser um administrador no servidor SQL lógico. O DAC não está disponível para um administrador do Microsoft Entra.

-C

Essa opção é usada pelo cliente para configurá-la para confiar implicitamente no certificado do servidor sem validação. Esta opção é equivalente à opção ADO.NET TRUSTSERVERCERTIFICATE = true.

Para o utilitário sqlcmd (Go), as seguintes condições também se aplicam:

  • Se -N e -C não forem fornecidos, sqlcmd negociará a autenticação com o servidor sem validar o certificado do servidor.
  • Se -N for fornecido, mas -C não for, sqlcmd exigirá a validação do certificado do servidor. Um valor false para criptografia ainda pode levar à criptografia do pacote de login.
  • Se -N e -C forem fornecidos, sqlcmd usará seus valores para negociação de criptografia.

-d db_name

Emite uma instrução USE <db_name> quando você inicia sqlcmd. Esta opção define o sqlcmd variável de script SQLCMDDBNAME. Este parâmetro especifica o banco de dados inicial. O padrão é a propriedade default-database do seu login. Se o banco de dados não existir, uma mensagem de erro será gerada e sqlcmd será encerrado.

-D

Interpreta o nome do servidor fornecido ao -S como um DSN em vez de um nome de host. Para obter mais informações, consulte suporte DSN em sqlcmd e bcp em Conexão com sqlcmd.

Observação

A opção -D só está disponível em clientes Linux e macOS. Em clientes Windows, ele anteriormente se referia a uma opção agora obsoleta que foi removida e é ignorada.

-l login_timeout

Especifica o número de segundos antes de um login do sqlcmd no driver ODBC atingir o tempo limite quando se tenta conectar a um servidor. Esta opção define a variável de script sqlcmdSQLCMDLOGINTIMEOUT. O tempo limite padrão para login em sqlcmd é de 8 segundos. Ao usar a opção -G para se conectar ao Banco de Dados SQL do Azure ou ao Azure Synapse Analytics e autenticar usando a ID do Microsoft Entra, recomenda-se um valor de tempo limite de pelo menos 30 segundos. O tempo limite de login deve ser um número entre 0 e 65534. Se o valor fornecido não for numérico ou não se enquadrar nesse intervalo, sqlcmd gerará uma mensagem de erro. Um valor de 0 especifica o tempo limite como infinito.

-E

Usa uma conexão confiável em vez de usar um nome de usuário e senha para entrar no SQL Server. Por padrão, sem -E especificado, sqlcmd usa a opção de conexão confiável.

A opção -E ignora possíveis configurações de variáveis de ambiente de nome de usuário e senha, como SQLCMDPASSWORD. Se a opção -E for usada junto com a opção -U ou a opção -P, uma mensagem de erro será gerada.

-g

Define a configuração Criptografia de Coluna para Enabled. Para obter mais informações, consulte Always Encrypted. Apenas as chaves mestras armazenadas no Repositório de Certificados do Windows são suportadas. A opção -g requer pelo menos sqlcmd versão 13.1. Para determinar sua versão, execute sqlcmd -?.

-G

Essa opção é usada pelo cliente ao se conectar ao Banco de Dados SQL do Azure ou ao Azure Synapse Analytics para especificar que o usuário seja autenticado usando a autenticação do Microsoft Entra. Esta opção define a variável de script sqlcmdSQLCMDUSEAAD = true. A opção -G requer pelo menos sqlcmd versão 13.1. Para determinar sua versão, execute sqlcmd -?. Para obter mais informações, consulte Conectando-se ao Banco de Dados SQL ou Azure Synapse Analytics usando a autenticação do Microsoft Entra. A opção -A não é suportada com a opção -G.

A opção -G só se aplica ao Banco de Dados SQL do Azure e ao Azure Synapse Analytics.

A autenticação interativa do Microsoft Entra não é suportada atualmente no Linux ou macOS. A autenticação integrada do Microsoft Entra requer Microsoft ODBC Driver 17 para SQL Server versão 17.6.1 ou superior e um ambiente Kerberos configurado corretamente .

Para obter mais informações sobre a autenticação do Microsoft Entra, consulte a autenticação do Microsoft Entra no sqlcmd .

-H workstation_name

Um nome de estação de trabalho. Esta opção define a variável de script sqlcmdSQLCMDWORKSTATION. O nome da estação de trabalho está listado na coluna hostname da exibição de catálogo sys.sysprocesses e pode ser retornado usando o procedimento armazenado sp_who. Se essa opção não for especificada, o padrão será o nome do computador atual. Esse nome pode ser usado para identificar diferentes sessões de sqlcmd.

-j

Imprime mensagens de erro brutas na tela.

-K application_intent

Declara o tipo de carga de trabalho do aplicativo ao se conectar a um servidor. O único valor suportado atualmente é ReadOnly. Se -K não for especificado, o sqlcmd não oferece suporte à conectividade com uma réplica secundária em um grupo de disponibilidade. Para obter mais informações, consulte Active Secundários: Réplicas Secundárias Legíveis (Always On Availability Groups).

-M multisubnet_failover

Sempre especifique -M ao conectar-se ao listener do grupo de disponibilidade de um grupo de disponibilidade do SQL Server ou de uma Instância de Cluster de Failover do SQL Server. -M fornece deteção e conexão mais rápidas com o servidor (atualmente) ativo. Se -M não for especificado, -M está desativado. Para obter mais informações sobre Ouvintes, Conectividade de Cliente, Failover de Aplicativos, Criação e Configuração de Grupos de Disponibilidade (SQL Server), Clustering de Failover e Grupos de Disponibilidade Always On (SQL Server)e Secundários Ativos: Réplicas Secundárias de Leitura (Grupos de Disponibilidade Always On).

-N

Esta opção é usada pelo cliente para solicitar uma conexão criptografada.

Para o utilitário sqlcmd (Go), -N agora usa um valor de cadeia de caracteres que pode ser um dos true, falseou disable para especificar a opção de criptografia. (default é o mesmo que omitir o parâmetro):

  • Se -N e -C não forem fornecidos, sqlcmd negociará a autenticação com o servidor sem validar o certificado do servidor.
  • Se -N for fornecido, mas -C não, sqlcmd exigirá a validação do certificado do servidor. Um valor false para criptografia ainda pode levar à criptografia do pacote de login.
  • Se -N e -C forem fornecidos, sqlcmd usará seus valores para negociação de criptografia.

-P senha

Uma senha especificada pelo usuário. As senhas diferenciam maiúsculas de minúsculas. Se a opção -U for usada e a opção -P não for usada, e a variável de ambiente SQLCMDPASSWORD não tiver sido definida, sqlcmd solicitará uma senha ao usuário. Não recomendamos o uso de uma senha nula (em branco), mas você pode especificar a senha nula usando um par de aspas duplas contíguas para o valor do parâmetro ("").

Importante

O uso do -P deve ser considerado inseguro. Evite dar a senha na linha de comando. Como alternativa, use a variável de ambiente SQLCMDPASSWORD ou insira interativamente a senha omitindo a opção -P.

Recomendamos que utilize uma palavra-passe forte .

O prompt de senha é exibido imprimindo o prompt de senha no console, da seguinte maneira: Password:

A entrada do usuário está oculta. Isso significa que nada é exibido e o cursor permanece na posição.

A variável de ambiente SQLCMDPASSWORD permite definir uma senha padrão para a sessão atual. Portanto, as senhas não precisam ser codificadas em arquivos em lote. O exemplo a seguir primeiro define a variável SQLCMDPASSWORD no prompt de comando e, em seguida, acessa o utilitário sqlcmd.

No prompt de comando, digite:

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

Se a combinação de nome de usuário e senha estiver incorreta, uma mensagem de erro será gerada.

Observação

A variável de ambiente OSQLPASSWORD foi mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDPASSWORD tem precedência sobre a variável de ambiente OSQLPASSWORD. Isso significa que sqlcmd e osql podem ser usados um ao lado do outro sem interferência. Scripts antigos continuam a funcionar.

Se a opção -P for usada com a opção -E, uma mensagem de erro será gerada.

Se a opção -P for seguida por mais de um argumento, uma mensagem de erro será gerada e o programa será encerrado.

Uma senha contendo caracteres especiais pode gerar uma mensagem de erro. Você deve escapar de caracteres especiais ao usar -Pou usar a variável de ambiente SQLCMDPASSWORD.

-S [protocolo:]servidor[\instance_name][,porta]

Especifica a instância do SQL Server à qual se conectar. Define a variável de script sqlcmd SQLCMDSERVER.

Especifique server_name para se conectar à instância padrão do SQL Server nesse servidor. Especifique server_name[\instance_name] para se conectar a uma instância nomeada do SQL Server nesse computador servidor. Se nenhum computador servidor for especificado, sqlcmd se conectará à instância padrão do SQL Server no computador local. Essa opção é necessária quando você executa sqlcmd de um computador remoto na rede.

de protocolo pode ser tcp (TCP/IP), lpc (memória partilhada) ou np (tubos nomeados).

Se você não especificar um server_name[\instance_name] ao iniciar sqlcmd , o SQL Server verificará e usará a variável de ambiente SQLCMDSERVER.

Observação

A variável de ambiente OSQLSERVER foi mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDSERVER tem precedência sobre a variável de ambiente OSQLSERVER. Isso significa que sqlcmd e osql podem ser usados um ao lado do outro sem interferência. Scripts antigos continuam a funcionar.

-U identificação_de_login

O nome de login ou o nome de usuário do banco de dados contido. Para usuários de banco de dados contidos, você deve fornecer a opção de nome do banco de dados (-d).

Observação

A variável de ambiente OSQLUSER foi mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDUSER tem precedência sobre a variável de ambiente OSQLUSER. Isso significa que sqlcmd e osql podem ser usados um ao lado do outro sem interferência. Scripts antigos continuam a funcionar.

Se você não especificar a opção -U ou a opção -P, sqlcmd tentará se conectar usando o modo de Autenticação do Windows. A autenticação é baseada na conta do Windows do usuário que está executando sqlcmd.

Se a opção -U for usada com a opção -E (descrita posteriormente neste artigo), uma mensagem de erro será gerada. Se a opção -U for seguida por mais de um argumento, uma mensagem de erro será gerada e o programa será encerrado.

-z nova_senha

Altere a palavra-passe:

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

-Z nova_senha

Altere a senha e saia:

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

Opções de entrada/saída

-f página de código | i:página de código[,o:página de código] | o:página de código[,i:página de código]

Especifica as páginas de código de entrada e saída. O número da página de código é um valor numérico que especifica uma página de código do Windows instalada.

Regras de conversão de página de código:

  • Se nenhuma página de código for especificada, sqlcmd usará a página de código atual para arquivos de entrada e saída, a menos que o arquivo de entrada seja um arquivo Unicode, caso em que nenhuma conversão é necessária.

  • sqlcmd reconhece automaticamente os arquivos de entrada Unicode big-endian e little-endian. Se a opção -u for especificada, a saída será sempre no formato little-endian Unicode.

  • Se nenhum arquivo de saída for especificado, a página de código de saída será a página de código do console. Essa abordagem permite que a saída seja exibida corretamente no console.

  • Vários arquivos de entrada são assumidos como sendo da mesma página de código. Os arquivos de entrada Unicode e não-Unicode podem ser misturados.

Digite chcp no prompt de comando para verificar a página de código do cmd.exe.

-i input_file[,input_file2...]

Identifica o arquivo que contém um lote de instruções Transact-SQL ou procedimentos armazenados. Vários arquivos podem ser especificados que são lidos e processados em ordem. Não use espaços entre nomes de arquivos. sqlcmd verifica primeiro se todos os arquivos especificados existem. Se um ou mais arquivos não existirem, sqlcmd será encerrado. As opções -i e -Q/-q excluem-se mutuamente.

Observação

Se você usar a opção -i seguida por um ou mais parâmetros adicionais, deverá usar um espaço entre o parâmetro e o valor. Este é um problema conhecido no sqlcmd (Go).

Exemplos de caminho:

-i C:\<filename>
-i \\<Server>\<Share$>\<filename>
-i "C:\Some Folder\<file name>"

Os caminhos de arquivo que contêm espaços devem ser colocados entre aspas.

Esta opção pode ser usada mais de uma vez:

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

-o ficheiro_saida

Identifica o arquivo que recebe a saída de sqlcmd.

Se -u for especificado, o output_file será armazenado no formato Unicode. Se o nome do arquivo não for válido, uma mensagem de erro será gerada e sqlcmd será encerrado. sqlcmd não oferece suporte à gravação simultânea de vários processos de sqlcmd no mesmo arquivo. A saída do arquivo está corrompida ou incorreta. A opção -f também é relevante para formatos de arquivo. Este ficheiro é criado se não existir. Um arquivo com o mesmo nome de uma sessão anterior sqlcmd é substituído. O arquivo especificado aqui não é o arquivo stdout. Se um arquivo stdout for especificado, esse arquivo não será usado.

Exemplos de caminho:

-o C:< filename>
-o \\<Server>\<Share$>\<filename>
-o "C:\Some Folder\<file name>"

Os caminhos de arquivo que contêm espaços devem ser colocados entre aspas.

-r[0 | 1]

Redireciona a saída da mensagem de erro para o ecrã (stderr). Se você não especificar um parâmetro ou se especificar 0, somente as mensagens de erro com um nível de gravidade igual ou superior a 11 serão redirecionadas. Se você especificar 1, toda a saída de mensagem de erro, incluindo PRINT, será redirecionada. Esta opção não terá efeito se utilizar -o. Por padrão, as mensagens são enviadas para stdout.

Observação

Para o utilitário sqlcmd (Go), -r requer um argumento 0 ou 1.

-R

Aplica-se a: ODBC somente sqlcmd.

Faz com que sqlcmd localize colunas numéricas, monetárias, de data e hora recuperadas do SQL Server com base na localidade do cliente. Por padrão, essas colunas são exibidas usando as configurações regionais do servidor.

-u

Especifica que output_file é armazenado no formato Unicode, independentemente do formato do input_file.

Observação

Para o utilitário sqlcmd (Go), o arquivo de saída Unicode gerado tem a marca de ordem de bytes (BOM) UTF-16 Little-Endian gravada nele.

Opções de execução de consulta

-e

Grava scripts de entrada no dispositivo de saída padrão (stdout).

-Eu

Aplica-se a: somente ODBC sqlcmd.

Define a opção de conexão SET QUOTED_IDENTIFIER como ON. Por padrão, ele é definido como OFF. Para obter mais informações, consulte SET QUOTED_IDENTIFIER (Transact-SQL).

Observação

Para desativar o comportamento do identificador entre aspas no utilitário sqlcmd (Go), adicione SET QUOTED IDENTIFIER OFF nos seus scripts.

-q "consulta cmdline"

Executa uma consulta quando sqlcmd é iniciado, mas não encerra sqlcmd quando a consulta termina de ser executada. Múltiplas consultas delimitadas por ponto-e-vírgula podem ser executadas. Use aspas ao redor da consulta, conforme mostrado no exemplo a seguir.

No prompt de comando, digite:

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Importante

Não use o terminador GO na consulta.

Se -b for especificado junto com esta opção, sqlcmd será encerrado em caso de erro. -b é descrito em outra parte deste artigo.

-Q "consulta de linha de comandos"

Executa uma consulta quando sqlcmd começa e depois sai imediatamente de sqlcmd. Consultas múltiplas delimitadas por ponto-e-vírgula podem ser executadas.

Use aspas ao redor da consulta, conforme mostrado no exemplo a seguir.

No prompt de comando, digite:

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Importante

Não use o terminador GO na consulta.

Se -b for especificado junto com esta opção, sqlcmd encerra-se em caso de erro. -b é descrito em outra parte deste artigo.

-t query_timeout

Especifica o número de segundos antes que um comando (ou instrução Transact-SQL) atinja o tempo limite. Esta opção define o sqlcmd variável de script SQLCMDSTATTIMEOUT. Se um valor de query_timeout não for especificado, o comando não expirará. O query_timeout deve ser um número entre 1 e 65534. Se o valor fornecido não for numérico ou não se enquadrar nesse intervalo, sqlcmd gerará uma mensagem de erro.

Observação

O valor de tempo limite real pode variar do valor de query_timeout especificado em vários segundos.

-v var = valor [ var = valor... ]

Cria uma variável de script sqlcmd que pode ser usada num script sqlcmd. Coloque o valor entre aspas se o valor contiver espaços. Você pode especificar vários valores de <var>="<value>". Se houver erros em qualquer um dos valores especificados, sqlcmd gerará uma mensagem de erro e será encerrada.

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

-x

Faz com que sqlcmd ignorem variáveis de script. Esse parâmetro é útil quando um script contém muitas instruções INSERT que podem conter cadeias de caracteres que têm o mesmo formato que variáveis regulares, como $(<variable_name>).

Opções de formato

-h cabeçalhos

Especifica o número de linhas a imprimir entre os cabeçalhos das colunas. O padrão é imprimir títulos uma vez para cada conjunto de resultados de consulta. Esta opção define o sqlcmd variável de script SQLCMDHEADERS. Use -1 para especificar que os cabeçalhos não sejam impressos. Qualquer valor que não seja válido faz com que sqlcmd gere uma mensagem de erro e, em seguida, saia.

-k [1 | 2]

Remove todos os caracteres de controle, como tabulações e caracteres de nova linha, da saída. Este parâmetro preserva a formatação da coluna quando os dados são retornados.

  • -k remove caracteres de controle.
  • -k1 substitui cada caractere de controle por um espaço.
  • -k2 substitui caracteres de controle consecutivos por um único espaço.

-s col_separator

Especifica o caractere separador de coluna. O padrão é um espaço em branco. Esta opção define o sqlcmd variável de script SQLCMDCOLSEP. Para utilizar caracteres que tenham um significado especial para o sistema operativo, como o e comercial (&) ou o ponto e vírgula (;), coloque o caractere entre aspas ("). O separador de coluna pode ser qualquer caractere de 8 bits.

-w largura_da_tela

Especifica a largura da tela para a saída. Esta opção define a variável de script sqlcmdSQLCMDCOLWIDTH. A largura da coluna deve ser um número maior que 8 e menor que 65536. Se a largura da coluna especificada não cair nesse intervalo, sqlcmd gerará uma mensagem de erro. A largura padrão é de 80 caracteres. Quando uma linha de saída excede a largura da coluna especificada, é deslocada para a linha seguinte.

-W

Esta opção remove espaços à direita de uma coluna. Use essa opção junto com a opção -s ao preparar dados que serão exportados para outro aplicativo. Não pode ser usado com as opções -y ou -Y.

-y variable_length_type_display_width

Define o sqlcmd variável de script SQLCMDMAXVARTYPEWIDTH. O padrão é 256. Ele limita o número de caracteres que são retornados para os tipos de dados de comprimento variável grande:

  • varchar(max)
  • nvarchar(max)
  • varbinary(max)
  • xml
  • tipos de dados definidos pelo usuário (UDTs)
  • texto
  • ntext
  • imagem

As UDTs podem ser de comprimento fixo, dependendo da implementação. Se esse comprimento de um UDT de comprimento fixo for menor que display_width, o valor do UDT retornado não será afetado. No entanto, se o comprimento for maior que display_width, a saída será truncada.

Atenção

Use a opção -y 0 com extrema cautela, pois ela pode causar problemas significativos de desempenho no servidor e na rede, dependendo do tamanho dos dados retornados.

-Y largura_de_ecrã_do_tipo_de_comprimento_fixado

Define a variável de script sqlcmdSQLCMDMAXFIXEDTYPEWIDTH. O padrão é 0 (ilimitado). Limita o número de caracteres retornados para os seguintes tipos de dados:

  • char(n), onde 1 <= n<= 8000
  • nchar(n), onde 1 <= n<= 4000
  • varchar(n), onde 1 <= n<= 8000
  • nvarchar(n), onde 1 <= n<= 4000
  • varbinary(n), onde 1 <= n<= 4000
  • sql_variant

Opções de relatório de erros

-b

Especifica que sqlcmd sai e retorna um valor DOS ERRORLEVEL quando ocorre um erro. O valor que é retornado para a variável ERRORLEVEL é 1 quando a mensagem de erro do SQL Server tem um nível de gravidade maior que 10; caso contrário, o valor retornado será 0. Se a opção -V tiver sido definida além -b, sqlcmd não relatará um erro se o nível de gravidade for inferior aos valores definidos usando -V. Os arquivos em lote do prompt de comando podem testar o valor de ERRORLEVEL e manipular o erro adequadamente. sqlcmd não relata erros para o nível de gravidade 10 (mensagens informativas).

Se o script sqlcmd contiver um comentário incorreto, erro de sintaxe ou estiver faltando uma variável de script, a ERRORLEVEL retornada será 1.

-m error_level

Controla quais mensagens de erro são enviadas para stdout. As mensagens que têm um nível de severidade maior ou igual a esse nível são enviadas. Quando esse valor é definido como -1, todas as mensagens, incluindo mensagens informativas, são enviadas. Não são permitidos espaços entre o -m e o -1. Por exemplo, -m-1 é válido e -m -1 não é.

Esta opção também define a variável de script sqlcmdSQLCMDERRORLEVEL. Esta variável tem um valor padrão de 0.

-V nível_de_severidade_do_erro

Controla o nível de gravidade usado para definir a variável ERRORLEVEL. Mensagens de erro com níveis de gravidade maiores ou iguais a esse valor definido ERRORLEVEL. Os valores inferiores a 0 são reportados como 0. Arquivos em lote e CMD podem ser usados para testar o valor da variável ERRORLEVEL.

Opções diversas

-um tamanho_do_pacote

Solicita um pacote de um tamanho diferente. Esta opção define o sqlcmd variável de script SQLCMDPACKETSIZE. packet_size deve ser um valor entre 512 e 32767. O padrão é 4096. Um tamanho de pacote maior pode melhorar o desempenho na execução de scripts que têm muitas instruções Transact-SQL entre comandos GO. Você pode solicitar um tamanho de pacote maior. No entanto, se a solicitação for negada, sqlcmd usará o padrão do servidor para o tamanho do pacote.

-c batch_terminator

Especifica o terminador de lote. Por padrão, os comandos são encerrados e enviados para o SQL Server digitando a palavra GO em uma linha por si só. Ao redefinir o terminador de lote, não utilize as palavras-chave reservadas Transact-SQL ou caracteres que tenham significado especial para o sistema operativo, mesmo que sejam precedidos por uma barra invertida.

-L[c]

Lista os computadores servidores configurados localmente e os nomes dos computadores servidores que estão transmitindo na rede. Este parâmetro não pode ser usado em combinação com outros parâmetros. O número máximo de computadores servidores que podem ser listados é 3000. Se a lista de servidores estiver truncada devido ao tamanho do buffer, uma mensagem de aviso será exibida.

Observação

Devido à natureza da transmissão em redes, sqlcmd podem não receber uma resposta oportuna de todos os servidores. Portanto, a lista de servidores retornados pode variar para cada invocação dessa opção.

Se o parâmetro opcional c for especificado, a saída aparecerá sem a linha de cabeçalho Servers: e cada linha do servidor será listada sem espaços à esquerda. Esta apresentação é denominada saída limpa. A saída limpa melhora o desempenho de processamento de linguagens de script.

-p[1]

Imprime estatísticas de desempenho para cada conjunto de resultados. A exibição a seguir é um exemplo do formato para estatísticas de desempenho:

Network packet size (bytes): n

x xact[s]:

Clock Time (ms.): total       t1  avg       t2 (t3 xacts per sec.)

Onde:

  • x = Número de transações processadas pelo SQL Server.
  • t1 = Tempo total para todas as transações.
  • t2 = Tempo médio para uma única transação.
  • t3 = Número médio de transações por segundo.

Todos os tempos são em milissegundos.

Se o parâmetro opcional 1 for especificado, o formato de saída das estatísticas estará no formato separado por dois pontos que pode ser importado facilmente para uma planilha ou processado por um script.

Se o parâmetro opcional for qualquer valor diferente de 1, um erro será gerado e sqlcmd será encerrado.

-X[1]

Desabilita comandos que podem comprometer a segurança do sistema quando sqlcmd é executado a partir de um arquivo em lotes. Os comandos desativados ainda são reconhecidos; sqlcmd emite uma mensagem de aviso e continua. Se o parâmetro opcional 1 for especificado, sqlcmd gerará uma mensagem de erro e, em seguida, será encerrado. Os seguintes comandos são desativados quando a opção -X é usada:

  • ED
  • !! comando

Se a opção -X for especificada, ela impedirá que variáveis de ambiente sejam passadas para sqlcmd. Ele também impede que o script de inicialização especificado usando a variável de script SQLCMDINI seja executado. Para obter mais informações sobre sqlcmd variáveis de script, consulte sqlcmd - Uso com variáveis de script.

-?

Exibe a versão do sqlcmd e um resumo de sintaxe de opções de sqlcmd.

Observação

No macOS, execute o comando sqlcmd '-?' (com aspas) em vez disso.

Comentários

As opções não precisam ser usadas na ordem mostrada na seção de sintaxe.

Observação

Se você usar a opção -i seguida por um ou mais parâmetros adicionais, deverá usar um espaço entre o parâmetro e o valor. Este é um problema conhecido no sqlcmd (Go).

Quando vários resultados são retornados, sqlcmd imprime uma linha em branco entre cada conjunto de resultados em um lote. Além disso, a mensagem <x> rows affected não aparece quando não se aplica à instrução executada.

Para usar sqlcmd interativamente, digite sqlcmd no prompt de comando com uma ou mais das opções descritas anteriormente neste artigo. Para obter mais informações, consulte Usar o utilitário sqlcmd

Observação

As opções -l, -Q, -Z ou -i fazem com que o sqlcmd saia após a execução.

O comprimento total da linha de comando do sqlcmd no ambiente de comando (por exemplo, cmd.exe ou bash), incluindo todos os argumentos e variáveis expandidas, é determinado pelo sistema operacional subjacente.

Precedência variável (baixa a alta)

  1. Variáveis ambientais ao nível do sistema
  2. Variáveis ambientais ao nível do utilizador
  3. Shell de comando (SET X=Y) definido no prompt de comando antes de executar sqlcmd
  4. sqlcmd -v X=Y
  5. :Setvar X Y

Observação

Para exibir as variáveis ambientais, no Painel de Controle , abra Sistema e selecione a guia Avançado.

Variáveis de script SQLCMD

Variável Opção relacionada R/W Padrão
SQLCMDUSER -U R ""
SQLCMDPASSWORD -P -- ""
SQLCMDSERVER -S R "DefaultLocalInstance"
SQLCMDWORKSTATION -H R "Nome do computador"
SQLCMDDBNAME -d R ""
SQLCMDLOGINTIMEOUT -l R/W "8" (segundos)
SQLCMDSTATTIMEOUT -t R/W "0" = esperar indefinidamente
SQLCMDHEADERS -h R/W "0"
SQLCMDCOLSEP -s R/W " "
SQLCMDCOLWIDTH -w R/W "0"
SQLCMDPACKETSIZE -a R "4096"
SQLCMDERRORLEVEL -m R/W 0
SQLCMDMAXVARTYPEWIDTH -y R/W "256"
SQLCMDMAXFIXEDTYPEWIDTH -Y R/W "0" = ilimitado
SQLCMDEDITOR R/W "edit.com"
SQLCMDINI R ""
SQLCMDUSEAAD -G R/W ""

SQLCMDUSER, SQLCMDPASSWORDe SQLCMDSERVER são definidos quando :Connect é usado.

R indica que o valor só pode ser definido uma vez durante a inicialização do programa.

R/W indica que o valor pode ser modificado usando o comando :setvar e os comandos subsequentes são influenciados pelo novo valor.

Comandos sqlcmd

Além de Transact-SQL instruções dentro de sqlcmd, os seguintes comandos também estão disponíveis:

GO [ contagem ]

:List

[:]RESET

:Error

[:]ED

:Out

[:]!!

:Perftrace

[:]QUIT

:Connect

[:]EXIT

:On Error

:r

:Help

:ServerList

:XML [ ON | OFF ]

:Setvar

:Listvar

Esteja ciente do seguinte ao usar comandos sqlcmd:

  • Todos os comandos sqlcmd, exceto GO, devem ser prefixados por dois pontos (:).

    Importante

    Para manter a compatibilidade retroativa com scripts osql existentes, alguns dos comandos são reconhecidos sem dois pontos, sinalizados pelo :.

  • comandos sqlcmd são reconhecidos somente se aparecerem no início de uma linha.

  • Todos os comandos sqlcmd não diferenciam maiúsculas de minúsculas.

  • Cada comando deve estar em uma linha separada. Um comando não pode ser seguido por uma instrução Transact-SQL ou outro comando.

  • Os comandos são executados imediatamente. Eles não são colocados no buffer de execução como são instruções Transact-SQL.

Editando comandos

[:]DE

Inicia o editor de texto. Este editor pode ser usado para editar o lote de Transact-SQL atual ou o último lote executado. Para editar o último lote executado, o comando ED deve ser digitado imediatamente após a conclusão da execução do último lote.

O editor de texto é definido pela variável de ambiente SQLCMDEDITOR. O editor padrão é Edit. Para alterar o editor, defina a variável de ambiente SQLCMDEDITOR. Por exemplo, para definir o editor para o Bloco de Notas da Microsoft, no prompt de comando, digite:

SET SQLCMDEDITOR=notepad

[:]REINICIAR

Limpa a cache de declarações.

:Lista

Imprime o conteúdo do cache de instruções.

Variáveis

:Setvar <var> [ "valor" ]

Define sqlcmd variáveis de script. As variáveis de script têm o seguinte formato: $(VARNAME).

Os nomes das variáveis não têm em conta a diferença entre maiúsculas e minúsculas.

As variáveis de script podem ser definidas das seguintes maneiras:

  • Implicitamente usando uma opção de linha de comando. Por exemplo, a opção -l define a variávelSQLCMDLOGINTIMEOUT sqlcmd.

  • Explicitamente usando o comando :Setvar.

  • Definindo uma variável de ambiente antes de executar sqlcmd.

Observação

A opção -X impede que variáveis de ambiente sejam passadas para sqlcmd.

Se uma variável definida usando :Setvar e uma variável de ambiente tiverem o mesmo nome, a variável definida usando :Setvar terá precedência.

Os nomes das variáveis não devem conter caracteres de espaço em branco.

Os nomes de variáveis não podem ter a mesma forma que uma expressão variável, como $(var).

Se o valor da cadeia de caracteres da variável de script contiver espaços em branco, coloque o valor entre aspas. Se um valor para uma variável de script não for especificado, a variável de script será descartada.

:Listvar

Exibe uma lista das variáveis de script que estão definidas no momento.

Observação

Somente as variáveis de script definidas por sqlcmd e aquelas definidas usando o comando :Setvar são exibidas.

Comandos de saída

:Erro <nome do arquivo> | STDERR | STDOUT

Redirecione toda a saída de erro para o arquivo especificado por nome de arquivo, para stderr ou para stdout. O comando :Error pode aparecer várias vezes em um script. Por padrão, a saída de erro é enviada para stderr.

  • nome do arquivo

    Cria e abre um arquivo que recebe a saída. Se o arquivo já existir, ele será truncado para zero bytes. Se o ficheiro não estiver disponível devido a permissões ou outros motivos, a saída não é alterada e é enviada para o último destino especificado ou padrão.

  • STDERR

    Alterna a saída de erro para o fluxo stderr. Se isso tiver sido redirecionado, o destino para o qual o fluxo foi redirecionado receberá a saída de erro.

  • STDOUT

    Alterna a saída de erro para o stream stdout. Se isso tiver sido redirecionado, o destino para o qual o fluxo foi redirecionado receberá a saída de erro.

:out <nome do arquivo> | STDERR | STDOUT

Cria e redireciona todos os resultados da consulta para o arquivo especificado por nome de arquivo, para stderr ou para stdout. Por padrão, a saída é enviada para stdout. Se o arquivo já existir, ele será truncado para zero bytes. O comando :Out pode aparecer várias vezes em um script.

:Perftrace <nome do arquivo> | STDERR | STDOUT

Cria e redireciona todas as informações de rastreamento de desempenho para o arquivo especificado por nome de arquivo, para stderr ou para stdout. Por padrão, a saída de rastreamento de desempenho é enviada para stdout. Se o arquivo já existir, ele será truncado para zero bytes. O comando :Perftrace pode aparecer várias vezes em um script.

Comandos de controle de execução

:On Error [ sair | ignorar ]

Define a ação a ser executada quando ocorre um erro durante a execução de script ou lote.

Quando a opção exit é usada, sqlcmd sai com o valor de erro apropriado.

Quando a opção ignore é usada, sqlcmd ignora o erro e continua executando o lote ou script. Por padrão, uma mensagem de erro é impressa.

[:]SAIR

Faz com que o sqlcmd saia.

[:]EXIT [ ( Declaração ) ]

Permite que você use o resultado de uma instrução SELECT como o valor de retorno de sqlcmd. Se for numérica, a primeira coluna da última linha de resultados é convertida em um inteiro de 4 bytes (longo). MS-DOS, Linux e macOS passam o byte inferior para o nível de erro do processo pai ou do sistema operativo. Windows 2000 e versões posteriores passam o inteiro completo de 4 bytes. A sintaxe é :EXIT(query).

Por exemplo:

:EXIT(SELECT @@ROWCOUNT)

Você também pode incluir o parâmetro :EXIT como parte de um arquivo em lotes. Por exemplo, no prompt de comando, digite:

sqlcmd -Q ":EXIT(SELECT COUNT(*) FROM '%1')"

O utilitário sqlcmd envia tudo entre parênteses (()) para o servidor. Se um procedimento armazenado do sistema selecionar um conjunto e retornar um valor, somente a seleção será retornada. A instrução :EXIT() sem nada entre parênteses executa todas as instruções anteriores no bloco e depois termina sem retornar um valor.

Quando uma consulta incorreta é especificada, sqlcmd é encerrado sem um valor de retorno.

Aqui está uma lista de formatos EXIT:

  • :EXIT

    Não executa o lote e, em seguida, fecha imediatamente e não retorna nenhum valor.

  • :EXIT( )

    Executa o lote e, em seguida, fecha e não retorna nenhum valor.

  • :EXIT(query)

    Executa o lote que inclui a consulta e, em seguida, fecha depois que ele retorna os resultados da consulta.

Se RAISERROR for usado em um script de sqlcmd e se um estado de 127 for gerado, sqlcmd fecha e retorna o ID da mensagem para o cliente. Por exemplo:

RAISERROR(50001, 10, 127)

Este erro faz com que o script sqlcmd termine e retorne a mensagem ID 50001 para o cliente.

Os valores de retorno -1 para -99 são reservados pelo SQL Server e sqlcmd define os seguintes valores de retorno adicionais:

Valor de retorno Descrição
-100 Erro encontrado antes de selecionar o valor de retorno.
-101 Nenhuma linha encontrada ao selecionar o valor de retorno.
-102 Ocorreu um erro de conversão ao selecionar o valor de retorno.

GO [contagem]

GO sinaliza o fim de um lote e a execução de quaisquer instruções de Transact-SQL em cache. O lote é executado várias vezes como lotes separados. Não é possível declarar uma variável mais de uma vez em um único lote.

Comandos diversos

:r <nome do arquivo>

Analisa instruções Transact-SQL adicionais e comandos de sqlcmd do arquivo especificado por nome de arquivo no cache de instruções. nome do ficheiro é lido relativamente ao diretório de arranque no qual sqlcmd foi executado.

Se o arquivo contiver instruções Transact-SQL que não sejam seguidas por GO, deverá inserir GO na linha que segue :r.

O ficheiro será lido e executado depois que um terminador de lote for encontrado. Você pode emitir vários comandos :r. O arquivo pode incluir qualquer comando sqlcmd, incluindo o terminador em lote GO.

Observação

A contagem de linhas exibida no modo interativo será aumentada em uma para cada comando :r encontrado. O comando :r aparece na saída do comando list.

:Lista de servidores

Lista os servidores configurados localmente e os nomes dos servidores que transmitem na rede.

:Ligar nome_servidor[\nome_instância] [-l tempo limite] [-U nome_utilizador [-P palavra-passe]]

Conecta-se a uma instância do SQL Server. Também fecha a conexão atual.

Opções de tempo limite:

Valor Comportamento
0 Espere para sempre
n>0 Aguarde e segundos

A variável de script SQLCMDSERVER reflete a conexão ativa atual.

Se de tempo limite não for especificado, o valor da variável SQLCMDLOGINTIMEOUT é usado como padrão.

Se apenas user_name for especificado (como uma opção ou como uma variável de ambiente), o usuário será solicitado a inserir uma senha. Os usuários não são avisados se as variáveis de ambiente SQLCMDUSER ou SQLCMDPASSWORD foram definidas. Se você não fornecer opções ou variáveis de ambiente, o modo de Autenticação do Windows será usado para entrar. Por exemplo, para se conectar a uma instância, instance1, do SQL Server, myserver, usando a segurança integrada, você usaria o seguinte comando:

:connect myserver\instance1

Para se conectar à instância padrão do myserver usando variáveis de script, você deve usar as seguintes configurações:

:setvar myusername test
:setvar myservername myserver
:connect $(myservername) $(myusername)

[:]!! comando

Executa comandos do sistema operacional. Para executar um comando do sistema operacional, inicie uma linha com dois pontos de exclamação (!!) seguido pelo comando do sistema operacional. Por exemplo:

:!! dir

Observação

O comando é executado no computador no qual sqlcmd está sendo executado.

:XML [ ATIVADO | DESLIGADO ]

Para obter mais informações, consulte de formato de saída XML e de formato de saída JSON neste artigo.

:Ajuda

Lista os comandos sqlcmd , juntamente com uma breve descrição de cada comando.

Nomes de arquivo sqlcmd

arquivos de entrada do sqlcmd podem ser especificados com a opção -i ou o comando :r. Os arquivos de saída podem ser especificados com a opção -o ou os comandos :Error, :Out e :Perftrace. A seguir estão algumas diretrizes para trabalhar com esses arquivos:

  • :Error, :Out e :Perftrace devem usar valores de de nome de arquivo separados. Se o mesmo nome de arquivo for usado, as entradas dos comandos podem ser misturadas.

  • Se um arquivo de entrada localizado em um servidor remoto for chamado de sqlcmd em um computador local e o arquivo contiver um caminho de arquivo de unidade, como :Out c:\OutputFile.txt, o arquivo de saída será criado no computador local e não no servidor remoto.

  • Os caminhos de arquivo válidos incluem: C:\<filename>, \\<Server>\<Share$>\<filename>e "C:\Some Folder\<file name>". Se houver um espaço no caminho, use aspas.

  • Cada nova sessão sqlcmd substitui arquivos existentes que têm os mesmos nomes.

Mensagens informativas

sqlcmd imprime qualquer mensagem informativa enviada pelo servidor. No exemplo a seguir, depois que as instruções Transact-SQL são executadas, uma mensagem informativa é impressa.

Inicie sqlcmd. Na linha de comandos do sqlcmd, digite a consulta:

USE AdventureWorks2022;
GO

Quando você pressiona ENTER, a seguinte mensagem informativa é impressa:

Changed database context to 'AdventureWorks2022'.

Formato de saída de consultas Transact-SQL

sqlcmd imprime primeiro um cabeçalho de coluna que contém os nomes de coluna especificados na lista de seleção. Os nomes das colunas são separados usando o caractere SQLCMDCOLSEP. Por padrão, este é um espaço. Se o nome da coluna for menor que a largura da coluna, a saída será preenchida com espaços até à próxima coluna.

Esta linha é seguida por uma linha separadora que é uma série de caracteres de traço. A saída a seguir mostra um exemplo.

Inicie sqlcmd. Na linha de comando sqlcmd, digite a consulta:

USE AdventureWorks2022;
SELECT TOP (2) BusinessEntityID, FirstName, LastName
FROM Person.Person;
GO

Quando você pressiona ENTER, o seguinte conjunto de resultados é retornado.

BusinessEntityID FirstName    LastName
---------------- ------------ ----------
285              Syed         Abbas
293              Catherine    Abel
(2 row(s) affected)

Embora a coluna BusinessEntityID tenha apenas quatro caracteres, ela foi expandida para acomodar o nome da coluna mais longa. Por padrão, a saída é encerrada em 80 caracteres. Essa largura pode ser alterada usando a opção -w ou definindo a variável de script SQLCMDCOLWIDTH.

Formato de saída XML

A saída XML que resulta de uma cláusula FOR XML é emitida, sem formatação, num fluxo contínuo.

Quando você espera uma saída XML, use o seguinte comando: :XML ON.

Observação

sqlcmd retorna mensagens de erro no formato usual. As mensagens de erro também são saídas no fluxo de texto XML em formato XML. Usando :XML ON, sqlcmd não exibe mensagens informativas.

Para definir o modo XML como desativado, use o seguinte comando: :XML OFF.

O comando GO não deve aparecer antes que o comando :XML OFF seja emitido, porque o comando :XML OFF muda o sqlcmd de volta para saída em formato orientado a linhas.

Os dados XML (transmitidos) e os dados do conjunto de linhas não podem ser misturados. Se o comando :XML ON não tiver sido emitido antes que uma instrução Transact-SQL que gera fluxos XML seja executada, a saída será distorcida. Depois que o comando :XML ON tiver sido emitido, você não poderá executar instruções Transact-SQL que geram conjuntos de linhas regulares.

Observação

O comando :XML não suporta a instrução SET STATISTICS XML.

Formato de saída JSON

Quando você espera saída JSON, use o seguinte comando: :XML ON. Caso contrário, a saída inclui o nome da coluna e o texto JSON. Esta saída não é JSON válida.

Para definir o modo XML como desativado, use o seguinte comando: :XML OFF.

Para obter mais informações, consulte XML Output Format neste artigo.

Usar a autenticação do Microsoft Entra

Exemplos de utilização da autenticação Microsoft Entra:

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

Práticas recomendadas do sqlcmd

Use as seguintes práticas para ajudar a maximizar a segurança e a eficiência.

  • Utilize a segurança integrada.

  • Use -X[1] em ambientes automatizados.

  • Proteja os arquivos de entrada e saída usando as permissões apropriadas do sistema de arquivos.

  • Para aumentar o desempenho, faça o máximo possível em uma sessão de sqlcmd, em vez de em várias sessões.

  • Defina valores de tempo limite para execução em lote ou consulta mais altos do que você espera que seja necessário para executar o lote ou consulta.

Use as seguintes práticas para ajudar a maximizar a correção:

  • Use -V 16 para registrar quaisquer mensagens de nível de gravidade 16 . As mensagens de gravidade 16 indicam erros gerais que podem ser corrigidos pelo usuário.

  • Verifique o código de saída e DOS ERRORLEVEL variável após o encerramento do processo. sqlcmd retorna 0 normalmente, caso contrário, ele define o ERRORLEVEL conforme configurado por -V. Em outras palavras, não se deve esperar que o valor de ERRORLEVEL seja o mesmo que o número de erro relatado pelo SQL Server. O número do erro é um valor específico do SQL Server correspondente à função do sistema @@ERROR. ERRORLEVEL é um valor específico dosqlcmd para indicar por que sqlcmd encerrado e seu valor é influenciado pela especificação de -b argumento de linha de comando.

O uso de -V 16 em combinação com a verificação do código de saída e DOS ERRORLEVEL pode ajudar a detetar erros em ambientes automatizados, especialmente em controlos de qualidade antes de um lançamento de produção.

Conteúdo relacionado