Compartilhar via

utilitário sqlcmd

  • Artigo

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)Banco de Dados SQL no Microsoft Fabric

O utilitário do sqlcmd permite que você insira as instruções Transact-SQL, os procedimentos do sistema e os arquivos de script usando vários modos:

  • No prompt de comando.
  • No Editor de Consulta no 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 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.

Descobrir qual versão foi instalada

Há duas versões do sqlcmd:

  • O go-mssqldb baseado em , à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.8.2

Verificar a versão

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

Importante

Instalar sqlcmd (Go) por meio de um gerenciador de pacotes substitui sqlcmd (ODBC) por sqlcmd (Go) em seu caminho de ambiente. Você deve fechar e reabrir as sessões de linha de comando atuais para que essa alteração entre em vigor. O sqlcmd (ODBC) não é removido e ainda pode ser usado especificando o caminho completo para o executável. Você também pode atualizar sua variável de PATH para indicar qual tem precedência. Para fazer isso no Windows 11, abra Configurações do sistema e acesse Sobre >Configurações avançadas do sistema. Quando as Propriedades do Sistema forem abertas, 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 no qual o sqlcmd (Go) for salvo (C:\Program Files\sqlcmd é o padrão) estiver listado antes de C:\Program Files\Microsoft SQL Server\<version>\Tools\Binn, o sqlcmd (Go) será usado. Você pode inverter a ordem para tornar o sqlcmd (ODBC) o padrão novamente.

Baixar e instalar o sqlcmd

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

winget (CLI do gerenciador de pacotes do Windows)

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

  2. Execute o comando a seguir para instalar o sqlcmd (Go).

    winget install sqlcmd

Chocolatey

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

  2. Execute o comando a seguir para instalar o sqlcmd (Go).

    choco install sqlcmd

Download direto

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

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

Pré-instalado

Azure Cloud Shell

Você pode experimentar o utilitário sqlcmd do Azure Cloud Shell, que 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 o Modo SQLCMD na lista suspensa Menu de Consulta da navegação superior.

O SSMS usa o Microsoft .NET Framework SqlClient para execução nos modos regular e SQLCMD no Editor de Consultas. Quando o sqlcmd é executado na linha de comando, o 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 a sintaxe e o uso do sqlcmd, confira sintaxe do sqlcmd ODBC.

Alterações significativas do sqlcmd (ODBC)

Várias opções e comportamentos são alterados no utilitário sqlcmd (Go). Para obter a lista mais atualizada de sinalizadores ausentes para compatibilidade retroativa, visite a discussão no GitHub sobre Implementação prioritária de sinalizadores de compatibilidade retroativa.

  • Em versões anteriores do sqlcmd (Go), a opção -P foi removida temporariamente, 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 podia digitar a senha para concluir uma conexão

  • -r requer um argumento 0 ou 1

  • O interruptor -R foi removido.

  • O interruptor -I foi removido. Para desativar o comportamento de identificadores entre aspas, adicione SET QUOTED IDENTIFIER OFF aos seus scripts.

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

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

  • -u O arquivo de saída Unicode gerado tem o BOM (marca de ordem de byte) Little-Endian UTF-16 gravado nele.

  • Alguns comportamentos que foram mantidos para manter a compatibilidade com OSQL podem ter sido 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 ou aspas abertos 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. No momento, não há suporte para pipes nomeados no driver go-mssqldb.

Aprimoramentos

  • :Connect agora tem um parâmetro opcional -G 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 fornecido, será usada a segurança integrada ou a autenticação do SQL Server, dependendo da presença do parâmetro de nome de usuário -U.

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

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

Opções de linha de comando

A tabela a seguir lista as opções de linha de comando disponíveis no sqlcmd e quais sistemas operacionais eles dão suporte.

