Partilhar via

  • Artigo

Utilitário sqlcmd

O utilitário sqlcmd permite inserir instruções Transact-SQL, procedimentos do sistema e arquivos de script no prompt de comando, no Editor de Consultas no modo SQLCMD, em um arquivo de script do Windows ou em uma etapa do trabalho do sistema operacional (Cmd.exe) de um trabalho do SQL Server Agent. Esse utilitário usa OLE DB para executar lotes Transact-SQL.

Observação importanteImportante

O SQL Server Management Studio usa o Microsoft .NET Framework SqlClient para execução nos modos normal e SQLCMD no Editor de Consultas. Quando sqlcmd é executado na linha de comando, sqlcmd usa o provedor OLE DB. Como diferentes opções padrão podem ser aplicáveis, você poderá perceber um comportamento diferente quando executar a mesma consulta no SQL Server Management Studio no modo SQLCMD e no utilitário sqlcmd.

Sintaxe

sqlcmd 
[{ { -U login_id [ -P password ] } | –E trusted connection }] 

[ -N encrypt connection ][ -C trust the server certificate ]
[ -z new password ] [ -Z new password and exit]
[ -S [protocol:]server[\instance_name][,port] ] [ -H wksta_name ] [ -d db_name ]
[ -l login time_out ] [ -A dedicated admin connection] 
[ -i input_file ] [ -o output_file ]
[ -f < codepage > | i: < codepage > [ < , o: < codepage > ] ]
[ -u unicode output] [ -r [ 0 | 1 ] msgs to stderr ] 
[ -R use client regional settings]
[ -q "cmdline query" ] [ -Q "cmdline query" and exit] 
[ -e echo input ] [ -t query time_out ] 
[ -I enable Quoted Identifiers ] 
[ -v var = "value"...] [ -x disable variable substitution ]
[ -h headers ][ -s col_separator ] [ -w column_width ] 
[ -W remove trailing spaces ]
[ -k [ 1 | 2 ] remove[replace] control characters ] 
[ -y display_width ] [-Y display_width ]
[ -b on error batch abort] [ -V severitylevel ] [ -m error_level ] 
[ -a packet_size ][ -c cmd_end ] 
[ -L [ c ] list servers[clean output] ] 
[ -p [ 1 ] print statistics[colon format]] 
[ -X [ 1 ] ] disable commands, startup script, enviroment variables [and exit] 
[ -? show syntax summary]

