Partilhar via

Utilidade SQLCMD

Aplica-se a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (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.
  • Numa etapa de trabalho de sistema operacional (cmd.exe) de uma tarefa do SQL Server Agent.

Note

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.

Variantes do sqlcmd

Existem duas variantes do sqlcmd:

  • sqlcmd (Go): O go-mssqldb baseado em , por vezes estilizado como go-sqlcmd. Esta versão é uma ferramenta autônoma que você pode baixar independentemente do SQL Server. Ele roda em Windows, macOS, Linux e em contêineres.

  • sqlcmd (ODBC): O sqlcmd alinhado à plataforma, baseado em ODBC, disponível com o SQL Server ou os utilitários de linha de comando da Microsoft e parte do mssql-tools pacote no Linux. Ele também roda em Windows, macOS, Linux e em contêineres.

Para descobrir qual variante e versão do sqlcmd está instalada no seu sistema, consulte Verificar a versão instalada do utilitário sqlcmd.

Para obter informações sobre como obter o sqlcmd, consulte Baixar e instalar o utilitário sqlcmd.

Suporte a TDS 8.0

O SQL Server 2025 (17.x) introduz suporte TDS 8.0 para a utilidade sqlcmd .

Syntax

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 uso do sqlcmd, consulte 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

  • O -R interruptor é removido.

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

  • -N aceita um valor de cadeia de caracteres que pode ser 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, 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.

    Important

    No SQL Server 2025 (17.x), -N pode ser o (para optional), m (para mandatory, o padrão), ou s (para strict). Se você não incluir -N, -Nm (for mandatory) é o padrão. Esta é uma alteração significativa em relação ao SQL Server 2022 (16.x) e versões anteriores.

  • -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 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 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 com nome não são suportados neste momento no driver go-mssqldb.

Enhancements

  • :Connect tem um parâmetro opcional -G para selecionar um dos métodos de autenticação para o Banco de Dados SQL do Azure - SqlAuthentication, ActiveDirectoryDefault, ActiveDirectoryIntegrated, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity, ActiveDirectoryPassword. Para obter mais informações, consulte Autenticar com o Microsoft Entra ID no sqlcmd. 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 parâmetro de linha de comando --driver-logging-level permite ver registos do driver go-mssqldb. Use 64 para ver todos os vestígios.

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

    Note

    Isso é diferente do -F switch para sqlcmd (ODBC), que é usado com -N para especificar o nome do host no certificado.

Opções da linha de comandos

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

Opção de linha de comando Suportado no Windows Compatível com Linux e macOS
Opções relacionadas com login
-A Yes No
-C Yes Yes
- d db_name Yes Yes
-D Yes Yes
-Eu login_timeout Yes Yes
-E Yes Yes
-g Yes Yes
-G Yes Yes
- H workstation_name Yes Yes
-j Yes Yes
-K application_intent Yes Yes
-M multisubnet_failover Yes Yes
-N[s|m|o] Yes Yes
-Senha P Yes Yes
-S [protocolo:]servidor[\instance_name][,porta] Yes Yes
-Tu login_id Yes Yes
- Z new_password Yes Yes
-Z new_password Yes Yes
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] Yes Yes
-F hostname_in_certificate Yes Yes
- Eu input_file[,input_file2...] Yes Yes
- O output_file Yes Yes
-r[0 | 1] Yes Yes
-R Yes Yes
-u Yes Yes
Opções de execução de consulta
-e Yes Yes
-I Yes Yes
-q "consulta cmdline" Yes Yes
-Q "consulta cmdline" Yes Yes
- T query_timeout Yes Yes
-v var = valor [ var = valor... ] Yes No
-x Yes Yes
Opções de formato
-cabeçalhos h Yes Yes
-k [1 | 2] Yes Yes
- s col_separator Yes Yes
-E screen_width Yes Yes
-W Yes Yes
- Y variable_length_type_display_width Yes Yes
-Y fixed_length_type_display_width Yes Yes
Opções de relatório de erros
-b Yes Yes
- M error_level Yes Yes
-V error_severity_level Yes Yes
Opções diversas
-um packet_size Yes Yes
-C batch_terminator Yes Yes
-L[c] Yes No
-p[1] Yes Yes
-X[1] Yes Yes
-? Yes Yes

-A

Aplica-se a: Windows apenas. Linux e macOS não são suportados.

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.

Note

Para obter informações sobre como fazer uma conexão de administrador dedicado (DAC) 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. 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, 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.

- 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 de base de dados padrão 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, veja Suporte a DSN em sqlcmd e bcp.

Note

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

-Eu 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 o sqlcmd variável de script SQLCMDLOGINTIMEOUT. O tempo limite padrão para login em sqlcmd é de 8 segundos. Ao usar a opção para se conectar ao Banco de Dados SQL do Azure ou ao Azure Synapse Analytics e autenticar usando a -G 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.

Note

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

-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 com a autenticação do Microsoft Entra. Esta opção define o sqlcmd variável de script SQLCMDUSEAAD = 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 Autenticação do Microsoft Entra para Azure SQL. 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 o Download ODBC Driver 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 Autenticar com o ID do Microsoft Entra no sqlcmd.

- H workstation_name

Um nome de estação de trabalho. Esta opção define o sqlcmd variável de script SQLCMDWORKSTATION. 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 intenção_da_aplicação

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 Transferir carga de trabalho de leitura apenas para a réplica secundária de um grupo de disponibilidade Always On.