Opção de linha de comando Com suporte no Windows Com suporte no Linux e no macOS
Opções relacionadas ao logon
-A Sim Não
-C Sim Sim
-d db_name Sim Sim
-D Sim Sim
-l login_timeout Sim Sim
-E Sim Sim
-g Sim Sim
-G Sim Sim
-H workstation_name Sim Sim
-j Sim Sim
-K application_intent Sim Sim
-M multisubnet_failover Sim Sim
-N Sim Sim
-P password Sim Sim
-S [protocolo:]servidor[\nome_instância][,porta] Sim Sim
-U login_id Sim Sim
-z new_password Sim Sim
-Z new_password Sim Sim
Opções de entrada/saída
-f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage] Sim Sim
-i input_file[,input_file2...] Sim Sim
-o output_file Sim Sim
-r[0 | 1] Sim Sim
-R Sim Sim
-u Sim Sim
Opções de execução de consulta
-e Sim Sim
-I Sim Sim
-q "cmdline query" Sim Sim
-Q "cmdline query" Sim Sim
-t query_timeout Sim Sim
-v var = value [ var = value... ] Sim Não
-x Sim Sim
Opções de formato
-h headers Sim Sim
-k [1 | 2] Sim Sim
-s col_separator Sim Sim
-w screen_width Sim Sim
-W Sim Sim
-y variable_length_type_display_width Sim Sim
-Y fixed_length_type_display_width Sim Sim
Opções de relatório de erros
-b Sim Sim
-m error_level Sim Sim
-V error_severity_level Sim Sim
Opções diversas
-a packet_size Sim Sim
-c batch_terminator Sim Sim
-L[c] Sim Não
-p[1] Sim Sim
-X[1] Sim Sim
-? Sim Sim

-A

Aplica-se a: Somente Windows. Não há suporte para Linux e macOS.

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

Observação

Para obter informações sobre como fazer uma DAC (conexão de administrador dedicada) no macOS ou linux, consulte Diretrizes de programação.

-c

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

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

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

-d db_name

Emite uma instrução USE <db_name> ao iniciar o sqlcmd. Essa opção define a variável de script do sqlcmdSQLCMDDBNAME. Esse parâmetro especifica o banco de dados inicial. O padrão é a propriedade do banco de dados padrão de seu logon. Se o banco de dados não existir, será gerada uma mensagem de erro e o sqlcmd será encerrado.

-d

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

Observação

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

-l login_timeout

Especifica o número de segundos antes que um logon do sqlcmd no driver ODBC expire quando você tentar se conectar a um servidor. Essa opção define a variável de script do sqlcmdSQLCMDLOGINTIMEOUT. O tempo limite padrão de logon do sqlcmd é de oito 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, é recomendável um valor de tempo limite de pelo menos 30 segundos. O tempo limite do logon precisa ser um número entre 0 e 65534. Se o valor fornecido não for numérico ou não estiver nesse intervalo, o sqlcmd vai 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 um nome de usuário e uma senha para entrar no SQL Server. Por padrão, sem a especificação de -E , o sqlcmd usa a opção de conexão confiável.

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

Observação

Para obter mais informações sobre como fazer conexões confiáveis que usam a autenticação integrada de um cliente Linux ou macOS, consulte Usando a Autenticação Integrada.

-g

Define a configuração de Criptografia de Coluna como Enabled. Para obter mais informações, consulte Always Encrypted. Há suporte apenas para as chaves mestras armazenadas no Repositório de Certificados do Windows. A opção -g exige, no mínimo, o sqlcmd versão 13.1. Para determinar a 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 está autenticado com a autenticação do Microsoft Entra. Essa opção define a variável de script do sqlcmdSQLCMDUSEAAD = true. A opção -G exige, no mínimo, o sqlcmd versão 13.1. Para determinar a versão, execute sqlcmd -?. Para obter mais informações, confira Conectar ao Banco de Dados SQL ou Azure Synapse Analytics usando a autenticação do Microsoft Entra. A opção -A não é compatível 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 tem suporte no Linux nem no macOS. A autenticação integrada do Microsoft Entra requer o 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, confira Autenticação do Microsoft Entra em sqlcmd.

-H workstation_name

Um nome de estação de trabalho. Essa opção define a variável de script do sqlcmdSQLCMDWORKSTATION. O nome da estação de trabalho é 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 do sqlcmd .

-j

Imprime mensagens de erro brutas na tela.

-K intenção_do_aplicativo

Declara o tipo de carga de trabalho de aplicativo ao conectar-se a um servidor. O único valor com suporte no momento é ReadOnly. Se -K não for especificado, o sqlcmd não dará suporte à conectividade com uma réplica secundária em um grupo de disponibilidade. Para obter mais informações, confira Réplicas secundárias ativas: réplica secundária para leitura (Grupos de Disponibilidade Always On).

Observação

-K não há suporte no SLES (SUSE Linux Enterprise Server). No entanto, você pode especificar a ApplicationIntent=ReadOnly palavra-chave em um arquivo DSN passado para sqlcmd. Para obter mais informações, consulte suporte de DSN no sqlcmd e bcp mais adiante neste artigo.

Para obter mais informações, consulte Alta disponibilidade e recuperação de desastre no Linux e no macOS.