Opções de linha de comando

  • Opções relacionadas a logon

  • -Ulogin_id
    É a identificação de logon do usuário.

    ObservaçãoObservação

    A variável ambiental OSQLUSER está disponível para compatibilidade com versões anteriores. A variável ambiental SQLCMDUSER tem precedência em relação à variável ambiental OSQLUSER. Isso significa que sqlcmd e osql podem ser usados paralelamente sem interferência. Isso também significa que scripts osql existentes continuarão a funcionar.

    Se nem a opção -U nem a opção -P for especificada, o sqlcmd tentará se conectar usando o modo de Autenticação do Microsoft Windows. A autenticação é baseada na conta do Windows do usuário que estiver executando o sqlcmd.

    Se a opção -U for usada com a opção -E (descrita posteriormente neste tópico), uma mensagem de erro será gerada. Será gerada uma mensagem de erro se a opção –U for seguida por mais de um argumento e o programa será encerrado.

  • -Ppassword
    É uma senha especificada pelo usuário. Senhas diferenciam maiúsculas e minúsculas. Se a opção -U for usada e a opção -P não for usada, e a variável ambiental SQLCMDPASSWORD não tiver sido definida, o sqlcmd solicitará uma senha ao usuário. Se a opção -P for usada no final do prompt de comando sem uma senha, o sqlcmd usará a senha padrão (NULL).

    Observação sobre segurançaObservação sobre segurança

    Não use uma senha em branco. Use uma senha forte. Para obter mais informações, consulte Senhas fortes.

    O prompt de senha é exibido imprimindo-se o prompt de senha no console, como a seguir: Password:

    A entrada do usuário está oculta. Isso significa que nada é exibido e o cursor fica em posição.

    A variável de ambiente SQLCMDPASSWORD lhe permite definir uma senha padrão para a sessão atual. Assim, senhas não têm de ser hard-coded em arquivos em lote.

    O exemplo a seguir define a variável SQLCMDPASSWORD no prompt de comando e acessa o utilitário sqlcmd. No prompt de comando, digite:

    SET SQLCMDPASSWORD= p@a$$w0rd

    Observação sobre segurançaObservação sobre segurança

    A senha estará visível para qualquer um que tiver acesso ao monitor do seu computador.

    No prompt de comando a seguir, digite:

    sqlcmd

    Se a combinação de nome de usuário e senha estiverem incorretos, o provedor OLE DB gera uma mensagem de erro.

    ObservaçãoObservação

    A variável de ambiente OSQLPASSWORD foi mantida para compatibilidade com versões anteriores. A variável ambiental SQLCMDPASSWORD tem precedência sobre a variável ambiental OSQLPASSWORD; isso significa que sqlcmd e osql podem ser usados paralelamente sem interferência e que os scripts antigos continuarão a funcionar.

    Será gerada uma mensagem de erro se a opção -P for usada com a opção -E.

    Será gerada uma mensagem de erro se a opção -P for seguida por mais de um argumento e o programa será encerrado.

  • -E trusted connection
    Usa uma conexão confiável em vez de usar um nome de usuário e uma senha para fazer logon no SQL Server. Por padrão, sem a especificação de -E, o sqlcmd usa a opção de conexão confiável.

    A opção -E ignora as possíveis configurações de variável ambiental de nome de usuário e senha, como SQLCMDPASSWORD. Se a opção -E for usada com -U ou -P, uma mensagem de erro será gerada.

  • -Nencrypt connection
    Essa opção é usada pelo cliente para solicitar uma conexão criptografada. Essa opção equivale à opção ENCRYPT = true do ADO.net.

  • -Ctrust the server certificate
    Essa opção é usada pelo cliente para configurá-lo para confiar implicitamente no certificado do servidor sem validação. Essa opção equivale à opção TRUSTSERVERCERTIFICATE = true do ADO.net.

  • -z new password
    Alterar senha:

    sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

  • -Z new password and exit
    Alterar senha e sair:

    sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

  • -S [protocol:]server[**\instance_name][,**port]
    Especifica a instância do SQL Server à qual se conectar. Define a variável de script SQLCMDSERVER do sqlcmd.

    Especifica o server que se conectará à instância padrão do SQL Server nesse computador servidor. Especifica server[**\**instance_name] para conexão com uma instância nomeada do SQL Server naquele computador servidor. Se nenhum computador servidor for especificado, o sqlcmd se conectará à instância padrão do SQL Server no computador local. Essa opção é necessária quando você executa o sqlcmd em um computador remoto na rede.

    protocol pode ser tcp (TCP/IP), lpc (memória compartilhada) ou np (pipes nomeados). Para obter mais informações sobre protocolos, consulte Escolhendo um protocolo de rede.

    Se você não especificar um server[**\**instance_name] ao iniciar o sqlcmd, o SQL Server verifica e usa a variável ambiental SQLCMDSERVER.

    ObservaçãoObservação

    A variável de ambiente OSQLSERVER foi mantida para compatibilidade com versões anteriores. A variável ambiental SQLCMDSERVER tem precedência sobre a variável ambiental OSQLSERVER; isso significa que sqlcmd e osql podem ser usados paralelamente sem interferência e que os scripts antigos continuarão a funcionar.

  • -Hwksta_name
    É um nome de estação de trabalho. Essa opção define a variável de script SQLCMDWORKSTATION do sqlcmd. O nome da estação de trabalho é listada na coluna hostname da exibição de catálogo sys.processes e pode ser retornada 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 do sqlcmd.

  • -ddb_name
    Emite uma instrução USE db_name quando você inicia o sqlcmd. Essa opção define a variável de script SQLCMDDBNAME do sqlcmd. Isso especifica o banco de dados inicial. O padrão é a propriedade do banco de dados padrão de seu logon. Se o banco de dados não existir, uma mensagem de erro será gerada e o sqlcmd será fechado.

  • -llogintime_out
    Especifica o número de segundos antes de o tempo de logon do sqlcmd no provedor OLE DB se esgotar quando você tentar se conectar a um servidor. Essa opção define a variável de script SQLCMDLOGINTIMEOUT do sqlcmd. O tempo limite padrão de logon do sqlcmd é de oito segundos. O tempo limite do logon deve ser um número entre 0 e 65534. Se o valor fornecido não for numérico ou não estiver nesse intervalo, o sqlcmd gerará uma mensagem de erro. Um valor de 0 especifica o tempo limite como infinito.

  • -A dedicated admin connection
    Faz logon no SQL Server com uma DAC (conexão de administrador dedicada). Esse tipo de conexão é usado para solucionar um problema no servidor. Isso funcionará apenas com computadores servidor que oferecem suporte para DAC. Se o DAC não estiver disponível, o sqlcmd gerará uma mensagem de erro e será fechado. Para obter mais informações sobre a DAC, consulte Usando uma conexão de administrador dedicada [SQL Server].

  • Input/Output Options

  • -i input_file[***,***input_file2...]
    Identifica o arquivo que contém um lote de instruções SQL ou procedimentos armazenados. Poderão ser especificados vários arquivos para serem lidos e processados em ordem. Não use espaços entre os nomes de arquivos. O sqlcmdfará primeiramente uma verificação para conferir se todos os arquivos especificados existem. Se um ou mais arquivos não existirem, o sqlcmd será fechado. As opções -i e Q/-q são mutuamente exclusivas.

    Exemplos de caminho:

    -i C:\<nomedoarquivo>

    -i \\<Servidor>\<Share$>\<nomedoarquivo>

    -i "C:\Alguma pasta\<nome do arquivo>"

    Os caminhos de arquivos que contêm espaços devem ficar entre aspas.

    Esta opção pode ser usada mais de uma vez: -i input_file -i I input_file.

  • -ooutput_file
    Identifica o arquivo que recebe a saída do sqlcmd.

    Se -u for especificado, o output_file será armazenado no formato Unicode. Se o nome do arquivo for inválido, uma mensagem de erro será gerada e o sqlcmd será fechado. O sqlcmd não oferece suporte à gravação simultânea de vários processos sqlcmd no mesmo arquivo. A saída de arquivo será corrompida ou incorreta. Consulte a opção -f para obter mais informações sobre os formatos de arquivo. Caso não exista, esse arquivo será criado. Um arquivo de mesmo nome de uma sessão sqlcmd anterior será 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 caminho:

    -o C:\< nomedoarquivo>

    -o \\<Servidor>\<Share$>\<nomedoarquivo>

    **-o "**C:\Alguma pasta\<nome do arquivo>"

    Os caminhos de arquivos que contêm espaços devem ficar entre aspas.

  • -f < codepage > | i: < codepage > [ <, o: < codepage > ]
    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 um código de página instalada do Windows. Para obter mais informações, consulte Configurações de agrupamento na Instalação.

    Regras de conversão de página de código:

    • Se nenhuma página de código for especificada, o sqlcmd usará a página de código atual para os arquivos de entrada e saída, a menos que o arquivo de entrada seja Unicode, o que não exige conversão.

    • O sqlcmd reconhece automaticamente os arquivos de entrada Unicode big-endian e little-endian. Se a opção -u for especificada, a saída será sempre Unicode little-endian.

    • Se não for especificado nenhum arquivo de saída, a página de código de saída será a página de código de console. Isso habilita a saída a ser exibida corretamente no console.

    • Assume-se que arquivos de entrada múltiplos tenham a mesma página de código. 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 de Cmd.exe.

  • -u unicode output
    Especifica que o output_file é armazenado no formato Unicode, independentemente do formato do input_file.

  • -r[ 0 | 1] msgs to stderr
    Redireciona a saída da mensagem de erro para a tela (stderr). Se você não especificar um parâmetro ou se especificar 0, serão redirecionadas somente mensagens de erro com nível de severidade 11 ou acima disso. Se você especificar 1, serão redirecionadas todas as saídas de mensagens de erro inclusive PRINT. Não tem nenhum efeito se você usar -o. Por padrão, as mensagens são enviadas para stdout.

  • -R use client regional settings
    Faz com que o sqlcmd localize colunas numéricas, de moeda, 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.

  • Opções de execução de consultas

  • -q" cmdline query "
    Executa uma consulta quando o sqlcmd é iniciado, mas não fecha o sqlcmd quando a execução da consulta termina. Podem ser executadas consultas delimitadas por vários ponto e vírgula. Use aspas na consulta, conforme o exemplo a seguir.

    No prompt de comando, digite:

    sqlcmd -d AdventureWorks2008R2 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

    sqlcmd -d AdventureWorks2008R2 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

    Observação importanteImportante

    Não use o terminador GO na consulta.

    Se -b for especificado com essa opção, o sqlcmd será fechado com erro. -b é descrito mais adiante neste tópico.

  • **-Q"**cmdline query " and exit
    Executa uma consulta quando o sqlcmd iniciado e fecha o sqlcmd imediatamente. Podem ser executadas consultas delimitadas por vários ponto e vírgula.

    Use aspas na consulta, conforme o exemplo a seguir.

    No prompt de comando, digite:

    sqlcmd -d AdventureWorks2008R2 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

    sqlcmd -d AdventureWorks2008R2 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

    Observação importanteImportante

    Não use o terminador GO na consulta.

    Se -b for especificado com essa opção, o sqlcmd será fechado com erro. -b é descrito mais adiante neste tópico.

  • -e echo input
    Grava scripts de entrada no dispositivo de saída padrão (stdout).

  • -I enable Quoted Identifiers
    Define a opção de conexão SET QUOTED_IDENTIFIER como ON. Por padrão, ela é definida como OFF. Para obter mais informações, consulte SET QUOTED_IDENTIFIER (Transact-SQL).

  • -tquerytime_out
    Especifica quanto segundos faltam para que um comando (ou instrução SQL) expire. Essa opção define a variável de script SQLCMDSTATTIMEOUT do sqlcmd. Se um valor time_out não for especificado, o tempo do comando não se esgotará. O querytime_out deve ser um número entre 1 e 65535. Se o valor fornecido não for numérico ou não estiver nesse intervalo, o sqlcmd gerará uma mensagem de erro.

    ObservaçãoObservação

    O valor de tempo limite real pode variar do valor time_out especificado por vários segundos.

  • -vvar*=value[ var=*value...]
    Cria uma variável de script do sqlcmdque pode ser usada em um script sqlcmd. Se o valor contiver espaços, mantenha-o entre aspas. Você pode especificar vários valores var="values". Se houver erros em qualquer um dos valores especificados, o sqlcmd gerará uma mensagem de erro e será fechado.

    sqlcmd -v MyVar1=something MyVar2="some thing"

    sqlcmd -v MyVar1=something -v MyVar2="some thing"

  • -x disable variable substitution
    Faz com que o sqlcmd ignore as variáveis de script. Isso é útil quando um script contém muitas instruções INSERT que podem conter cadeias de caracteres que tenham o mesmo formato de variáveis comuns, como $(variable_name).

  • Opções de formatação

  • -hheaders
    Especifica o número de linhas a imprimir entre os títulos da coluna. O padrão é imprimir títulos uma vez para cada conjunto de resultados de consulta. Essa opção define a variável de script SQLCMDHEADERS do sqlcmd. Use -1 para especificar que os cabeçalhos não devem ser impressos. Qualquer valor inválido faz com que o sqlcmd gere uma mensagem de erro e seja fechado.

  • -scol_separator
    Especifica o caractere do separador de coluna. O padrão é um espaço em branco. Essa opção define a variável de script SQLCMDCOLSEP do sqlcmd. Para usar caracteres que tenham um significado especial ao sistema operacional, como o E comercial (&) ou ponto e vírgula (;), coloque o caractere entre aspas ("). O separador de coluna pode ser qualquer caractere de 8 bits.

  • -wcolumn_width
    Especifica a largura de tela para saída. Essa opção define a variável de script SQLCMDCOLWIDTH do sqlcmd. A largura da coluna deve ser um número maior que 8 e menor que 65536. Se a largura de coluna especificada não estiver nesse intervalo, o sqlcmd gerará uma mensagem de erro. A largura padrão é 80 caracteres. Quando uma linha de saída excede a largura de coluna especificada, ela inclui a próxima linha.

  • -W remove trailing spaces
    Essa opção remove espaços à direita de uma coluna. Use essa opção com a opção -s para preparar os dados que devem ser exportados para outro aplicativo. Não pode ser usada com as opções -y ou -Y.

  • -k[ 1 | 2 ] remove[replace] control characters
    Remove todos os caracteres de controle, como tabulações e caracteres de nova linha da saída. Isso preserva a formatação de coluna quando os dados são retornados. Se for especificado 1, os caracteres de controle serão substituídos por um único espaço. Se for especificado 2, os caracteres de controle consecutivos serão substituídos por um único espaço.

  • -ydisplay_width
    Define a variável de script SQLCMDMAXFIXEDTYPEWIDTH do sqlcmd. Limita o número de caracteres que são retornados para os tipos de dados com comprimento variável grande:

    • varchar(max)

    • nvarchar(max)

    • varbinary(max)

    • xml

    • UDT (user-defined data types)

    • text

    • ntext

    • image

    ObservaçãoObservação

    UDTs podem ter comprimento fixo dependendo da implementação. Se esse comprimento de UDT de comprimento fixo for mais curto que display_width, o valor do UDT retornado não será afetado. Porém, se o comprimento for mais longo que display_width, a saída será truncada.

    Se display_width for 0, a saída será truncada a 1 MB. Pode-se usar o: comando XML ON para evitar que a saída seja truncada. O comando XML ON é descrito posteriormente neste tópico.

    Observação importanteImportante

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

  • -Ydisplay_width
    Define a variável de script SQLCMDMAXVARTYPEWIDTH do sqlcmd. O padrão é 256. Limita o número de caracteres retornado para os tipos de dados a seguir:

    • char

    • nchar

    • varchar(n), onde 1<n<8000

    • nvarchar(n) onde 1<n<4000

    • sql_variant

  • Opções de relatório de erro

  • -b on error batch abort
    Especifica que o sqlcmd é encerrado e retorna um valor DOS ERRORLEVEL no caso de erro. O valor que é retornado para a variável DOS ERRORLEVEL será 1 quando a mensagem de erro do SQL Server tiver um nível de severidade superior a 10; caso contrário, o valor retornado será 0. Se a opção -V tiver sido definida além de -b, o sqlcmd não reportará um erro se o nível de severidade for inferior aos valores definidos com -V. Os arquivos de lote do prompt de comando podem testar o valor de ERRORLEVEL e tratar o erro adequadamente. O sqlcmd não reporta erros para o nível de severidade 10 (mensagens informativas).

    Se o script sqlcmd contiver um comentário incorreto, um erro de sintaxe ou estiver sem uma variável de script, o ERRORLEVEL retornado será 1.

  • -V severitylevel
    Controla o nível de severidade usado para definir a variável ERRORLEVEL. Mensagens de erro com níveis de severidade menores ou igual a esse valor definem ERRORLEVEL. Valores menores que 0 são reportados como 0. Podem ser usados arquivos de lote e CMD para testar o valor da variável ERRORLEVEL.

  • -merror_level
    Controla quais mensagens de erro serão enviadas ao stdout. Mensagens com um nível de severidade menor ou igual a esse nível são enviadas. Quando esse valor é definido como -1, todas as mensagens, incluindo as informativas, são enviadas. Espaços não são permitidos entre -m e -1. Por exemplo, -m-1 é válido e -m-1 não é.

    Essa opção também define a variável de script SQLCMDERRORLEVEL do sqlcmd. Essa variável tem um padrão de 0.

  • Opções diversas

  • -apacket_size
    Exige um pacote de tamanho diferente. Essa opção define a variável de script SQLCMDPACKETSIZE do sqlcmd. packet_size deve ter um valor entre 512 e 32767. O padrão = 4096. Um tamanho de pacote maior pode melhorar o desempenho da execução de scripts que tenham muitas instruções SQL entre comandos GO. Pode-se solicitar um tamanho de pacote maior. No entanto, se a solicitação for negada, sqlcmd usará o padrão do servidor como o tamanho do pacote.

  • -ccmd_end
    Especifica o terminador de lote. Por padrão, os comandos são encerrados e enviados ao SQL Server digitando a palavra "GO" em uma linha por conta própria. Quando você for redefinir o terminador de lote, não use palavras-chave ou caracteres Transact-SQL reservados que tenham significado especial para o sistema operacional, mesmo se tiverem precedidos por uma barra invertida.

  • -L [ c ] list servers[clean output]
    Lista os computadores servidor localmente configurados e os nomes dos computadores servidor que estão transmitindo na rede. Esse parâmetro não pode ser usado em combinação com outros parâmetros. O número máximo de computadores servidores que pode ser listado é 3000. Se a lista de servidores ficar truncada devido ao tamanho do buffer, será exibida uma mensagem de aviso.

    ObservaçãoObservação

    Devido à natureza da transmissão em redes, o sqlcmd pode não receber uma resposta oportuna de todos os servidores. Assim, a lista de servidores retornada pode variar para cada invocação dessa opção.

    Se for especificado o parâmetro opcional c, a saída aparecerá sem os servidores: linha de cabeçalho e cada linha de servidor será listada sem espaços à esquerda. Isso é chamado de saída normal. A saída normal melhora o desempenho de processamento das linguagens dos scripts.

  • -p[ 1 ] print statistics[colon format]
    Imprime estatísticas de desempenho para cada conjunto de resultados. O exemplo a seguir mostra o 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.)

    Onde:

    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 estão em milissegundos.

    Se for especificado o parâmetro opcional 1, o formato de saída das estatísticas estará em formato separado por dois pontos, que pode ser facilmente importado para uma planilha ou processado por um script.

    Se o parâmetro opcional for qualquer valor diferente de 1, um erro será gerado e o sqlcmd será fechado.

  • -X [ 1 ] disable commands, startup script, enviroment variables [and exit]
    Desabilita os comandos que podem comprometer a segurança do sistema quando o sqlcmd for executado a partir de um arquivo de lote. Os comandos desabilitados ainda são reconhecidos; o sqlcmd emite uma mensagem de aviso e continua. Se o parâmetro opcional 1 for especificado, o sqlcmd gerará uma mensagem de erro e será fechado. Os comandos a seguir são desabilitados quando a opção -X é usada:

    • ED

    • **!!**command

    Se a opção -X for especificada, isso impedirá que as variáveis ambientais sejam transmitidas para o sqlcmd. Evita também que o script de inicialização especificado, usando a variável de script SQLCMDINI, seja executado. Para obter mais informações sobre variáveis de script sqlcmd, consulte Usando sqlcmd com variáveis de script.

  • -? show syntax summary
    Exibe o resumo da sintaxe de opções sqlcmd.

