sqlcmd 实用工具中的命令

2025-07-14

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics Platform System (PDW)Microsoft Fabric SQL 数据库

sqlcmd 实用工具允许你输入 Transact-SQL 语句、系统过程和脚本文件。

注释

若要了解系统上安装了哪个 sqlcmd 变体和版本，请参阅 “检查已安装的 sqlcmd 实用工具版本”。有关如何获取 sqlcmd 的信息，请参阅下载并安装 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

¹ Linux 或 macOS 不支持。

使用 sqlcmd 命令时，请注意以下事项：

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

重要

为了保持现有 osql 脚本的后向兼容性，有些命令会被视为不带冒号，通过 : 指示。
sqlcmd 命令只有出现在一行的开头时，才能够被识别。
所有 sqlcmd 命令都不区分大小写。
每个命令都必须位于单独的行中。命令后面不能跟随 Transact-SQL 语句或其他命令。
命令将被立即执行。它们与 Transact-SQL 语句不同，不会放在执行缓冲区中。

编辑命令

[:]ED

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

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

SET SQLCMDEDITOR=notepad

[:]RESET

清除语句缓存。

：列表

输出语句缓存的内容。

变量

:Setvar <var> [ "value" ]

定义 sqlcmd 脚本变量。脚本变量具有如下格式： $(VARNAME)。

变量名称不区分大小写。

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

隐式使用命令行选项。例如，-l 选项设置 SQLCMDLOGINTIMEOUTsqlcmd 变量。
显式使用 :Setvar 命令。
在运行 sqlcmd 之前定义环境变量。

注释

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

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

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

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

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

：Listvar

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

注释

只有 由 sqlcmd 设置的脚本变量和由 :Setvar 命令设置的变量将被显示。

输出命令

:Error <filename> | STDERR | STDOUT

将所有错误输出重定向到 filename 指定的文件、stderr 或 stdout。 :Error 命令可以在脚本中出现多次。默认情况下，错误输出发送到 stderr。

文件名

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

将错误输出切换到 stderr 流。如果输出已重定向，则流重定向的目标会收到错误输出。
STDOUT

将错误输出切换到 stdout 流。如果输出已重定向，则流重定向的目标会收到错误输出。

:Out <filename> | STDERR | STDOUT

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

:Perftrace <filename> | STDERR | STDOUT

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

执行控制命令

:On Error [ exit | ignore ]

设置在脚本或批处理执行过程中发生错误时要执行的操作。

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

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

[:]QUIT

导致 sqlcmd 退出。

[:]EXIT [ ( statement ) ]

允许使用 SELECT 语句的结果作为 sqlcmd 的返回值。如果为数值，最后一个结果行的第一列将转换为 4 字节的整数（长整型）。 MS-DOS、Linux 和 macOS 将低字节传递给父进程或操作系统错误级别。 Windows 2000 及更高版本传递整个 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 定义了以下附加返回值：

返回值	DESCRIPTION
`-100`	选择返回值之前遇到错误。
`-101`	选择返回值时找不到行。
`-102`	选择返回值时发生转换错误。

GO [count]

GO 在批处理结束和任何缓存 Transact-SQL 语句执行时发出信号。该批处理将作为单独的批处理执行多次。不能在单个批处理中多次声明某个变量。

杂项命令

：r <filename>

将来自 filename 指定的文件中的其他 Transact-SQL 语句和 sqlcmd 命令分析到语句缓存中。系统会相对于 sqlcmd 在其中运行的启动目录读取 filename。

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

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

注释

在交互模式下，显示的行计数会因每个遇到的 :r 命令而增加一。 :r 命令显示在列表命令的输出中。

:ServerList

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

:Connect server_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 Server 的一个实例 instance1（如 myserver），则会使用以下命令：

:connect myserver\instance1

若要使用脚本变量连接到 myserver 的默认实例，则会使用以下设置：

:setvar myusername test
:setvar myservername myserver
:connect $(myservername) $(myusername)

[:]!! 命令

执行操作系统命令。若要执行操作系统命令，请用两个感叹号 ( !! ) 开始一行，后面输入操作系统命令。例如：

:!! dir

注释

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

：XML [ON | OFF]

有关详细信息，请参阅本文中的 XML 输出格式和 JSON 输出格式。

:Help

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

sqlcmd 文件名

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

:Error、:Out 和 :Perftrace 应使用不同的 文件名 值。如果使用相同的 文件名，则命令中的输入可能会混合。
如果从本地计算机的 sqlcmd 调用远程服务器上的输入文件，并且该文件包含驱动器文件路径（如 :Out c:\OutputFile.txt），将在本地计算机而不是远程服务上创建输出文件。
有效文件路径包括：C:\<filename>、\\<Server>\<Share$>\<filename> 和 "C:\Some Folder\<file name>"。如果路径中包含空格，请使用引号。
每个新的 sqlcmd 会话都将覆盖现有的同名文件。

信息性消息

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

启动 sqlcmd。在 sqlcmd 命令提示符下键入以下查询：

USE AdventureWorks2022;
GO

按 ENTER 后，会输出以下信息性消息：

Changed database context to 'AdventureWorks2022'.

Transact-SQL 查询的输出格式

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

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

启动 sqlcmd。在 sqlcmd 命令提示符下键入以下查询：

USE AdventureWorks2022;

SELECT TOP (2) BusinessEntityID,
               FirstName,
               LastName
FROM Person.Person;
GO

当你按下 ENTER 后，系统便会返回以下结果集。

BusinessEntityID FirstName    LastName
---------------- ------------ ----------
285              Syed         Abbas
293              Catherine    Abel
(2 row(s) affected)

尽管BusinessEntityID列的宽度只有四个字符，但它会扩展以适应更长的列名称。默认情况下，输出会在 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 ON如果在执行输出 XML 流的 Transact-SQL 语句之前未发出该命令，则输出会乱写。 :XML ON命令发出后，无法执行 Transact-SQL 语句来输出常规行集。

注释

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

JSON 输出格式

若要得到 JSON 输出，请使用以下命令： :XML ON。否则，输出包括的列名和 JSON 文本。此输出不是有效的 JSON。