-M multisubnet_failover

Sempre especifique -M ao se conectar ao ouvinte do grupo de disponibilidade de um grupo de disponibilidade do SQL Server ou a uma instância de cluster de failover do SQL Server. -M proporciona a detecção mais rápida e a conexão com o servidor (atualmente) ativo. Se -M não estiver especificado, -M estará desativado. Para saber mais, veja Ouvintes, Conectividade do Cliente e Failover de Aplicativos, Criação e Configuração de Grupos de Disponibilidade (SQL Server), Failover Clustering e Grupos de Disponibilidade Always On (SQL Server) e Secundárias Ativas: Réplicas Secundárias Legíveis (Grupos de Disponibilidade Always On).

Observação

-M não há suporte no SLES (SUSE Linux Enterprise Server). No entanto, você pode especificar a MultiSubnetFailover=Yes palavra-chave em um arquivo DSN passado para sqlcmd. Para obter mais informações, consulte suporte de DSN no sqlcmd e bcp mais adiante neste artigo.

Para obter mais informações, consulte Alta disponibilidade e recuperação de desastre no Linux e no macOS.

-n

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

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

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

Observação

No Linux e no macOS, [s|m|o] foram adicionados ao sqlcmd 18.0.

-P senha

Uma senha especificada pelo usuário. As senhas diferenciam maiúsculas de minúsculas. Se a opção -U for usada, a opção -P não será usada e a SQLCMDPASSWORD variável de ambiente não estiver definida, o sqlcmd solicitará uma senha ao usuário. Não recomendamos o uso da 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 de -P deve ser considerado inseguro. Evite fornecer a senha na linha de comando. Como alternativa, use a variável de ambiente SQLCMDPASSWORD ou insira de modo interativo a senha omitindo a opção -P.

Recomendamos usar uma senha forte.

A solicitação de senha é exibida ao imprimir a solicitação de senha no console, como a seguir: Password:

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

A variável de ambiente SQLCMDPASSWORD permite que você defina uma senha padrão para a sessão atual. Assim, senhas não precisam ser embutidas em código nos arquivos em lote. O exemplo a seguir define primeiro a variável SQLCMDPASSWORD no prompt de comando e acessa o utilitário sqlcmd.

No prompt de comando, digite o seguinte. Substitua <password> por uma senha válida.

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

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

Observação

A OSQLPASSWORD variável de ambiente é mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDPASSWORD tem precedência em relação à variável de ambiente OSQLPASSWORD. Isso significa que o sqlcmd e osql podem ser usados próximos um do outro sem interferência. Os scripts antigos continuam funcionando.

Será gerada uma mensagem de erro se a opção -P for usada com a opção -E.

Será gerada uma mensagem de erro se a opção -P for acompanhada de mais de um argumento e o programa será encerrado.

Uma senha contendo caracteres especiais pode gerar uma mensagem de erro. Você deve fazer o escape de caracteres especiais ao usar -P ou usar a variável de ambiente SQLCMDPASSWORD como alternativa.

No Linux e no macOS, quando usado com a opção -G sem -U, -P especifica um arquivo que contém um token de acesso (v17.8+). O arquivo de token deve estar no formato UTF-16LE (sem BOM).

Tokens de acesso podem ser obtidos por meio de vários métodos. Você deve garantir que o token de acesso esteja correto byte para byte, pois ele é enviado as-is. A seguir está um comando de exemplo que obtém um token de acesso. O comando usa os comandos da CLI do Azure e Linux e salva-os em um arquivo no formato adequado. Se a codificação padrão do sistema ou terminal não for ASCII ou UTF-8, talvez seja necessário ajustar as iconv opções. Garanta a proteção cuidadosa do arquivo resultante e exclua-o quando não for mais necessário.

az account get-access-token --resource https://database.windows.net --output tsv | cut -f 1 | tr -d '\n' | iconv -f ascii -t UTF-16LE > /tmp/tokenFile

-S [protocol:]server[\instance_name][,port]

Especifica a instância do SQL Server à qual você deseja se conectar. Ele define a variável de script do sqlcmdSQLCMDSERVER.

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

Oprotocolo pode ser tcp (TCP/IP), lpc (memória compartilhada) ou np (pipes nomeados).

Se você não especificar um server_name[\instance_name] ao iniciar o sqlcmd, o SQL Server verifica se há uma variável de ambiente SQLCMDSERVER e usa-a.

Observação