Comentários

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

Quando vários resultados são retornados, o sqlcmd imprime uma linha em branco entre cada conjunto de resultados de um lote. Além disso, a mensagem "<x> linhas afetadas" não aparece quando não se aplica à instrução executada.

Para usar o sqlcmd interativamente, digite sqlcmd no prompt de comando com uma ou mais das opções descritas anteriormente neste tópico. Para obter mais informações, consulte Usando o utilitário sqlcmd

ObservaçãoObservação

As opções -L, -Q, -Z ou -i fazem com que o sqlcmd seja fechado após a execução.

O comprimento total da linha de comando sqlcmd no ambiente de comando (Cmd.exe), incluindo todos os argumentos e variáveis expandidas, é aquele determinado pelo sistema operacional para Cmd.exe.

Precedência de variável (baixa para alta)

  1. Variáveis ambientais do nível de sistema.

  2. Variáveis ambientais do nível de usuário.

  3. Shell de comando (SET X=Y) definido no prompt de comando antes da execução do sqlcmd.

  4. sqlcmd-v X=Y

  5. :Setvar X Y

ObservaçãoObservação

Para exibir as variáveis ambientais, no Painel de Controle, abra Sistema e clique na guia Avançado.

Variáveis de script do sqlcmd

Variável

Opção relacionada

