Partilhar via

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

O utilitário sqlcmd permite inserir instruções Transact-SQL, procedimentos do sistema e arquivos de script.

Note

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.

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

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

1 Não suportado em Linux ou macOS.

Esteja ciente do seguinte ao usar sqlcmd comandos:

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

    Important

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

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

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

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

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

Comandos de edição

[:]ED

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

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

SET SQLCMDEDITOR=notepad

[:]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.

Note

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

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

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

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

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

:Listvar

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

Note

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

  • filename

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

  • STDERR

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

  • STDOUT

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

:out <nome do arquivo> | STDERR | STDOUT

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

:Perftrace <nome do arquivo> | STDERR | STDOUT

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

Comandos de controle de execução

:On Error [ sair | ignorar ]

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

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

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

[:]QUIT

Faz com que o sqlcmd saia.

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

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

Por exemplo:

:EXIT(SELECT @@ROWCOUNT)

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

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

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

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

Aqui está uma lista de formatos EXIT:

  • :EXIT

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

  • :EXIT( )

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

  • :EXIT(query)

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

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

RAISERROR(50001, 10, 127)

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

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

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

GO [contagem]

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

Comandos diversos

:r <nome do arquivo>

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

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

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

Note

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

:ServerList

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

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

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

Opções de 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 apenas user_name for especificado (como uma opção ou como uma variável de ambiente), o usuário será solicitado a inserir uma senha. Os usuários não 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 se conectar à instância padrão do myserver usando variáveis de script, você deve usar as seguintes configurações:

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

[:]!! command

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

:!! dir

Note

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

:XML [ ATIVADO | DESLIGADO ]

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

:Help

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

Nomes de arquivo sqlcmd

arquivos de entrada do sqlcmd podem ser especificados com a opção -i ou o comando :r. Os arquivos de saída podem ser especificados com a -o opção ou os :Errorcomandos , :Oute :Perftrace . A seguir estão algumas diretrizes para 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 podem ser misturadas.

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

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

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

Mensagens informativas

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

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

USE AdventureWorks2022;
GO

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

Changed database context to 'AdventureWorks2022'.

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 menor que a largura da coluna, a saída será preenchida com espaços até à próxima coluna.

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

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

USE AdventureWorks2022;

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

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

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

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

Formato de saída XML

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

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

Note

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

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

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

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

Note

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

Formato de saída JSON

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

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

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

Utilize a autenticação do Microsoft Entra

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

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

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

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

Conteúdo relacionado

  • Last updated on