A OSQLSERVER variável de ambiente é mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDSERVER tem precedência em relação à variável de ambiente OSQLSERVER. Isso significa que o sqlcmd e osql podem ser usados próximos um do outro sem interferência. Os scripts antigos continuam funcionando.

O driver ODBC no Linux e no macOS requer -S. O único valor de protocolo válido é tcp.

-U login_id

O nome de logon ou o nome de usuário de banco de dados independente. Para usuários de banco de dados independente, é necessário fornecer a opção de nome de banco de dados (-d).

Observação

A OSQLUSER variável de ambiente é mantida para compatibilidade com versões anteriores. A variável de ambiente SQLCMDUSER tem precedência em relação à variável de ambiente OSQLUSER. Isso significa que o sqlcmd e osql podem ser usados próximos um do outro sem interferência. Os scripts antigos continuam funcionando.

Se as opções -U ou -P não forem especificadas, o sqlcmd tentará se conectar usando o modo de Autenticação do Windows. A autenticação se baseia na conta do Windows do usuário que está executando o sqlcmd.

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

-z new_password

Altere a senha. Substitua <oldpassword> pela senha antiga e <newpassword> pela nova senha.

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

-Z new_password

Altere a senha e saia. Substitua <oldpassword> pela senha antiga e <newpassword> pela nova senha.

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

Opções de entrada/saída

-f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]

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 instalada no Windows.

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

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

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

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

  • Assume-se que arquivos de entrada múltiplos tenham a mesma página de código. Arquivos de entrada Unicode e não Unicode podem ser misturados.

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

Observação

No Linux, o número da página de código é um valor numérico que especifica uma página de código do Linux instalada (disponível desde 17.5.1.1).

-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ço entre nomes de arquivos. O sqlcmd verificará primeiro se todos os arquivos especificados existem. Se um ou mais arquivos não existirem, o sqlcmd será encerrado. As opções -i e -Q/-q são mutualmente exclusivas.

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. Esse é 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 arquivos que contêm espaços devem estar entre aspas.

Essa 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 output_file

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

Se -u for especificado, output_file será armazenado no formato Unicode. Se o nome do arquivo não for válido, uma mensagem de erro será gerada e o sqlcmd será encerrado. O sqlcmd não dá suporte à gravação simultânea de vários processos sqlcmd no mesmo arquivo. A saída de arquivo está corrompida ou é incorreta. A opção -f também é relevante para formatos de arquivo. Esse arquivo será criado se não existir. Um arquivo com o mesmo nome de uma sessão sqlcmd anterior será substituído. O arquivo aqui especificado 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 arquivos que contêm espaços devem estar entre aspas.

-r[0 | 1]

Redireciona a saída da mensagem de erro para a tela (stderr). Se você não especificar um parâmetro ou se especificar 0, serão redirecionadas somente mensagens de erro com nível de severidade 11 ou acima disso. Se você especificar 1, serão redirecionadas todas as saídas de mensagens de erro inclusive PRINT. Essa opção não terá efeito se você usar -o. Por padrão, mensagens são enviadas para stdout.

Observação

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

-R

Aplicável a: ODBC sqlcmd apenas.

Faz com que o sqlcmd localize colunas numéricas, de moeda, de data e de 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.

Observação

No Linux e no macOS, -R atualmente só usa a formatação en_US (inglês dos EUA).

-U

Especifica se output_file é armazenado no formato Unicode, independentemente do formato de 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) Little-Endian UTF-16 gravada nele.

Opções de execução de consultas

-E

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

-Eu

Aplicável a: ODBC sqlcmd apenas.

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

Observação

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

-q "cmdline query"

Executa uma consulta quando o sqlcmd é iniciado, mas não sai do sqlcmd quando a consulta é concluída. Várias consultas delimitadas por ponto-e-vírgula podem ser executadas. Use aspas na consulta, conforme o 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 em caso de erro. -b é descrito em outro lugar neste artigo.

-Q "cmdline query"

Executa uma consulta quando o sqlcmd é iniciado e fecha o sqlcmdimediatamente. Podem ser executadas consultas separadas por múltiplos pontos e vírgulas.

Use aspas na consulta, conforme o 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 em caso de erro. -b é descrito em outro lugar neste artigo.

-t query_timeout

Especifica quanto segundos faltam para que um comando (ou instrução Transact-SQL) atinja o tempo limite. Essa opção define a variável de script do sqlcmdSQLCMDSTATTIMEOUT. Se um valor de query_timeout não for especificado, o comando não atingiu o tempo limite. O query_timeout deve ser um número entre 1 e 65534. Se o valor fornecido não for numérico ou não estiver nesse intervalo, o 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... ]