R/W

Padrão

SQLCMDUSER

-U

R

""

SQLCMDPASSWORD

-P

--

""

SQLCMDSERVER

-S

R

"DefaultLocalInstance"

SQLCMDWORKSTATION

-H

R

"ComputerName"

SQLCMDDBNAME

-d

R

""

SQLCMDLOGINTIMEOUT

-l

R/W

"8" (segundos)

SQLCMDSTATTIMEOUT

-t

R/W

"0" = espere indefinidamente

SQLCMDHEADERS

-h

R/W

"0"

SQLCMDCOLSEP

-s

R/W

" "

SQLCMDCOLWIDTH

-w

R/W

"0"

SQLCMDPACKETSIZE

-a

R

"4096"

SQLCMDERRORLEVEL

-m

R/W

0

SQLCMDMAXVARTYPEWIDTH

-y

R/W

"256"

SQLCMDMAXFIXEDTYPEWIDTH

-Y

R/W

"0" = ilimitado

SQLCMDEDITOR

R/W

"edit.com"

SQLCMDINI

R

""

SQLCMDUSER, SQLCMDPASSWORD e SQLCMDSERVER são definidos quando :Conectar

é usado.

R indica que o valor pode ser definido apenas uma vez durante a inicialização do programa.

R/W indica que o valor pode ser modificado usando o comando setvar e que os comandos subsequentes serão influenciados pelo novo valor.

