sqlcmd - Uso com variáveis de script

Artigo
03/08/2025

Aplica-se a:SQL Server Azure SQL Database Instância Gerenciada do SQL do Azure Azure Synapse Analytics Analytics Platform System (PDW)Banco de Dados SQL no Microsoft Fabric

As variáveis usadas em scripts são chamadas de variáveis de script. As variáveis de script permitem que um script seja usado em vários cenários. Por exemplo, se você quiser executar um script em vários servidores, em vez de modificar o script para cada servidor, você pode usar uma variável de script para o nome do servidor. Ao alterar o nome do servidor fornecido para a variável de script, o mesmo script pode ser executado em servidores diferentes.

As variáveis de script podem ser definidas explicitamente usando o comando setvar ou implicitamente usando a opção sqlcmd -v.

Este artigo também inclui exemplos que definem variáveis ambientais no prompt de comando Cmd.exe usando SET.

Definir variáveis de script com o comando setvar

O comando setvar é usado para definir variáveis de script. As variáveis que são definidas usando o comando setvar são armazenadas internamente. As variáveis de script não devem ser confundidas com as variáveis de ambiente que são definidas no prompt de comando usando SET. Se um script fizer referência a uma variável que não seja uma variável de ambiente ou não seja definida usando setvar, uma mensagem de erro será retornada e a execução do script será interrompida. Para obter mais informações, consulte a opção -b em sqlcmd.

Precedência variável (baixa a alta)

Se mais de um tipo de variável tiver o mesmo nome, a variável com a maior precedência será usada.

Variáveis ambientais ao nível do sistema
Variáveis ambientais ao nível do utilizador
Linha de comandos (SET X=Y) definida no prompt de comando antes de iniciar o sqlcmd
sqlcmd -v X=Y
:Setvar X Y

Observação

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

Definição implícita de variáveis de script

Quando inicias sqlcmd com uma opção que tem uma variável sqlcmd relacionada, a variável sqlcmd é definida implicitamente com o valor especificado ao usar a opção. No exemplo a seguir, sqlcmd é iniciado com a opção -l. Isso implicitamente define a variável SQLLOGINTIMEOUT.

sqlcmd -l 60

Você também pode usar a opção -v para definir uma variável de script que existe em um script. No script a seguir (o nome do arquivo é testscript.sql), ColumnName é uma variável de script.

USE AdventureWorks2022;

SELECT x.$(ColumnName)
FROM Person.Person x
WHERE x.BusinessEntityID < 5;

Em seguida, você pode especificar o nome da coluna que deseja retornar usando a opção -v:

sqlcmd -v ColumnName ="FirstName" -i c:\testscript.sql

Para retornar uma coluna diferente usando o mesmo script, altere o valor da variável de script ColumnName.

sqlcmd -v ColumnName ="LastName" -i c:\testscript.sql

Diretrizes para a escrita de nomes e valores de variáveis

Considere as seguintes diretrizes ao nomear variáveis de script:

Os nomes das variáveis não devem conter caracteres de espaço em branco ou aspas.
Os nomes de variáveis não devem ter a mesma forma que uma expressão variável, como $(var).
As variáveis de script não diferenciam maiúsculas de minúsculas

Observação

Se nenhum valor for atribuído a uma variável de ambiente sqlcmd, a variável será removida. Usar :setvar VarName sem um valor limpa a variável.

Considere as seguintes diretrizes ao especificar valores para variáveis de script:

Os valores de variáveis que são definidos usando setvar ou a opção -v devem ser colocados entre aspas se o valor da cadeia de caracteres contiver espaços.
Se as aspas fizerem parte do valor da variável, elas devem ser escapadas. Por exemplo: :setvar MyVar "spac""e".

Diretrizes para valores e nomes de variáveis do tipo SET cmd.exe

As variáveis que são definidas usando SET fazem parte do ambiente de cmd.exe e podem ser referenciadas por sqlcmd. Considere as seguintes diretrizes:

Os nomes das variáveis não devem conter caracteres de espaço em branco ou aspas.
Os valores das variáveis podem conter espaços ou aspas.

Variáveis de script sqlcmd

As variáveis definidas por sqlcmd são conhecidas como variáveis de script. A tabela a seguir lista as variáveis de script de sqlcmd.

Variável	Opção relacionada	R/W	Padrão
SQLCMDUSER ¹	-U	R ²	""
SQLCMDPASSWORD ¹	-P	--	""
SQLCMDSERVER ¹	-S	R ²	"DefaultLocalInstance"
SQLCMDWORKSTATION	-H	R ²	"Nome do computador"
SQLCMDDBNAME	-d	R ²	""
SQLCMDLOGINTIMEOUT	-l	R/W ³	"8" (segundos)
SQLCMDSTATTIMEOUT	-t	R/W ³	"0" = esperar 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 :Connect é usado.

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

³ R/W indica que o valor pode ser redefinido usando o comando setvar e os comandos subsequentes usam o novo valor.

Exemplos

Um. Usar o comando setvar em um script