Aplica-se a: Somente Windows. Não há suporte para Linux e macOS.

Cria uma variável de script do sqlcmd que possa ser usada em um script do sqlcmd.

Se o valor contiver espaços, mantenha-o entre aspas. Você pode especificar vários valores <var>="<value>". Se houver erros em algum dos valores especificados, o sqlcmd vai gerar uma mensagem de erro e será encerrado.

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 o sqlcmd ignore 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 headers

Especifica o número de linhas a imprimir entre os cabeçalhos de coluna. O padrão é imprimir títulos uma vez para cada conjunto de resultados de consulta. Essa opção define a variável de script do sqlcmdSQLCMDHEADERS. Use -1 para especificar que os cabeçalhos não sejam impressos. Qualquer valor inválido faz com que o sqlcmd gere uma mensagem de erro e seja encerrado.

-k [1 | 2]

Remove todos os caracteres de controle, como tabulações e caracteres de nova linha, da saída. Esse parâmetro preserva a formatação de 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 do separador de coluna. O padrão é um espaço em branco. Essa opção define a variável de script do sqlcmdSQLCMDCOLSEP. Para usar caracteres com um significado especial para o sistema operacional como, por exemplo, E comercial (&) ou ponto e vírgula (;), use-os entre aspas ("). O separador de coluna pode ser qualquer caractere de 8 bits.

-w screen_width

Especifica a largura de tela para saída. Essa opção define a variável de script do sqlcmdSQLCMDCOLWIDTH. A largura da coluna precisa ser um número maior que 8 e menor que 65536. Se a largura da coluna especificada não estiver nesse intervalo, o sqlcmd vai gerar uma mensagem de erro. A largura padrão é 80 caracteres. Quando uma linha de saída excede a largura de coluna especificada, ela inclui a próxima linha.

-w

Essa opção remove espaços à direita de uma coluna. Use essa opção juntamente com a opção -s ao preparar dados a serem exportados para outro aplicativo. Não é possível usar com as opções -y ou -Y.

-y variable_length_type_display_width

Define a variável de script sqlcmdSQLCMDMAXVARTYPEWIDTH. O padrão é 256. Ele limita o número de caracteres retornados para os tipos de dados com comprimento variável grande:

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

UDTs podem ter comprimento fixo dependendo da implementação. Se esse tamanho de UDT de tamanho fixo for mais curto que display_width, o valor do UDT retornado não será afetado. Porém, se o tamanho for mais longo que display_width, a saída será truncada.

Cuidado

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 fixed_length_type_display_width

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

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

Opções de relatório de erros

-b

Especifica que o sqlcmd é encerrado e retorna um valor DOS ERRORLEVEL em caso de erro. O valor retornado à variável ERRORLEVEL será 1 quando a mensagem de erro do SQL Server tiver um nível de gravidade maior que 10. Caso contrário, o valor retornado será 0. Se a opção -V estiver definida, além de -b, o sqlcmd não relatará um erro se o nível de severidade for menor do que os valores definidos usando -V. Arquivos em lote do prompt de comando podem testar o valor de ERRORLEVEL e tratar o erro adequadamente. Osqlcmd não relata erros para o nível de severidade 10 (mensagens informativas).

Se o script sqlcmd tiver um comentário incorreto, erro de sintaxe ou se estiver sem uma variável de script, ERRORLEVEL retornará 1.

-m nível_de_erro

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

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

-V error_severity_level

Controla o nível de severidade usado para definir a variável ERRORLEVEL. Mensagens de erro com níveis de severidade maiores ou iguais a este valor definido por ERRORLEVEL. Valores menores que 0 são reportados como 0. Podem ser usados arquivos de lote e CMD para testar o valor da variável ERRORLEVEL.

Opções diversas

-a packet_size

Exige um pacote de tamanho diferente. Essa opção define a variável de script do sqlcmdSQLCMDPACKETSIZE. packet_size precisa ser um valor entre 512 e 32767. O padrão é 4096. Um tamanho de pacote maior pode melhorar o desempenho da execução de scripts que tenham muitas instruções Transact-SQL entre comandos GO. Pode-se solicitar um tamanho de pacote maior. Porém, se a solicitação for negada, o sqlcmd usará o padrão de servidor para tamanho de pacote.

-c batch_terminator

Especifica o terminador de lote. Por padrão, os comandos são encerrados e enviados para o SQL Server ao digitar a palavra GO sozinha em uma linha. Ao redefinir o terminador de lote, não use palavras-chave reservadas do Transact-SQL ou caracteres que tenham um significado especial para o sistema operacional, mesmo que elas sejam precedidas por uma barra invertida.

-L[c]

Aplica-se a: Somente Windows. Não há suporte para Linux e macOS.

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

Observação

Devido à natureza da difusão em redes, sqlcmd pode 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 de servidor será listada sem espaços à esquerda. Esta apresentação é conhecida como saída limpa. A saída limpa melhora o desempenho de processamento das linguagens de script.

-p[1]

Imprime estatísticas de desempenho para cada conjunto de resultados. A tela a seguir é um exemplo do formato das estatísticas de desempenho:

Network packet size (bytes): n

x xact[s]:

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

Em que:

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

Todos os tempos estão em milissegundos.

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

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

-X[1]

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

  • ED
  • !!comando

Se for especificada a opção -X, isso impedirá que as variáveis de ambiente sejam transmitidas para o sqlcmd. Isso evita também que o script de inicialização especificado usando a variável de script SQLCMDINI seja executado. Para obter mais informações sobre as variáveis de script do sqlcmd, confira sqlcmd – Usar o sqlcmd com variáveis de script.

-?

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

Observação

No macOS, execute 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. Esse é um problema conhecido no sqlcmd (Go).

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

Para usar o 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 seja fechado após a execução.

O tamanho 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, é aquele determinado pelo sistema operacional subjacente.

Precedência das variáveis (da mais baixa para a mais alta)

  1. Variáveis de ambiente do nível de sistema
  2. Variáveis ambientais do nível de usuário.
  3. Shell de comando (SET X=Y) definido no prompt de comando antes da execução do sqlcmd
  4. sqlcmd -v X=Y
  5. :Setvar X Y

Observação

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

Variáveis de script do sqlcmd

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

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

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

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

Comandos sqlcmd

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

  • GO [ <count> ]
  • :List
  • [:]RESET
  • :Error
  • [:]ED1
  • :Out
  • [:]!!
  • :Perftrace
  • [:]QUIT
  • :Connect
  • [:]EXIT
  • :On Error
  • :r
  • :Help
  • :ServerList1
  • :XML [ ON | OFF ]1
  • :Setvar
  • :Listvar

1 Não há suporte para Linux ou macOS.

Lembre-se do seguinte ao usar comandos sqlcmd :

  • Todos os comandos do sqlcmd, exceto GO, precisam ser prefixados com dois-pontos (:).

    Importante

    Para manter a compatibilidade com versões anteriores de scripts osql existentes, alguns dos comandos serão reconhecidos por :.

  • Os comandossqlcmd serão reconhecidos apenas 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 nem por outro comando.

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

Comandos de edição

[:]ED

Inicie o editor de textos. Esse editor pode ser usado para editar o lote Transact-SQL atual ou o último lote executado. Para editar o último lote executado, o comando ED deve ser digitado imediatamente depois 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 como o Microsoft Notepad, no prompt de comando, digite:

SET SQLCMDEDITOR=notepad

[:]RESET

Limpa o cache de declarações.

:List

Imprime o conteúdo do cache de instrução.

Variáveis

:Setvar <var> [ "value" ]

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

Nomes de variáveis não diferenciam maiúsculas de minúsculas.

Variáveis de script podem ser definidas da seguinte forma:

  • Implicitamente usando uma opção de linha de comando. Por exemplo, a opção -l define a variável SQLCMDLOGINTIMEOUTsqlcmd.
  • Explicitamente, usando o comando :Setvar .
  • Definindo uma variável de ambiente antes de executar o sqlcmd.

Observação

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

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

Nomes de 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 tiver espaços em branco, use aspas. Se não for especificado um valor para uma variável de script, a variável de script será removida.

:Listvar

Exibe uma lista das variáveis de script definidas atualmente.

Observação

Somente variáveis de script definidas pelo sqlcmd e variáveis definidas usando o :Setvar comando 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 filename, para stderr ou para stdout. O comando :Error pode aparecer várias vezes em um script. Por padrão, saída de erro é enviada para stderr.

  • Filename

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

  • STDERR

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

  • STDOUT

    Alterna a saída de erro para o fluxo stdout. Se houver redirecionamento, o destino para o qual o fluxo foi redirecionado receberá a saída de erro.

:Out <filename> | STDERR | STDOUT

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

:Perftrace <filename> | STDERR | STDOUT

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

Comandos de controle de execução

:On Error [ exit | ignore ]

Define a ação a ser executada no caso de um erro durante a execução de script ou em lote.

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

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

[:]QUIT

Faz com que sqlcmd saia.

[:]EXIT [ ( statement ) ]

Permite que você use o resultado de uma instrução SELECT como o valor retornado de sqlcmd. Se numérico, a primeira coluna da última linha do resultado será convertida em um inteiro de 4 bytes (longo). O MS-DOS, o Linux e o macOS transmitem o byte baixo para o processo pai ou para o nível de erro do sistema operacional. O Windows 2000 e versões posteriores transmitem todo o inteiro de 4 bytes. A sintaxe é :EXIT(query).

Por exemplo:

:EXIT(SELECT @@ROWCOUNT)

É possível incluir também o parâmetro :EXIT como parte de um arquivo em lote. Por exemplo, no prompt de comando, digite:

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

O utilitário sqlcmd envia tudo entre os parênteses (()) para o servidor. Se um procedimento armazenado de sistema selecionar um conjunto e retornar um valor, somente a seleção será retornada. A instrução :EXIT() sem nada entre os parênteses executa tudo que a precede no lote e então é encerrada sem um valor de retorno.

Quando uma consulta incorreta é especificada, o sqlcmd é encerrado sem um valor retornado.

Aqui está uma lista de formatos EXIT:

  • :EXIT

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

  • :EXIT( )

    Executa o lote e então sai imediatamente e não retorna valor algum.

  • :EXIT(query)

    Executa o lote de comandos que inclui a consulta e, em seguida, encerra após retornar os resultados da consulta.

Se RAISERROR for usado em um script do sqlcmd e for acionado um estado de 127, o sqlcmd encerrará e retornará o ID da mensagem para o cliente. Por exemplo:

RAISERROR(50001, 10, 127)

Esse erro fará com que o script do sqlcmd seja encerrado e retorne a ID de mensagem 50001 ao cliente.

Os valores retornados -1 a -99 são reservados pelo SQL Server e o sqlcmd define os seguintes valores retornados adicionais:

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

GO [count]

GO sinaliza tanto o término de um lote quanto a execução de qualquer instrução Transact-SQL em cache. O lote é executado várias vezes como lotes separados. Você não pode declarar uma variável mais de uma vez em um lote.

Comandos variados

:r <filename>

Analisa instruções Transact-SQL adicionais e comandos sqlcmd do arquivo especificado pelo nome do arquivo no cache de instruções. filename é lido em relação ao diretório de inicialização no qual o sqlcmd foi executado.

Se o arquivo contiver instruções Transact-SQL que não são seguidas por GO, insira GO na linha após :r.

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

Observação

A contagem de linhas exibida no modo interativo é aumentada em um para cada :r comando encontrado. O comando :r aparece na saída do comando de lista.

:ListaDeServidores

Lista os servidores configurados localmente e os nomes dos servidores que estão transmitindo na rede.

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]]

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