Comandos sqlcmd

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

GO [count]

:List

[:] RESET

:Error

[:] ED

:Out

[:] !!

:Perftrace

[:] QUIT

:Connect

[:] EXIT

:On Error

:r

:Help

:ServerList

:XML [ON | OFF]

:Setvar

:Listvar

Ao usar os seguintes comandos do sqlcmd lembre-se de que:

  • Todos os comandos do sqlcmd, exceto GO, devem ser antecedidos de dois pontos (:).

    Observação importanteImportante

    Para manter a compatibilidade com versões anteriores de scripts osql existentes, alguns dos comandos serão reconhecidos sem os dois pontos. Isso é indicado por [:].

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

  • Todos os comandos do 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 do Transact-SQL ou por outro comando.

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

  • Editando comandos

  • [:] ED
    Inicie o editor de textos. Esse editor pode ser usado para editar o lote atual do Transact-SQL 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 textos é definido pela variável de ambiente SQLCMDEDITOR. O editor padrão é 'Editar.' Para alterar o editor, defina a variável de ambiente SQLCMDEDITOR. Por exemplo, para definir o editor como Microsoft Notepad, no prompt de comando, digite:

    SET SQLCMDEDITOR=notepad

  • [:] RESET
    Desmarca o cache de instruções.

  • :List
    Imprime o conteúdo do cache de instrução.

  • Variáveis

  • :Setvar <var> [ "value" ]
    Define as variáveis de script do sqlcmd. As 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:

    • Usando-se implicitamente uma opção de linha de comando. Por exemplo, a opção -l define a variável SQLCMDLOGINTIMEOUT do sqlcmd.

    • Explicitamente, usando o comando :Setvar.

    • Definindo uma variável de ambiente antes de executar sqlcmd.

    ObservaçãoObservação

    A opção -X impede que variáveis ambientais sejam transmitidas para o sqlcmd.

    Se uma variável definida com o uso de :Setvar e uma variável ambiental tiver o mesmo nome, a variável definida com o uso de :Setvar terá precedência.

    Nomes de variáveis não devem conter caracteres de espaço em branco.

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

  • :Listvar
    Exibe uma lista das variáveis de script definidas atualmente.

    ObservaçãoObservação

    Somente as variáveis de script definidas por sqlcmd e as definidas com o uso do comando :Setvar serão exibidas.

  • Comandos de saída

  • :Error **<filename>|STDERR|STDOUT
    Redireciona toda a saída de erro para o arquivo especificado por file name, 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.

    • file name
      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 outras razões, a saída não será alternada e será enviada ao último destino especificado ou ao destino padrão.

    • STDERR
      Alterna a saída de erro para o fluxo stderr. Se houver redirecionamento, o destino para o qual o fluxo foi redirecionado receberá a saída de erro.

    • STDOUT
      Alterna a saída de erro para o fluxo stdout. Se houver redirecionamento, o destino para o qual o fluxo foi redirecionado receberá a saída de erro.

  • :Out <filename>| STDERR| STDOUT
    Cria e redireciona todos os resultados de consulta para o arquivo especificado por file name, para stderr ou para 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.

  • :Perftrace <filename>| STDERR| STDOUT
    Cria e redireciona todas as informações de rastreamento de desempenho para o arquivo especificado por file name, para stderr ou para 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

  • :On Error[ exit | ignore]
    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 exitfor usada, o sqlcmd será fechado com o valor de erro apropriado.

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

  • [:] QUIT
    Faz com que o sqlcmd seja fechado.

  • [:] EXIT[ (statement) ]
    Permite usar o resultado de uma instrução SELECT como o valor de retorno 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 transmite o byte baixo para o processo pai ou nível de erro do sistema operacional. O Windows 200x passa todo o número 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 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**()** com nada entre parênteses executa tudo antes dela no lote e é encerrada sem um valor de retorno.

    Quando uma consulta incorreta é especificada, o sqlcmd será fechado sem valor de retorno.

    Eis uma lista de formatos EXIT:

    • :EXIT

    Não executa o lote e então sai imediatamente e não retorna valor algum.

    • :EXIT( )

    Executa o lote e então sai imediatamente e não retorna valor algum.

    • :EXIT(query)

    Executa o lote que inclui a consulta, e então sai depois de retornar os resultados da consulta.

    Se RAISERROR for usado em um script sqlcmd e um estado de 127 for gerado, o sqlcmd será fechado e retornará a ID de mensagem para o 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; o sqlcmd define os seguintes valores de retorno adicionais:

    Valores de retorno

    Descrição

    -100

    Erro encontrado antes da seleção do valor de retorno.

    -101

    Nenhuma linha encontrada ao se selecionar o valor de retorno.

    -102

    Erro de conversão ao selecionar valor de retorno.

  • GO [count]
    GO sinaliza tanto o término de um lote quanto a execução de qualquer instrução de cachê do Transact-SQL. Ao especificar um valor para count, serão executadas as instruções de cache count vezes, como um único lote.

  • Comandos diversos

  • :r <filename>
    Analisa instruções Transact-SQL adicionais e comandos sqlcmd do arquivo especificado por <filename>* *no cache de instruções.

    Se o arquivo contiver instruções Transact-SQL que não são seguidas por GO, será necessário digitar GO na linha seguinte a :r.

    ObservaçãoObservação

    <filename> é lido em relação ao diretório de inicialização em que o sqlcmd foi executado.

    O arquivo será lido e executado depois que for encontrado um terminador de lote. É possível emitir vários comandos :r. O arquivo pode incluir qualquer comando sqlcmd. Isso inclui o terminador de lote GO.

    ObservaçãoObservação

    A contagem de linha exibida em modo interativo será aumentada em um para cada comando :r encontrado. O comando :r aparecerá na saída do comando de lista.

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

    Opções de tempo limite:

    0

    esperar

    n>0

    esperar por n segundos

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

    Se não for especificado timeout, o valor da variável SQLCMDLOGINTIMEOUT será o padrão.

    Se for especificado apenas user_name (como opção, ou como uma variável de ambiente), o usuário será solicitado a digitar uma senha. Isso não ocorre se as variáveis de ambiente SQLCMDUSER ou SQLCMDPASSWORD tiverem sido definidas. Se as opções e as variáveis de ambiente não forem fornecidas, o modo de Autenticação do Windows será usado para fazer logon. Por exemplo, para conectar-se a uma instância, instance1, do SQL Server, myserver, usando segurança integrada você usaria o seguinte:

    :connect myserver\instance1

    Para conectar-se à instância padrão do myserver usando variáveis de script, você usaria o seguinte:

    :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 pelo comando do sistema operacional. Por exemplo:

    :!! Dir

    ObservaçãoObservação

    O comando é executado no computador em que o sqlcmd está em execução.

  • :XML [ON | OFF]
    Para obter mais informações, consulte "XML Output Format", posteriormente neste tópico.

  • :Help
    Lista comandos sqlcmd juntamente com uma breve descrição de cada comando.

