Comandos no utilitário 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

A utilidade sqlcmd aceita instruções Transact-SQL, procedimentos do sistema e ficheiros de script.

Para além das instruções Transact-SQL dentro do sqlcmd, use os seguintes comandos:

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

¹ Não suportado em Linux ou macOS.

Tenha em mente os seguintes pontos quando usar comandos sqlcmd :

• Todos os comandos sqlcmd , exceto GO, devem começar com dois pontos (:).

  Important

  Para manter a compatibilidade retroativa com scripts osql existentes, alguns comandos funcionam sem os dois-pontos (indicado por [:]).

• O SQLCMD reconhece comandos 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. Não pode seguir um comando com Transact-SQL ou outro comando.

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

Comandos de edição

[:]ED

Inicia o editor de texto. Use este editor para editar o lote Transact-SQL atual, ou o lote da última execução. Para editar o último batch de execução, escreva o ED comando imediatamente após a execução do último lote.

A SQLCMDEDITOR variável ambiente define o editor de texto. O editor padrão é Edit. Para alterar o editor, defina a variável de ambiente SQLCMDEDITOR. Por exemplo, para definir o editor para Microsoft Notepad, escreva o seguinte comando:

SET SQLCMDEDITOR=notepad

[:]RESET

Limpa a cache de declarações.

:List

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

Variables

:Setvar <var> [ "valor" ]

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

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

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

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

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

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

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

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

:Listvar

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

Comandos de saída

:Erro <nome do arquivo> | STDERR | STDOUT

Redirecione todos os erros gerados para o ficheiro especificado pelo nome do ficheiro, para stderr, ou para stdout. O comando :Error pode aparecer várias vezes em um script. Por padrão, a saída de erro vai para stderr.

• filename

  Cria e abre um arquivo que recebe a saída. Um ficheiro existente é truncado para zero bytes. Se o ficheiro não estiver disponível devido a permissões ou outras razões, a saída não é alterada, e o último destino especificado ou por defeito recebe a saída de erro.

• STDERR

  Alterna a saída de erro para o fluxo stderr. Se a saída for redirecionada, o alvo para o qual o fluxo é redirecionado recebe a saída de erro.

• STDOUT

  Alterna a saída de erro para o fluxo stdout. Se a saída for redirecionada, o alvo para o qual o fluxo é redirecionado recebe a saída de erro.

:out <nome do arquivo> | STDERR | STDOUT

Cria e redireciona todos os resultados das consultas para o ficheiro especificado pelo nome do ficheiro, para stderr, ou para stdout. Por defeito, a saída vai para stdout. Se o arquivo já existir, ele será truncado para zero bytes. O comando :Out pode aparecer várias vezes em um script.

:Perftrace <nome do arquivo> | STDERR | STDOUT

Cria e redireciona toda a informação do rastreio de desempenho para o ficheiro especificado pelo nome do ficheiro, para stderr, ou para stdout. Por padrão, a saída do registo de desempenho vai para stdout. Um ficheiro existente é truncado para zero bytes. O comando :Perftrace pode aparecer várias vezes em um script.

Comandos de controle de execução

:On Error [ sair | ignorar ]

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

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

Quando usas a ignore opção, o sqlcmd ignora o erro e continua a executar o lote ou script. Por defeito, o sqlcmd imprime uma mensagem de erro.

[:]QUIT

Faz com que o sqlcmd saia.

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

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

Por exemplo:

:EXIT(SELECT @@ROWCOUNT)

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

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

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

Quando especificas uma consulta incorreta, o sqlcmd sai sem valor de retorno.

Aqui está uma lista de formatos EXIT:

• :EXIT

  Não executa o lote, depois sai imediatamente e não retorna valor.

• :EXIT( )

  Executa o processamento do lote, depois encerra o programa e não retorna nenhum valor.

• :EXIT(query)

  Executa o lote que inclui a consulta e depois encerra depois de devolver os resultados da consulta.

Se usares RAISERROR dentro de um script sqlcmd e definires um estado de 127, sqlcmd termina e devolve o ID da mensagem ao cliente. Por exemplo:

RAISERROR(50001, 10, 127)

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

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

GO [contagem]

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

Comandos diversos

:r <nome do arquivo>

Analisa instruções Transact-SQL extra e comandos sqlcmd do ficheiro especificado por filename na cache de instruções. O SQLCMD lê o nome do ficheiro em relação ao diretório de arranque.

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