Opções de tempo limite:

Valor Comportamento
0 Esperar para sempre
n>0 Esperar por n segundos

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

Se timeout não for especificado, o valor da variável SQLCMDLOGINTIMEOUT será o padrão.

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

:connect myserver\instance1

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

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

[:]!! comando

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

:!! dir

Observação

O comando é executado no computador em que o sqlcmd está sendo executado.

:XML [ ON | OFF ]

Para saber mais, confira Formato de saída XML e Formato de saída JSON neste artigo.

:Ajuda

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

Nomes de arquivos sqlcmd

Arquivos de entrada dosqlcmd 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 algumas diretrizes sobre como trabalhar com esses arquivos:

  • :Error, :Oute :Perftrace deve usar valores de nome de arquivo separados. Se o mesmo nome de arquivo for usado, as entradas dos comandos poderão ser intermixadas.

  • Se um arquivo de entrada em um servidor remoto for chamado do sqlcmd em um computador local e o arquivo tiver 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.

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

  • Cada nova sessão do sqlcmd substitui os arquivos com nomes iguais.

Mensagens informativas

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

Inicie o sqlcmd. No prompt de comando 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 das consultas do Transact-SQL

Osqlcmd imprime, em primeiro lugar, um cabeçalho de coluna com os nomes de coluna especificados na lista de seleção. Os nomes de coluna são separados usando o caractere SQLCMDCOLSEP. Por padrão, esse é um espaço. Se o nome de coluna for mais curto do que a largura de coluna, a saída será preenchida com espaços até a coluna seguinte.

