Comandos no utilitário sqlcmd

Aplica-se a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)Banco de dados SQL no Microsoft Fabric

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

Além das instruções Transact-SQL no 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 há suporte para Linux ou macOS.

Lembre-se dos seguintes pontos ao 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 somente se eles 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. Você não pode seguir um comando com 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 instruções Transact-SQL.

Editando comandos

[:]ED

Inicie o editor de textos. Use este editor para editar o lote Transact-SQL atual ou o lote de última execução. Para editar o lote de última execução, digite o ED comando imediatamente após a conclusão da execução do último lote.

A SQLCMDEDITOR variável de 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 como Microsoft Notepad, digite o seguinte comando:

SET SQLCMDEDITOR=notepad

[:]RESET

Limpa o cache de declarações.

:List

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

Variables

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

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.

Comandos de saída

:Erro <nome do arquivo> | STDERR | STDOUT

Redirecione toda a saída de erro para o arquivo especificado pelo nome do 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 vai para stderr.

• filename

  Cria e abre um arquivo que receberá a saída. Um arquivo existente é truncado para zero bytes. Se o arquivo não estiver disponível devido a permissões ou outros motivos, a alteração da saída não ocorrerá. Nesse caso, o último destino especificado ou padrão receberá a saída de erro.

• STDERR

  Alterna a saída de erro para o fluxo stderr. Se a saída for 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 for redirecionada, o destino para o qual o fluxo é redirecionado receberá a saída de erro.

:Out <filename> | STDERR | STDOUT

Cria e redireciona todos os resultados da consulta para o arquivo especificado pelo nome do arquivo, para stderr, ou para stdout. Por padrão, a saída vai 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 pelo nome do arquivo, para stderr, ou para stdout. Por padrão, a saída do rastreamento de desempenho vai para stdout. Um arquivo existente é truncado para zero bytes. O comando :Perftrace pode aparecer várias vezes em um script.

Comandos de controle de execução

:Em Caso de Erro [ sair | ignorar ]

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

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

Quando você usa a opção, o ignoresqlcmd ignora o erro e continua executando o lote ou o script. Por padrão, o sqlcmd imprime uma mensagem de erro.

[:]QUIT

Faz com que sqlcmd saia.

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

Use o resultado de uma SELECT instrução como o valor retornado do 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. Windows 2000 e versões posteriores passam 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 :EXIT() instrução com os parênteses vazios executa tudo o que está antes dela no lote e depois encerra sem um valor retornado.

Quando você especifica uma consulta incorreta, o sqlcmd sai sem um valor retornado.

Aqui está uma lista de formatos EXIT:

• :EXIT

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

• :EXIT( )

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

• :EXIT(query)

  Executa o lote que inclui a consulta e, em seguida, encerra-se após o retorno dos resultados da consulta.

Se você usar RAISERROR dentro de um script sqlcmd e gerar um estado de 127, o sqlcmd será encerrado e retornará a ID da mensagem de volta ao 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 de retorno de -1 a -99 são reservados pelo SQL Server, e sqlcmd define valores adicionais de retorno:

GO [contagem]

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 diversos

:r <filename>

Analisa instruções adicionais de Transact-SQL e comandos sqlcmd do arquivo especificado por filename no cache de declarações. o sqlcmd lê o nome do arquivo em relação ao diretório de inicialização.

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

O sqlcmd lê e executa o arquivo após encontrar um terminador de lote. Podem ser emitidos vários comandos :r . O arquivo pode incluir qualquer comando sqlcmd, incluindo o terminador de lote GO.

:ServerList

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]] [-N[s|m|o]] [-F hostname_in_certificate]

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

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

  Use essa opção para solicitar uma conexão criptografada. Se você não incluir -N, -Nm (for mandatory) será o padrão. Essa 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)	Obrigatório
  -No	Opcional

• Nome do host 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 uso durante a validação do certificado do servidor. Sem essa opção, a validação do certificado garante que o CN ou o 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 tempo limite:

  Value	Behavior
  0	Aguarde eternamente
  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 você especificar apenas user_name (como uma opção ou como uma variável de ambiente), o sqlcmd solicitará que você 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 se conectar à instância padrão do myserver usando variáveis de script, use 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 (!!) seguidos pelo comando do sistema operacional. Por exemplo:

:!! dir

:XML [ ON | OFF ]

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

:Help

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

Nomes de arquivos sqlcmd

Especifique arquivos sqlcmd de entrada usando a opção -i ou o comando :r. Especifique os arquivos de saída usando a opção -o ou os comandos :Error, :Out, e :Perftrace. Ao trabalhar com esses arquivos, use as seguintes diretrizes:

• Use valores de nome de arquivo separados para :Error, :Oute :Perftrace. Se você usar o mesmo nome de arquivo, os comandos poderão intercalar entradas.

• Se você chamar um arquivo de entrada localizado em um servidor remoto do sqlcmd em um computador local e o arquivo contiver um caminho de arquivo de unidade, como :Out c:\OutputFile.txt, o sqlcmd criará o arquivo de saída 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 o sqlcmd executa as instruções Transact-SQL, ele imprime uma mensagem informativa.

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

USE AdventureWorks2025;
GO

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

Changed database context to 'AdventureWorks2025'.

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 separador de coluna é um espaço. Se o nome da coluna for menor que a largura da coluna, sqlcmd preenche a saída com espaços até a próxima coluna.

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

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

USE AdventureWorks2025;

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

Quando você pressiona Enter, o sqlcmd retorna 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 de largura, ela se expande para acomodar o nome de coluna mais longo. Por padrão, o sqlcmd encerra a saída em 80 caracteres. Você pode alterar essa largura usando a opção -w ou definindo a SQLCMDCOLWIDTH variável de script.

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.

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 :XML ON comando não tiver sido emitido antes de uma instrução Transact-SQL que gera fluxos XML for executada, a saída será embaralhada. Depois que o :XML ON comando for emitido, você não poderá executar instruções Transact-SQL que geram conjuntos de linhas regulares.

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 que usam a 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

Conteúdo relacionado

• Utilitário sqlcmd
• Verificar a versão instalada do utilitário sqlcmd
• Iniciar o utilitário sqlcmd
• Executar o T-SQL de um arquivo de script com sqlcmd
• Usar sqlcmd