Usar sqlcmd com variáveis de script

Aplica-se a:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Sistema 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.

Variáveis de script no sqlcmd

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 setvar comando ou implicitamente usando a sqlcmd -v opção.

Este artigo também inclui exemplos que definem variáveis de ambiente na linha de comando usando SET.

Definir variáveis de script com o comando setvar

O setvar comando define variáveis de script. As variáveis que são definidas usando o setvar comando 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 setvaro , 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

Note

Para exibir as variáveis ambientais no Windows 11, abra Configurações, navegue atéSobre o > e selecione o link Configurações avançadas do sistema. Na janela Propriedades do sistema, selecione Variáveis de ambiente. No Linux, digite printenv na linha de comando e, no macOS, digite env.

Definir implicitamente 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

Note

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 -v opção 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 scripting do sqlcmd

Variable	Opção relacionada	R/W	Default
`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" = 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 e os setvar comandos subsequentes usam o novo valor.

Examples

Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que pode ser descarregado da página inicial de Exemplos e Projetos da Comunidade do Microsoft SQL Server.

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

Note

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á o conjunto 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

Comentários

Esta página foi útil?

Last updated on 2025-11-19

Partilhar via

Usar sqlcmd com variáveis de script

Variáveis de script no sqlcmd

Definir variáveis de script com o comando setvar

Precedência variável (baixa a alta)

Definir implicitamente variáveis de script

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

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

Variáveis de scripting do sqlcmd

Examples

A. Usar o comando setvar em um script

B. Utilize o comando setvar de forma interativa

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

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

E. Usar um script de inicialização

F. Expansão variável

Conteúdo relacionado

Comentários

Recursos adicionais