Essa linha é seguida por uma linha divisória formada por uma série de traços. A saída a seguir mostra um exemplo.

Inicie o sqlcmd. No prompt de comando do sqlcmd, digite a consulta:

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

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

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

Embora a BusinessEntityID coluna tenha apenas quatro caracteres de largura, ela é expandida para acomodar o nome de coluna mais longo. Por padrão, a saída é finalizada com 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 é o resultado de uma cláusula FOR XML é gerada, sem formatação, em um fluxo contínuo.

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

Observação

Osqlcmd retorna mensagens de erro no formato habitual. As mensagens de erro também são produzidas no fluxo de texto XML em formato XML. Ao usar :XML ON, , o 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 ser exibido antes que o comando :XML OFF seja emitido, pois o comando :XML OFF retorna o sqlcmd para a saída orientada por linhas.

Dados XML (em fluxo) e dados de conjunto de linhas não podem ser misturados. Se o comando :XML ON não tiver sido emitido antes de ser executada uma instrução Transact-SQL que gera fluxo de XML, a saída ficará confusa. Depois que o :XML ON comando for emitido, você não poderá executar Transact-SQL instruções que geram conjuntos de linhas regulares.

Observação

O comando :XML não dá suporte à instrução SET STATISTICS XML.

Formato da saída JSON

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

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

