sqlcmd 实用工具

使用 sqlcmd 实用工具可以在命令提示符处、在 SQLCMD 模式下的查询编辑器中、在 Windows 脚本文件中或者在 SQL Server 代理作业的操作系统 (Cmd.exe) 作业步骤中输入 Transact-SQL 语句、系统过程和脚本文件。此实用工具使用 OLE DB 执行 Transact-SQL 批处理。

重要说明重要提示

查询编辑器的常规模式和 SQLCMD 模式下,SQL Server Management Studio 使用 Microsoft.NET FrameworkSqlClient 执行批处理。从命令行运行 sqlcmd 时,sqlcmd 将使用 OLE DB 访问接口。由于可以应用不同的默认选项,因此在 SQL Server Management Studio SQLCMD 模式下以及在 sqlcmd 实用工具中执行相同的查询时,可能会看到不同的行为。

语法

sqlcmd 
[{ { -U login_id [ -P password ] } | –E trusted connection }] 
[ -z new password ] [ -Z new password and exit]
[ -S server_name [ \ instance_name ] ] [ -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]

命令行选项

  • 登录相关选项

  • -Ulogin_id
    是用户登录 ID。

    注意注意

    OSQLUSER 环境变量可用于实现向后兼容性。SQLCMDUSER 环境变量优先于 OSQLUSER 环境变量。也就是说,sqlcmdosql 可以彼此相邻使用而不会相互干扰。此外,现有的 osql 脚本可以继续使用。

    如果 -U 选项和 -P 选项均未指定,sqlcmd 将尝试使用 Microsoft Windows 身份验证模式进行连接。身份验证基于运行 sqlcmd 的用户的 Windows 帐户。

    如果 -U 选项与 -E 选项(将在本主题的后面进行说明)一起使用,将生成错误消息。如果 –U 选项后有多个参数,将生成错误消息并退出程序。

  • -Ppassword
    用户指定的密码。密码是区分大小写的。如果使用了 -U 选项而未使用 -P 选项,并且未设置 SQLCMDPASSWORD 环境变量,则 sqlcmd 会提示用户输入密码。如果在命令提示符的末尾使用 -P 选项而不带密码,sqlcmd 将使用默认密码 (NULL)。

    安全说明安全说明

    不要使用空密码。请使用强密码。有关详细信息,请参阅强密码

    通过向控制台输出密码提示,可以显示密码提示,如下所示:Password:

    隐藏用户输入。也就是说,将不会显示任何输入的内容,光标保留原位不动。

    使用 SQLCMDPASSWORD 环境变量可以为当前会话设置默认密码。因此,不必将密码硬编码到批处理文件中。

    以下示例首先在命令提示符处设置 SQLCMDPASSWORD 变量,然后访问 sqlcmd 实用工具。在命令提示符下,键入:

    SET SQLCMDPASSWORD= p@a$$w0rd

    安全说明安全说明

    任何可以看到计算机监视器的人均可看到密码。

    在以下命令提示符处键入:

    sqlcmd

    如果用户名和密码组合不正确,OLE DB 访问接口将生成错误消息。

    注意注意

    为实现向后兼容性而保留了 OSQLPASSWORD 环境变量。SQLCMDPASSWORD 环境变量优先于 OSQLPASSWORD 环境变量;也就是说 sqlcmdosql 可以彼此相邻使用而不会相互干扰,并且旧式脚本可以继续使用。

    如果将 -P 选项与 -E 选项一起使用,将生成错误消息。

    如果 –P 选项后有多个参数,将生成错误消息并退出程序。

  • -Etrusted connection
    使用信任连接而不是用户名和密码登录 SQL Server。默认情况下,如果未指定 -E,sqlcmd 将使用信任连接选项。

    -E 选项会忽略可能的用户名和密码环境变量设置,例如 SQLCMDPASSWORD。如果将 -E 选项与 -U 选项或 -P 选项一起使用,将生成错误消息。

  • -znew password
    更改密码:

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

  • -Znew password and exit
    更改密码并退出:

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

  • -Sserver_name [ **\**instance_name ]
    指定要连接的 SQL Server 的实例。它设置 sqlcmd 脚本变量 SQLCMDSERVER。

    指定 server_name 将连接到该服务器中 SQL Server 的默认实例。指定 server_name [ **\**instance_name ] 将连接到该服务器上 SQL Server 的命名实例。如果未指定服务器,sqlcmd 将连接到本地计算机上的 SQL Server 的默认实例。从网络上的远程计算机执行 sqlcmd 时,此选项是必需的。

    如果在启动 sqlcmd 时未指定 server_name [ **\**instance_name ],SQL Server 将检查并使用 SQLCMDSERVER 环境变量。

    注意注意

    为实现向后兼容性而保留了 OSQLSERVER 环境变量。SQLCMDSERVER 环境变量优先于 OSQLSERVER 环境变量;也就是说 sqlcmdosql 可以彼此相邻使用而不会相互干扰,并且旧式脚本可以继续使用。

  • -Hwksta_name
    工作站的名称。此选项设置 sqlcmd 脚本变量 SQLCMDWORKSTATION。工作站名称列出在 sys.processes 目录视图的 hostname 列中,并且可使用存储过程 sp_who 返回。如果不指定此选项,则默认为当前计算机名称。此名称可用来标识不同的 sqlcmd 会话。

  • -ddb_name
    启动 sqlcmd 时发出一个 USE db_name 语句。此选项设置 sqlcmd 脚本变量 SQLCMDDBNAME。它指定初始数据库。默认为您的登录名的默认数据库属性。如果数据库不存在,则生成错误消息且 sqlcmd 退出。

  • -llogintime_out
    指定在您尝试连接到服务器时 OLE DB 访问接口的 sqlcmd 登录超时时间(以秒计)。此选项设置 sqlcmd 脚本变量 SQLCMDLOGINTIMEOUT。登录 sqlcmd 的默认超时时间为 8 秒。登录超时设定必须是介于 0 和 65534 之间的数字。如果提供的值不是数值或不在此范围内,sqlcmd 将生成错误消息。该值为 0 时,则允许无限制等待。

  • -Adedicated admin connection
    使用专用管理员连接 (DAC) 登录到 SQL Server。此类型连接用于排除服务器故障。这只适用于支持 DAC 的服务器。如果 DAC 不可用,sqlcmd 会生成错误消息,然后退出。有关 DAC 的详细信息,请参阅使用专用管理员连接

  • 输入/输出选项

  • -iinput_file[***,***input_file2...]
    标识包含一批 SQL 语句或存储过程的文件。可以指定要按顺序读取和处理的多个文件。文件名之间不要使用任何空格。sqlcmd将首先检查所有指定的文件是否都存在。如果有一个或多个文件不存在,sqlcmd 将退出。-i 和 -Q/-q 选项是互斥的。

    路径示例:

    -i C:\<filename>

    -i \\<Server>\<Share$>\<filename>

    -i "C:\Some Folder\<file name>"

    包含空格的文件路径必须用引号引起来。

    此选项可能多次使用:-i input_file -i I input_file.

  • -ooutput_file
    标识从 sqlcmd 接收输出的文件。

    如果指定了 -u,则 output_file 以 Unicode 格式存储。如果文件名无效,将生成一个错误消息,并且 sqlcmd 将退出。sqlcmd 不支持向同一文件并发写入多个 sqlcmd 进程。文件输出将损坏或不正确。有关文件格式的详细信息,请参阅 -f 开关。如果此文件不存在,将创建此文件。前一个 sqlcmd 会话中的同名文件将被覆盖。此处指定的文件不是 stdout 文件。如果指定了 stdout 文件,将不使用此文件。

    路径示例:

    -o C:\< filename>

    -o \\<Server>\<Share$>\<filename>

    **-o "**C:\Some Folder\<file name>"

    包含空格的文件路径必须用引号引起来。

  • -f < codepage > | i: < codepage > [ <, o: < codepage > ]
    指定输入和输出代码页。代码页页码是指定已安装的 Windows 代码页的数值。有关详细信息,请参阅安装程序中的排序规则设置

    代码页转换规则:

    • 如果未指定代码页,sqlcmd 会将当前代码页同时用于输入文件和输出文件,除非输入文件为 Unicode 文件,在此情况下无需进行转换。

    • sqlcmd 自动识别 Big-endian Unicode 和 Little-endian Unicode 输入文件。如果已指定 -u 选项,输出将始终为 Little-endian Unicode。

    • 如果未指定输出文件,输出代码页将为控制台代码页。这将使输出正确显示在控制台上。

    • 假定多个输入文件具有相同的代码页。可以将 Unicode 和非 Unicode 输入文件混合在一起。

    在命令提示符处输入 chcp 以验证 Cmd.exe 的代码页。

  • -uunicode output
    指定无论 input_file 为何种格式,output_file 都以 Unicode 格式进行存储。

  • -r[ 0 | 1] msgs to stderr
    将错误消息输出重定向到屏幕 (stderr)。如果未指定参数或指定参数为 0,则仅重定向严重级别为 11 或更高的错误消息。如果指定参数为 1,则将重定向所有消息输出(包括 PRINT)。如果使用 -o,将不起任何作用。默认情况下,消息将发送到 stdout

  • -Ruse client regional settings
    设置 SQL Server OLE DB 访问接口,使其在将货币、日期和时间数据转换为字符数据时使用客户端区域设置。默认为服务器区域设置。

  • 查询执行选项

  • -q" cmdline query "
    启动 sqlcmd 时执行查询,但是在查询结束运行时不退出 sqlcmd。可以执行多个以分号分隔的查询。将查询用引号引起来,如下例所示。

    在命令提示符下,键入:

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

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

    重要说明重要提示

    请不要在查询中使用 GO 终止符。

    如果在指定此选项的同时还指定了 -bsqlcmd 在遇到错误时将退出。本主题的后面将介绍 -b

  • **-Q"**cmdline query " and exit
    sqlcmd 启动时执行查询,随后立即退出 sqlcmd。可以执行多个以分号分隔的查询。

    将查询用引号引起来,如下例所示。

    在命令提示符下,键入:

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

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

    重要说明重要提示

    请不要在查询中使用 GO 终止符。

    如果在指定此选项的同时还指定了 -bsqlcmd 在遇到错误时将退出。本主题的后面将介绍 -b

  • -eecho input
    将输入脚本写入标准输出设备 (stdout)。

  • -Ienable Quoted Identifiers
    将 SET QUOTED_IDENTIFIER 连接选项设置为 ON。默认情况下,此选项设置为 OFF。有关详细信息,请参阅 SET QUOTED_IDENTIFIER (Transact-SQL)

  • -tquerytime_out
    指定命令(或 SQL 语句)超时的时间。此选项设置 sqlcmd 脚本变量 SQLCMDSTATTIMEOUT。如果未指定 time_out 值,则命令将不会超时。querytime_out 必须是介于 1 和 65535 之间的数字。如果提供的值不是数值或不在此范围内,则 sqlcmd 将生成错误消息。

    注意注意

    实际的超时值可能会与指定的 time_out 值相差几秒。

  • -vvar*=value[ var=*value...]
    创建可用于 sqlcmd 脚本中的 sqlcmd脚本变量。如果该值包含空格,则将其用引号引起来。可以指定多个 var="values" 值。如果指定的任何值中有错误,sqlcmd 会生成错误消息,然后退出。

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

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

  • -xdisable variable substitution
    导致 sqlcmd 忽略脚本变量。当脚本中包含多个 INSERT 语句,并且这些语句可能包含格式与常规变量(如 $(variable_name))相同的字符串时,这一选项很有用。

  • 格式设置选项

  • -hheaders
    指定要在列标题之间输出的行数。默认为每一组查询结果输出一次标题。此选项设置 sqlcmd 脚本变量 SQLCMDHEADERS。使用 -1 指定不能输出标题。任何无效的值都将导致 sqlcmd 生成错误消息并随后退出。

  • -scol_separator
    指定列分隔符字符。默认为空格。此选项设置 sqlcmd 脚本变量 SQLCMDCOLSEP。若要使用对操作系统有特殊含义的字符,如“与”符号 (&) 或分号 (;),请将该字符用双引号 (") 引起来。列分隔符可以是任意 8 位字符。

  • -wcolumn_width
    指定用于输出的屏幕宽度。此选项设置 sqlcmd 脚本变量 SQLCMDCOLWIDTH。该列宽必须是介于 8 和 65536 之间的数字。如果指定的列宽不在此范围内,则 sqlcmd 将生成错误消息。默认宽度为 80 个字符。在输出行超出指定的列宽时,将转到下一行。

  • -Wremove trailing spaces
    此选项删除列的尾随空格。在准备要导出到另一应用程序的数据时,请将此选项和 -s 选项结合使用。不能与 -y-Y 选项结合使用。

  • -k[ 1 | 2 ] remove[replace] control characters
    删除输出中的所有控制字符,例如制表符和换行符。这会在返回数据时保留列格式。如果指定了 1,则控制字符被一个空格替代。如果指定了 2,则连续的控制字符被一个空格替代。

  • -ydisplay_width
    设置 sqlcmd 脚本变量 SQLCMDMAXFIXEDTYPEWIDTH。默认值为 0 (未设置)。它限制为下列大型可变长度数据类型返回的字符的数目:

    • varchar(max)

    • nvarchar(max)

    • varbinary(max)

    • xml

    • UDT(用户定义数据类型)

    • text

    • ntext

    • image

    注意注意

    根据实现,UDT 可以使用固定的长度。如果此固定长度 UDT 的长度比 display_width 短,则返回的 UDT 值将不会受影响。但是,如果此长度比 display_width 长,则输出将会被截断。

    如果 display_width 为 0,则输出将会在 1 MB 处截断。您可以使用 :XML ON 命令防止输出被截断。本主题的后面将介绍 :XML ON 命令。

    重要说明重要提示

    使用 -y 0 选项时要特别注意,因为根据返回的数据量大小,此选项可能导致服务器和网络上出现严重性能问题。

  • -Ydisplay_width
    设置 sqlcmd 脚本变量 SQLCMDMAXVARTYPEWIDTH。默认值为 256。它限制为以下数据类型返回的字符数:

    • char

    • nchar

    • varchar(n),其中 1<n<8000

    • nvarchar(n),其中 1<n<4000

    • sql_variant

  • 错误报告选项

  • -b on error batch abort
    指定错误发生时 sqlcmd 退出并返回一个 DOS ERRORLEVEL 值。当 SQL Server 错误消息的严重级别高于 10 时,返回给 DOS ERRORLEVEL 变量的值为 1;否则返回的值为 0。如果除 -b 选项外还设置了 -V 选项,则当严重等级低于使用 -V 设置的值时,sqlcmd 将不报告错误。命令提示符批处理文件可以测试 ERRORLEVEL 的值并适当处理错误。sqlcmd 不对严重级别 10 报告错误(信息性消息)。

    如果 sqlcmd 脚本包含错误的注释、语法错误或缺少脚本变量,则返回的 ERRORLEVEL 为 1。

  • -Vseveritylevel
    控制用于设置 ERRORLEVEL 变量的安全级别。安全级别小于或等于此值的错误消息将设置 ERRORLEVEL。小于 0 的值将报告为 0。可以使用批处理文件和 CMD 文件来测试 ERRORLEVEL 变量的值。

  • -merror_level
    控制将哪些错误消息发送到 stdout。将发送安全级别小于或等于此级别的消息。如果此值设置为 -1,将发送所有消息(包括信息性消息)。在 -m-1 之间不允许有空格。例如,-m-1 有效,而 -m-1 无效。

    此选项还设置 sqlcmd 脚本变量 SQLCMDERRORLEVEL。此变量的默认值为 0。

  • 其他选项

  • -apacket_size
    需要不同大小的数据包。该选项设置 sqlcmd 脚本变量 SQLCMDPACKETSIZE。packet_size 必须是介于 512 和 32767 之间的值。默认值为 4096。如果脚本的两个 GO 命令之间包含大量 SQL 语句,则使用较大的数据包可以提高脚本执行的性能。您可以请求更大的包大小。但是,如果请求遭拒绝,sqlcmd 将对包大小使用服务器默认值。

  • -ccmd_end
    指定批处理终止符。默认情况下,通过单独在一行中键入“GO”来终止命令并将其发送到 SQL Server。重置批处理终止符时,不要使用对操作系统具有特殊意义的 Transact-SQL 保留关键字或字符,即便它们前面有反斜杠也是如此。

  • -L [ c ] list servers[clean output]
    列出在本地配置的服务器和在网络上广播的服务器的名称。此参数不能与其他参数结合使用。可以列出的服务器的最大数目是 3000。如果服务器列表由于缓冲区大小而被截断,则会显示错误消息。

    注意注意

    鉴于网络广播的特点,sqlcmd 不可能及时接收来自所有服务器的响应。因此,每次调用该选项所返回的服务器列表都可能不同。

    如果指定可选参数 c,则输出不会显示 Servers: 标题行,并且列出的每个服务器行都没有前导空格。这被称为清除输出。清除输出可以提高脚本语言的处理性能。

  • -p[ 1 ] print statistics[colon format]
    输出每个结果集的性能统计信息。以下示例是性能统计信息的格式:

    Network packet size (bytes): n

    x xact[s]:

    Clock Time (ms.): total t1 avg t2 (t3 xacts per sec.)

    其中:

    x = SQL Server 处理的事务数。

    t1 = 所有事务的总时间。

    t2 = 单个事务的平均时间。

    t3 = 每秒的平均事务数。

    所有时间均以毫秒表示。

    如果指定了可选参数 1,则统计信息的输出格式为以冒号分隔的格式,此格式可以由脚本轻松导入到电子表格中或进行处理。

    如果可选参数是除 1 之外的任何值,则将生成错误并且 sqlcmd 将退出。

  • -X [ 1 ] disable commands, startup script, enviroment variables [and exit]
    从批处理文件执行 sqlcmd 时,将禁用可能危及系统安全的命令。禁用的命令仍然可以被识别;sqlcmd 发出警告消息并继续。如果指定了可选参数 1,则 sqlcmd 将生成错误消息,然后退出。使用 -X 选项时,将禁用以下命令:

    • ED

    • **!!**command

    如果指定 -X 选项,它会阻止将环境变量传递给 sqlcmd。同时该选项还会阻止执行通过使用 SQLCMDINI 脚本变量指定的启动脚本。有关 sqlcmd 脚本变量的详细信息,请参阅将 sqlcmd 与脚本变量结合使用

  • -? show syntax summary
    显示 sqlcmd 选项的语法摘要。

注释

不必按语法部分所示的顺序使用选项。

在返回多个结果时,sqlcmd 在批处理中的每个结果集之间输出一个空行。此外,如果没有应用于已执行的语句,则“<x> 行受影响”消息不会出现。

若要交互使用 sqlcmd,请在命令提示符处使用本主题前面介绍的一个或多个选项键入 sqlcmd。有关详细信息,请参阅使用 sqlcmd 实用工具

注意注意

-L-Q-Z-i 选项会导致 sqlcmd 在完成执行后退出。

命令环境 (Cmd.exe) 中的 sqlcmd 命令行的总长度(包括所有参数和扩展变量)取决于 Cmd.exe 所在的操作系统。

变量优先级(从低到高)

  1. 系统级环境变量。

  2. 用户级环境变量

  3. 运行 sqlcmd 之前在命令提示符处设置的命令 shell (SET X=Y)。

  4. sqlcmd-v X=Y

  5. :Setvar X Y

注意注意

若要查看环境变量,请在“控制面板”中打开“系统”,然后单击“高级”选项卡。

sqlcmd 脚本变量

变量

相关开关

R/W

默认值

SQLCMDUSER

-U

R

""

SQLCMDPASSWORD

-P

--

""

SQLCMDSERVER

-S

R

"DefaultLocalInstance"

SQLCMDWORKSTATION

-H

R

"ComputerName"

SQLCMDDBNAME

-d

R

""

SQLCMDLOGINTIMEOUT

-l

R/W

"8"(秒)

SQLCMDSTATTIMEOUT

-t

R/W

"0" = 无限期等待

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" = 无限制

SQLCMDEDITOR

R/W

"edit.com"

SQLCMDINI

R

""

SQLCMDUSER、SQLCMDPASSWORD 和 SQLCMDSERVER 是在使用 :Connect

设置的。

R 表示在程序初始化过程中只能设置一次值。

R/W 表示可以使用 setvar 命令修改值,并且后续命令将受新值的影响。

sqlcmd 命令

sqlcmd 中的 Transact-SQL 语句之外,还可使用以下命令:

GO [count]

:List

[:] RESET

:Error

[:] ED

:Out

[:] !!

:Perftrace

[:] QUIT

:Connect

[:] EXIT

:On Error

:r

:Help

:ServerList

:XML [ON | OFF]

:Setvar

:Listvar

使用 sqlcmd 命令时,请注意以下事项:

  • 除 GO 以外,所有 sqlcmd 命令必须以冒号 (:) 为前缀。

    重要说明重要提示

    为了保持现有 osql 脚本的向后兼容性,有些命令会被视为不带冒号。这由 [:] 指示。

  • sqlcmd 命令只有出现在一行的开头时,才能够被识别。

  • 所有 sqlcmd 命令都不区分大小写。

  • 每个命令都必须位于单独的行中。命令后面不能跟随 Transact-SQL 语句或其他命令。

  • 命令将被立即执行。它们与 Transact-SQL 语句不同,不会放在执行缓冲区中。

  • 编辑命令

  • [:] ED
    启动文本编辑器。该编辑器可以用来编辑当前的 Transact-SQL 批处理或上次执行的批处理。若要编辑上次执行的批处理,必须在上一批处理执行完之后立即键入 ED 命令。

    文本编辑器由 SQLCMDEDITOR 环境变量定义。默认编辑器为“Edit”。若要更改编辑器,请设置 SQLCMDEDITOR 环境变量。例如,若要将编辑器设置为 Microsoft 记事本,请在命令提示符处键入:

    SET SQLCMDEDITOR=notepad

  • [:] RESET
    清除语句缓存。

  • :List
    输出语句缓存的内容。

  • 变量

  • :Setvar <var> [ "value" ]
    定义 sqlcmd 脚本变量。脚本变量具有如下格式:$(VARNAME)。

    变量名称不区分大小写。

    可以通过下列方式设置脚本变量:

    • 隐式使用命令行选项。例如,-l 选项设置 SQLCMDLOGINTIMEOUT sqlcmd 变量。

    • 显式使用 :Setvar 命令。

    • 在运行 sqlcmd 之前定义一个环境变量。

    注意注意

    -X 选项可防止将环境变量传递给 sqlcmd

    如果使用 :Setvar 定义的变量和某个环境变量同名,则使用 :Setvar 定义的变量优先。

    变量名中不能包含空格字符。

    变量名不能与变量表达式(如 $(var))具有相同的形式。

    如果脚本变量的字符串值中含有空格,请用引号将该值引起来。如果未指定脚本变量的值,则将删除该脚本变量。

  • :Listvar
    显示当前设置的脚本变量列表。

    注意注意

    只显示由 sqlcmd 设置的脚本变量和使用 :Setvar 命令设置的脚本变量。

  • 输出命令

  • :Error<filename>|STDERR|STDOUT
    将所有错误输出重定向到 file name 指定的文件、stderrstdoutError 命令可以在一个脚本中多次出现。默认情况下,错误输出将发送到 stderr

    • file name
      创建并打开一个要接收输出的文件。若该文件已经存在,则将其截断为零字节。若该文件不可用(由于权限或其他原因),将不会切换输出,也不会将输出发送到上次指定的目标或默认目标。

    • STDERR
      将错误输出切换至 stderr 流。如果已经重定向,流的重定向目标将会收到错误输出。

    • STDOUT
      将错误输出切换至 stdout 流。如果已经重定向,流的重定向目标将会收到错误输出。

  • :Out <filename>| STDERR| STDOUT
    创建所有查询结果并将它们重定向到 file name 指定的文件、stderrstdout。默认情况下,输出将发送到 stdout。若该文件已经存在,则将其截断为零字节。Out 命令可以在一个脚本中多次出现。

  • :Perftrace <filename>| STDERR| STDOUT
    创建所有性能跟踪信息并将它们重定向到 file name 指定的文件、stderrstdout。默认情况下,性能跟踪输出将发送到 stdout。若该文件已经存在,则将其截断为零字节。Perftrace 命令可以在一个脚本中多次出现。

  • 执行控制命令

  • :On Error[ exit | ignore]
    设置在脚本或批处理执行过程中发生错误时要执行的操作。

    使用 exit 选项时,sqlcmd 退出,并显示相应的错误值。

    使用 ignore 选项时,sqlcmd 会忽略错误,并继续执行批处理或脚本。默认情况下,会输出错误消息。

  • [:] QUIT
    导致 sqlcmd 退出。

  • [:] EXIT[ (statement) ]
    允许您将 SELECT 语句的结果用作 sqlcmd 的返回值。第一个结果行的第一列转换为 4 字节的整数(长整型)。MS-DOS 将低字节传递给父进程或操作系统错误级别。Windows 200x 传递整个 4 字节整数。语法为:

    :EXIT(query)

    例如:

    :EXIT(SELECT @@ROWCOUNT)

    您还可以在批处理文件中包含 EXIT 参数。例如,在命令提示符处键入:

    sqlcmd -Q "EXIT(SELECT COUNT(*) FROM '%1')"

    sqlcmd 实用工具将圆括号 () 中的所有内容发送给服务器。如果系统存储过程选择了一个集合并返回一个值,则仅返回选择的内容。如果圆括号中没有任何内容,则 EXIT () 语句会执行批处理中此语句前的所有内容,然后退出,且不返回任何值。

    当指定了错误查询时,sqlcmd 将退出,且不返回任何值。

    下面是 EXIT 格式的列表:

    • :EXIT

    不执行批处理就立即退出,无返回值。

    • :EXIT( )

    执行批处理后退出,不返回值。

    • :EXIT(query)

    执行包括查询的批处理,返回查询的结果后退出。

    如果在 sqlcmd 脚本中使用 RAISERROR,并且出现状态 127,则 sqlcmd 将退出,并将消息 ID 返回给客户端。例如:

    RAISERROR(50001, 10, 127)

    该错误会导致 sqlcmd 脚本终止并将消息 ID 50001 返回给客户端。

    SQL Server 保留了介于 -1 到 -99 之间的返回值;sqlcmd 定义了以下附加返回值:

    返回值

    说明

    -100

    选择返回值前遇到错误。

    -101

    选择返回值时找不到行。

    -102

    选择返回值时发生转换错误。

  • GO [count]
    GO 在批处理和执行任何缓存 Transact-SQL 语句结尾时会发出信号。在为 count 指定一个值时,缓存的语句会被作为单个批处理执行 count 次。

  • 其他命令

  • :r <filename>
    将来自通过 **<filename>**所指定文件的其他 Transact-SQL 语句和 sqlcmd 命令分析到语句缓存中。

    如果文件包含的 Transact-SQL 语句后面没有跟随 GO,则必须在 :r 的后一行中输入 GO

    注意注意

    系统会相对于 sqlcmd 在其中运行的启动目录读取 <filename>

    当遇到批处理终止符之后,将读取并执行该文件。可以发出多个 :r 命令。该文件可以包含任何 sqlcmd 命令。包括批处理终止符 GO

    注意注意

    每遇到一个 :r 命令,交互模式下显示的行计数都会加一。:r 命令会出现在 list 命令的输出中。

  • :Serverlist
    列出在本地配置的服务器和在网络上广播的服务器的名称。

  • :Connectserver_name[**\**instance_name] [-l timeout] [-U user_name [-P password]]
    连接到 SQL Server 的一个实例。同时关闭当前的连接。

    超时选项:

    0

    永远等待

    n>0

    等待 n 秒钟

    SQLCMDSERVER 脚本变量将反映当前的活动连接。

    如果未指定 timeout,则其默认值将为 SQLCMDLOGINTIMEOUT 变量的值。

    仅当指定了 user_name(作为选项或环境变量)时,才会提示用户输入密码。如果已设置 SQLCMDUSER 或 SQLCMDPASSWORD 环境变量,则不会出现此提示。如果既未提供选项,又未提供环境变量,则使用 Windows 身份验证模式登录。例如,若要使用集成安全性连接到 SQL Servermyserver 的一个实例(如 instance1),则会使用以下内容:

    :connect myserver\instance1

    若要使用脚本变量连接到 myserver 的默认实例,您会使用以下内容:

    :setvar myusername test

    :setvar myservername myserver

    :connect $(myservername) $(myusername)

  • [:] !!< command>
    执行操作系统命令。若要执行操作系统命令,请用两个感叹号 (!!) 开始一行,后面输入操作系统命令。例如:

    :!! Dir

    注意注意

    该命令在运行 sqlcmd 的计算机上执行。

  • :XML [ON | OFF]
    有关详细信息,请参阅本主题后面的“XML 输出格式”

  • :Help
    列出 sqlcmd 命令以及每个命令的简短说明。

sqlcmd 文件名

可以使用 -i 选项或 :r 命令指定 sqlcmd 输入文件。可以使用 -o 选项或 :Error:Out:Perftrace 命令指定输出文件。以下是使用这些文件的一些原则:

  • :Error:Out:Perftrace 应使用不同的 <filename>。如果使用了相同的 <filename>,这些命令的输入可能会混杂在一起。

  • 如果从本地计算机的 sqlcmd 调用远程服务器上的输入文件,并且该文件包含驱动器文件路径(如 :out c:\OutputFile.txt),将在本地计算机而不是远程服务上创建输出文件。

  • 有效的文件路径包括:C:\<filename>、\\<服务器>\<共享$>\<filename> 和 "C:\Some Folder\<file name>"。如果路径中包含空格,请使用引号。

  • 每个新的 sqlcmd 会话都将覆盖现有的同名文件。

信息性消息

sqlcmd 将输出由服务器发送的所有信息性消息。在以下示例中,执行 Transact-SQL 语句后会输出信息性消息。

在命令提示符下键入以下内容:

sqlcmd

At the sqlcmd prompt type:

USE AdventureWorks;

GO

按下 Enter 时,会输出以下信息性消息:“已将数据库上下文改为 'AdventureWorks'。”

Transact-SQL 查询的输出格式

sqlcmd 首先输出列标题,其中包含在选择列表中指定的列名。列名使用 SQLCMDCOLSEP 字符分隔。默认情况下,将使用空格。如果列名短于列宽,则使用空格填充输出,直到下一列。

此行将跟随一行分隔行,分隔行是一系列的破折号字符。以下输出显示了一个示例。

启动 sqlcmd。在 sqlcmd 命令提示符下键入以下内容:

USE AdventureWorks;

SELECT TOP (2) ContactID, FirstName, LastName

FROM Person.Contact;

GO

按下 Enter 时,会返回以下结果集。

ContactID FirstName LastName

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

1 Syed Abbas

2 Catherine Abel

(2 row(s) affected)

虽然 ContactID 列只有 4 个字符宽,但已将其扩展以适应更长的列名。默认情况下,输出会在 80 个字符处终止。可通过使用 -w 选项或设定 SQLCMDCOLWIDTH 脚本变量来进行更改。

XML 输出格式

从 FOR XML 子句得到的 XML 输出是在连续流中的未格式化的输出。

若要得到 XML 输出,请使用以下命令::XML ON。

注意注意

sqlcmd 将采用常见的格式返回错误消息。请注意,XML 文本流中的错误消息还将采用 XML 格式输出。如果使用 :XML ON,则 sqlcmd 不显示信息性消息。

若要关闭 XML 模式,请使用以下命令::XML OFF。

发出 XML OFF 命令之前不应显示 GO 命令,因为 XML OFF 命令会将 sqlcmd 切换回面向行的输出。

XML(流形式)数据和行集数据不能混合。如果在执行输出 XML 流的 Transact-SQL 语句之前未发出 XML ON 命令,则输出将为乱码。如果已发出 XML ON 指令,则无法执行输出常规行集的 Transact-SQL 语句。

注意注意

:XML 命令不支持 SET STATISTICS XML 语句。

sqlcmd 最佳方法

使用以下方法来帮助实现最高的安全性和效率。

  • 使用集成安全性。

  • 在自动化环境中使用 -X

  • 使用适当的 NTFS 文件系统权限保护输入文件和输出文件。

  • 若要提高性能,请在一个 sqlcmd 会话中执行尽可能多的操作,而不是在一系列会话中来执行这些操作。

  • 将批处理或查询执行的超时值设置为大于您所预期的值。