Nomes de arquivos sqlcmd

Os arquivos de entrada sqlcmd 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, :Out e :Perftrace devem usar <filename> separados. Se for usado o mesmo <filename>, as entradas dos comandos poderão ser misturadas.

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

  • Os caminhos de arquivo válido 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 do sqlcmd substituirá os arquivos existentes que tiverem os mesmos nomes.

Mensagens informativas

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

No prompt de comando, digite o seguinte:

sqlcmd

At the sqlcmd prompt type:

USE AdventureWorks2008R2;

GO

Ao pressionar ENTER, será impressa a seguinte mensagem informativa: "Contexto de banco de dados alterado para 'AdventureWorks2008R2'."

Formato de saída do Transact-SQL Queries

O sqlcmd imprime primeiramente um cabeçalho de coluna com os nomes de coluna especificados na lista de seleção. Os nomes de coluna são separados usando-se o caractere SQLCMDCOLSEP. Por padrão, esse é 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 será seguida por uma linha divisória formada por uma série de tracejados. A saída a seguir mostra um exemplo.

Inicie o sqlcmd. No prompt de comando do sqlcmd, digite o seguinte:

USE AdventureWorks2008R2;

SELECT TOP (2) BusinessEntityID, FirstName, LastName

FROM Person.Person;

GO