Note

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

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

- 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, consulte:

Note

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

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

-N[s|m|o]

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

-N pode ser o (para optional), m (para mandatory, o padrão) ou s (para strict). Se você não incluir -N, -Nm (for mandatory) é o padrão. Esta é uma alteração significativa do SQL Server 2022 (16.x) e versões anteriores, onde -No é o padrão.

Para o utilitário sqlcmd (Go), -N usa um valor de cadeia de caracteres que pode ser um de true, false ou disable para especificar a escolha 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.

  • No sqlcmd (ODBC), use -F para especificar o nome do host no certificado. Por exemplo:

    sqlcmd -S server01 -Q "SELECT TOP 100 * FROM WideWorldImporters.Sales.Orders" -A -Ns -F server01.adventure-works.com

    Note

    Isso é diferente da opção -F para sqlcmd (Go), que é usada para imprimir resultados num formato vertical.

-P senha

Uma senha especificada pelo usuário. As palavras-passe diferenciam maiúsculas de minúsculas. Se a -U opção for usada, a -P opção não for 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 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 ("").

Important

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 o seguinte comando. 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.

Note

A OSQLPASSWORD variável de ambiente é 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.

No Linux e macOS, quando usado com a -G opção 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).

Os tokens de acesso podem ser obtidos através de vários métodos. Você deve garantir que o token de acesso esteja correto byte por byte, porque ele é enviado as-is. A seguir está um comando de exemplo que obtém um token de acesso. O comando usa os comandos CLI do Azure e Linux e o salva em um arquivo no formato adequado. Se a codificação padrão do seu sistema ou terminal não for ASCII ou UTF-8, talvez seja necessário ajustar as opções de iconv. Certifique-se de proteger cuidadosamente o arquivo resultante e excluí-lo 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 [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.

Note

A OSQLSERVER variável de ambiente é 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.

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

- Tu login_id

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).

Note

A OSQLUSER variável de ambiente é 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 new_password

Altere a palavra-passe. 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 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 ficheiros de entrada Unicode big-endian e little-endian. Se a opção -u for especificada, a saída será sempre em 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 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.

Note

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

-F hostname_in_certificate

Especifica um Nome Comum (CN) ou Nome Alternativo da Entidade (SAN) diferente e esperado no certificado do servidor para ser usado durante a validação do certificado do servidor. Sem essa opção, a validação do certificado garante que o CN ou a SAN no certificado corresponda ao nome do servidor ao qual você está se conectando. Esse parâmetro pode ser preenchido quando o nome do servidor não corresponde ao CN ou SAN, por exemplo, ao usar aliases DNS.

- Eu 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.

Note

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

Exemplos de caminhos:

-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 utilizada mais do que 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 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. Se este ficheiro não existir, será criado. 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 caminhos:

-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.

Note

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

-R

Aplica-se a: ODBC sqlcmd somente.

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.

Note

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

-u

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

Note

Para o utilitário sqlcmd (Go), o ficheiro 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).

-I

Aplica-se a: ODBC sqlcmd somente.

Define a opção de conexão SET QUOTED_IDENTIFIER como ON. A predefinição é OFF. Para obter mais informações, consulte SET QUOTED_IDENTIFIER.

Note

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

-q "consulta da linha de comandos"

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

Important

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

Important

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.

- 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.

Note

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: Windows apenas. Linux e macOS não são suportados.

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

-cabeçalhos h

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 screen_width

Especifica a largura da tela para a saída. Esta opção define o sqlcmd variável de script SQLCMDCOLWIDTH. 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 a variável de script sqlcmdSQLCMDMAXVARTYPEWIDTH. 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)
  • text
  • ntext
  • image

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.

Caution

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

- E fixed_length_type_display_width

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 -V opção estiver definida, além de -b, o sqlcmd não acusará um erro se o nível de gravidade for inferior aos valores definidos com o uso de -V. Os ficheiros em lote do prompt de comando podem testar o valor de ERRORLEVEL e lidar com 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_gravidade_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 packet_size

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 processamento em 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]

Aplica-se a: Windows apenas. Linux e macOS não são suportados.

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.

Note

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.)

Where:

  • 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 da sintaxe das opções de sqlcmd.

Note

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

Remarks

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

Note

Se você usar a -i opção seguida por um ou mais parâmetros extras, 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 sqlcmd.

Note

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.

Suporte a DSN em sqlcmd e bcp

Você pode especificar um nome de fonte de dados (DSN) 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 bcp se conecte ao servidor especificado no DSN pela -S opção.

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

Em sistemas Windows, os DSNs de sistema e usuário são armazenados no registro e gerenciados via odbcad32.exe. bcp e sqlcmd não suportam DSNs de arquivos.

Consulte Palavras-chave e atributos de DSN e cadeia de conexão para obter a lista de entradas suportadas pelo driver.

Em um DSN, apenas a DRIVER entrada é necessária, mas para se conectar a um servidor remoto, sqlcmd ou bcp precisa de SERVER um valor no 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 do SQL Native Client 11 (sqlncli11.dll), enquanto o SQL Server 2019 (15.x) e versões posteriores exigem o driver 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 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 fornecidos, serão ignorados.

Os scripts existentes que invocam isql podem ser modificados para usar 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.

  • 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 o esperado 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 a variável após a saída 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 do sqlcmd para indicar por que o sqlcmd foi encerrado, e o seu valor é influenciado pela especificação do argumento de linha de comando -b.

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

  • Last updated on