Comandos no utilitário sqlcmd

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

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

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

• 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 do seguinte ao usar comandos sqlcmd :

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

  Important

  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.

Editing commands

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

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.

Output commands

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

:P erftrace <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

:Em Caso de Erro [ sair | ignorar ]

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 [ ( instrução ) ]

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

For example:

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

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:

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.

Miscellaneous commands

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

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

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

Timeout options:

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)

[:]!! command

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

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

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.

Informational messages

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.

Start 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 separador de coluna é 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.

Start 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 se expande 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.

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.

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

Related content

• sqlcmd utility
• 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
• Use sqlcmd