sqlcmd lê e executa o ficheiro depois de encontrar um terminador de lote. Você pode emitir vários comandos :r. O arquivo pode incluir qualquer comando sqlcmd, incluindo o terminador em lotes GO.

:ServerList

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

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

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

• Opções de encriptação (-N[s|m|o]):

  Use esta opção para solicitar uma ligação encriptada. Se você não incluir -N, -Nm (for mandatory) é o padrão. Esta opção é uma alteração significativa em relação ao SQL Server 2022 (16.x) e versões anteriores, onde -No (para optional) é o padrão.

  Value	Description
  -Ns	Rigoroso
  -Nm (padrão)	Mandatory
  -No	Opcional

• Nome do anfitrião no certificado (-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.

• Opções de timeout:

  Value	Behavior
  0	Espera para sempre
  n>0	Aguarde e segundos

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

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

Se especificar apenas user_name (seja como opção ou como variável de ambiente), o sqlcmd pede para introduzir uma palavra-passe. Os usuários não serão avisados se as SQLCMDUSER variáveis ou SQLCMDPASSWORD de ambiente estiverem definidas. Se você não fornecer opções ou variáveis de ambiente, o modo de Autenticação do Windows será usado para entrar. Por exemplo, para se conectar a uma instância, instance1, do SQL Server, myserver, usando a segurança integrada, você usaria o seguinte comando:

:connect myserver\instance1

Para ligar-se à instância padrão de myserver utilizando variáveis de scripting, use as seguintes definições:

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

[:]!! command

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

:!! dir

:XML [ ATIVADO | DESLIGADO ]

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

:Help

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

Nomes de arquivo sqlcmd

Especifique ficheiros de entrada do sqlcmd usando a -i opção ou o :r comando. Especifique ficheiros de saída usando a -o opção ou os :Errorcomandos , :Out, e :Perftrace . Ao trabalhar com estes ficheiros, utilize as seguintes orientações:

• Use valores de nomes de ficheiro separados para :Error, :Out, e :Perftrace. Se usares o mesmo nome de ficheiro, os comandos podem misturar as entradas.

• Se chamar um ficheiro de entrada localizado num servidor remoto a partir de sqlcmd num computador local, e o ficheiro contiver um caminho de ficheiro de drive como :Out c:\OutputFile.txt, sqlcmd cria o ficheiro de saída no computador local e não no servidor remoto.

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

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

Mensagens informativas

O SQLCMD imprime qualquer mensagem informativa que o servidor envie. No exemplo seguinte, depois de o sqlcmd executar as instruções Transact-SQL, imprime uma mensagem informativa.

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

USE AdventureWorks2025;
GO

Quando pressiona Enter, o sqlcmd imprime a seguinte mensagem informativa:

Changed database context to 'AdventureWorks2025'.

O formato de saída das consultas Transact-SQL

sqlcmd imprime primeiro um cabeçalho de coluna que contém os nomes de coluna especificados na lista de seleção. Os nomes das colunas são separados usando o caractere SQLCMDCOLSEP. Por predefinição, este separador de coluna é um espaço. Se o nome da coluna for mais curto do que a largura da coluna, o sqlcmd preenche a saída com espaços até à coluna seguinte.

O SQLCMD imprime uma linha separadora que é uma série de caracteres traço. A saída a seguir mostra um exemplo.

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

USE AdventureWorks2025;

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

Quando pressiona Enter, sqlcmd devolve o seguinte conjunto de resultados.

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

Embora a BusinessEntityID coluna tenha apenas quatro caracteres, ela se expande para acomodar o nome da coluna mais longa. Por defeito, o sqlcmd termina a saída a 80 caracteres. Podes alterar essa largura usando a -w opção ou definindo a SQLCMDCOLWIDTH variável de script.

Formato de saída XML

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

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

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

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

Os dados XML (transmitidos) e os dados do conjunto de linhas não podem ser misturados. Se o :XML ON comando não foi emitido antes de ser executada uma instrução Transact-SQL que gera fluxos XML, a saída fica distorcida. Uma vez emitido o :XML ON comando, não pode executar Transact-SQL instruções que gerem conjuntos de linhas normais.

Formato de saída JSON

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

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

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

Utilize a autenticação do Microsoft Entra

Exemplos que utilizam autenticação Microsoft Entra:

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

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

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

Conteúdo relacionado

• utilitário sqlcmd
• Verifique a versão instalada do utilitário sqlcmd
• Inicie o utilitário sqlcmd
• Executar T-SQL a partir de um arquivo de script com sqlcmd
• Usar sqlcmd