Para saber mais, confira Formato de saída XML neste artigo.

Use a autenticação do Microsoft Entra

Exemplos usando autenticação do 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

Suporte para DSN no sqlcmd e no bcp

Você pode especificar um DSN (nome da fonte de dados) em vez de um nome de servidor no sqlcmd ou bcp -S opção (ou sqlcmd :Connect comando) se especificar -D. -D faz com que sqlcmd ou o bcp conecte-se ao servidor especificado no DSN pela opção -S.

Os DSNs do sistema são armazenados no odbc.ini arquivo no diretório ODBC SysConfigDir (/etc/odbc.ini em instalações padrão). Os DSNs de usuário são armazenados no arquivo .odbc.ini no diretório base do usuário (~/.odbc.ini).

Em sistemas Windows, os DSNs do Sistema e do Usuário são armazenados no registro e gerenciados por meio de odbcad32.exe. bcp e sqlcmd não dão suporte a DSNs de arquivo.

Confira Atributos e palavras-chave de cadeia de conexão e DSN para ver a lista de entradas com suporte do driver.

Em um DSN, somente a DRIVER entrada é necessária, mas para se conectar a um servidor remoto, o sqlcmd ou bcp precisa de um valor no SERVER elemento. Se o SERVER elemento estiver vazio ou não estiver presente no DSN, sqlcmd e bcp tentarão se conectar à instância padrão no sistema local.

Quando você usa bcp em sistemas Windows, o SQL Server 2017 (14.x) e versões anteriores exigem o driver SQL Native Client 11 (sqlncli11.dll), enquanto o SQL Server 2019 (15.x) e versões posteriores exigem o driver do Microsoft ODBC Driver 17 para SQL Server (msodbcsql17.dll).

Se a mesma opção for especificada no DSN e na linha de comando sqlcmd ou bcp , a opção de linha de comando substituirá o valor usado no DSN. Por exemplo, se o DSN tiver uma DATABASE entrada e a linha de comando do sqlcmd incluir -d, o valor passado para -d será usado. Se Trusted_Connection=yes for especificado no DSN, a autenticação Kerberos será usada; o nome de usuário (-U) e a senha (-P), se fornecido, serão ignorados.

Os scripts existentes que invocam isql podem ser modificados para usar o sqlcmd definindo o seguinte alias: alias isql="sqlcmd -D".

Práticas recomendadas do sqlcmd

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

  • Use segurança integrada.

  • Use -X[1] em ambientes automatizados.

  • Proteja arquivos de entrada e de saída usando permissões adequadas de sistema de arquivos.

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

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

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

  • Use o -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 a variável após a saída do processo. O sqlcmd retorna 0 normalmente, caso contrário ele define o ERRORLEVEL conforme definido por -V. Em outras palavras, ERRORLEVEL não deve ser o mesmo valor 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 do sqlcmd para indicar porque o sqlcmd foi encerrado e o valor é influenciado pelo argumento da linha de comando -b especificado.

Usar o -V 16 em combinação com a verificação do código de saída e DOS ERRORLEVEL pode ajudar a detectar erros em ambientes automatizados, especialmente portões de qualidade antes de uma versão de produção.

Conteúdo relacionado