Ao pressionar ENTER, o seguinte conjunto de resultados é reajustado.

BusinessEntityID FirstName    LastName

---------------- ------------ ----------

285              Syed         Abbas

293              Catherine    Abel

(2 row(s) affected)

Embora a coluna BusinessEntityID tenha apenas 4 caracteres de largura, ela foi expandida para acomodar o nome de coluna mais longo. Por padrão, a saída é finalizada com 80 caracteres. Isso pode ser alterado com a opção -w, ou definindo a variável de script SQLCMDCOLWIDTH.

Formato de saída XML

Saída XML é o resultado de uma cláusula FOR XML, não formatada, em um fluxo contínuo.

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

ObservaçãoObservação

O sqlcmd retorna mensagens de erro no formato habitual. Observe que as mensagens de erro também são produzidas no fluxo de texto XML em formato XML. Usando :XML ON, o sqlcmd não exibe mensagens informativas.

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

O comando GO não deve aparecer antes de o comando XML OFF ser emitido uma vez que o comando XML OFF retorna o sqlcmd para a saída orientada por linha.

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 da execução de uma instrução do Transact-SQL que gera protocolos XML, a saída será adulterada. Se o comando XML ON tiver sido emitido, não será possível executar instruções do Transact-SQL que gerem conjuntos de linhas normais.

ObservaçãoObservação

O comando :XML não oferece suporte para a instrução SET STATISTICS XML.

Práticas recomendadas sqlcmd

Use as seguintes práticas para ajudar a maximizar a segurança e a eficiência.

  • Use segurança integrada.

  • Use -X em ambientes automatizados.

  • Proteja arquivos de entrada e de saída usando permissões adequadas de sistema de arquivos NTFS.

  • Para aumentar o desempenho, faça o máximo possível em uma sessão do sqlcmd, em vez de usar uma série de sessões.

  • Defina valores mais altos de tempo limite para execução em lote ou de consulta do que você imagina que levará para a execução em lote ou de consulta.