Muitas opções de sqlcmd podem ser controladas em um script usando o comando setvar. No exemplo a seguir, o script test.sql é criado no qual a variável SQLCMDLOGINTIMEOUT é definida para 60 segundos e outra variável de script, server, é definida como testserver. O código a seguir está em test.sql.

:setvar SQLCMDLOGINTIMEOUT 60
:setvar server "testserver"
:connect $(server) -l $(SQLCMDLOGINTIMEOUT)

USE AdventureWorks2022;

SELECT FirstName, LastName
FROM Person.Person;

O script é então chamado usando sqlcmd:

sqlcmd -i c:\test.sql

B. Utilize o comando setvar de forma interativa

O exemplo a seguir mostra como definir uma variável de script interativamente usando o comando setvar.

sqlcmd
:setvar MYDATABASE AdventureWorks2022
USE $(MYDATABASE);
GO

Aqui está o conjunto de resultados.

Changed database context to 'AdventureWorks2022'
1>

C. Usar variáveis de ambiente de prompt de comando dentro do sqlcmd

No exemplo a seguir, quatro variáveis de ambiente are são definidas e chamadas em seguida a partir de sqlcmd.

SET tablename=Person.Person
SET col1=FirstName
SET col2=LastName
SET title=Ms.
sqlcmd -d AdventureWorks2022
1> SELECT TOP 5 $(col1) + ' ' + $(col2) AS Name
2> FROM $(tablename)
3> WHERE Title ='$(title)'
4> GO

D. Usar variáveis de ambiente de nível de usuário no sqlcmd

No exemplo a seguir, a variável ambiental de nível de usuário %Temp% é definida no prompt de comando e passada para o arquivo de entrada sqlcmd. Para obter a variável de ambiente de nível de utilizador, no Painel de Controlo, clique duas vezes no Sistema. Selecione a guia Advance e, em seguida, selecione Variáveis de Ambiente.

O código a seguir está no arquivo de entrada C:\testscript.txt:

:OUT $(MyTempDirectory)
USE AdventureWorks2022;

SELECT FirstName
FROM AdventureWorks2022.Person.Person
WHERE BusinessEntityID < 5;

Este código a seguir é inserido no prompt de comando:

SET MyTempDirectory=%Temp%\output.txt
sqlcmd -i C:\testscript.txt

O resultado a seguir é enviado para o arquivo de saída C:\Documents and Settings\<user>\Local Settings\Temp\output.txt.

Changed database context to 'AdventureWorks2022'.
FirstName
--------------------------------------------------
Gustavo
Catherine
Kim
Humberto

(4 rows affected)

E. Usar um script de inicialização

Um script de inicialização do sqlcmd é executado quando o sqlcmd é iniciado. O exemplo a seguir define a variável de ambiente SQLCMDINI. Este é o conteúdo de init.sql.

SET NOCOUNT ON
GO

DECLARE @nt_username nvarchar(128)
SET @nt_username = (SELECT rtrim(convert(nvarchar(128), nt_username))
FROM sys.dm_exec_sessions WHERE spid = @@SPID)
SELECT  @nt_username + ' is connected to ' +
rtrim(CONVERT(nvarchar(20), SERVERPROPERTY('servername'))) +
' (' +`
rtrim(CONVERT(nvarchar(20), SERVERPROPERTY('productversion'))) +
')'
:setvar SQLCMDMAXFIXEDTYPEWIDTH 100
SET NOCOUNT OFF
GO

:setvar SQLCMDMAXFIXEDTYPEWIDTH

Isso chama o arquivo init.sql quando sqlcmd é iniciado.

SET sqlcmdini=c:\init.sql
sqlcmd

Esta é a saída.

1> <user> is connected to <server> (9.00.2047.00)

Observação

A opção -X desativa o recurso de script de inicialização.

F. Expansão variável

O exemplo a seguir mostra o trabalho com dados na forma de uma variável sqlcmd.

USE AdventureWorks2022;
GO
CREATE TABLE AdventureWorks2022.dbo.VariableTest (Col1 NVARCHAR(50));
GO

Insira uma linha em Col1 de dbo.VariableTest que contém o valor $(tablename).

INSERT INTO AdventureWorks2022.dbo.VariableTest (Col1)
VALUES ('$(tablename)');
GO

No prompt sqlcmd, quando nenhuma variável é definida como igual a $(tablename), as instruções a seguir retornam a linha e também retornam a mensagem "'tablename' scripting variable not defined". Por padrão, o sinalizador sqlcmd -b não está definido. Se -b estiver definido, o sqlcmd será encerrado após ocorrer o erro "variável não definida".

sqlcmd
1> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(tablename)';
2> GO
3> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(tablename)';
4> GO

Aqui está a lista de resultados.

1> Col1
2> ------------------
3> $(tablename)
4>
5> (1 rows affected)

Dada a variável MyVar, esta é definida como $(tablename).

6> :setvar MyVar $(tablename)

Essas instruções devolvem a linha e também devolvem a mensagem "variável de scripting 'tablename' não definida".

6> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(tablename)';
7> GO

1> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(tablename)';
2> GO

Essas instruções retornam a linha.

1> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(MyVar)';
2> GO

1> SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(MyVar)';
2> GO

Partilhar via