sqlcmd 实用工具中的命令

适用于：SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics 分析平台系统（PDW）Microsoft Fabric中的SQL数据库

sqlcmd 实用工具接受 Transact-SQL 语句、系统过程和脚本文件。

Note

若要了解系统上安装了哪个 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 命令都必须以冒号（:）开头。

Important

为了保持与现有 osql 脚本的向后兼容性，有些命令在没有冒号的情况下也能运行（由 [:] 指示）。
仅当命令出现在行的开头时，sqlcmd 才识别命令。
所有 sqlcmd 命令都不区分大小写。
每个命令都必须位于单独的行中。不能使用 Transact-SQL 语句或其他命令执行命令。
命令立即运行。它们与 Transact-SQL 语句不同，不会放在执行缓冲区中。

编辑命令

[:]ED

启动文本编辑器。使用此编辑器编辑当前 Transact-SQL 批处理或上次运行批处理。若要编辑最后一个运行批处理，请在最后一批完成执行后立即键入 ED 该命令。

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

SET SQLCMDEDITOR=notepad

[:]RESET

清除语句缓存。

:List

输出语句缓存的内容。

Variables

:Setvar <var> [ "value" ]

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

变量名称不区分大小写。

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

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

Note

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

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

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

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

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

:Listvar

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

Note

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

输出命令

：Error <filename> | STDERR | STDOUT

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

filename

创建并打开一个要接收输出的文件。现有文件截断为零字节。如果文件因权限或其他原因而不可用，则不会切换输出，最后一个指定或默认目标会收到错误输出。
STDERR

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

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

：Out <filename> |STDERR |STDOUT

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

:Perftrace <文件名> | STDERR | STDOUT

创建所有性能跟踪信息，并将其重定向到由文件名指定的文件、stderr或stdout。默认情况下，性能跟踪输出将转到 stdout。现有文件截断为零字节。 :Perftrace 命令可以在脚本中出现多次。

执行控制命令

：On Error [ exit | ignore ]

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

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

使用 ignore 此选项时， sqlcmd 将忽略错误并继续执行批处理或脚本。默认情况下， 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>

将文件名指定的文件的额外 Transact-SQL 语句和 sqlcmd 命令解析到语句缓存中。 sqlcmd 读取相对于启动目录的 文件名 。

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

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

Note

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

:ServerList

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

：Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

连接到 SQL Server 的一个实例。同时关闭当前的连接。

Important

该 :Connect 命令不充当隐式批处理分隔符。在发出 GO 命令之前，不会运行当前批处理中缓冲的任何 Transact-SQL 语句。如果在不使用干预:Connect语句的情况下使用多个GO命令，则所有缓冲语句都针对最后一个连接的服务器运行，而不是针对每个服务器单独运行。

加密选项（-N[s|m|o]）：

使用此选项请求加密连接。如果未包含 -N， -Nm 则为默认值（for mandatory）。此选项是 SQL Server 2022（16.x）及更早版本中的重大变更，-No （for optional）是默认值。

Value Description

-Ns 严格

-Nm（默认值）强制的

-No 可选
证书中的主机名（-F hostname_in_certificate）

在服务器证书中指定不同的预期公用名 (CN) 或使用者可选名称 (SAN)，以便在服务器证书验证期间使用。如果没有该选项，证书验证可确保证书中的 CN 或 SAN 与要连接的服务器名称相符。例如，使用 DNS 别名时，服务器名称与 CN 或 SAN 不匹配时，可以填充此参数。
超时选项：

Value Behavior

0 永远等待

n>0 等待 n 秒钟

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

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

Value	Description
`-Ns`	严格
`-Nm`（默认值）	强制的
`-No`	可选

Value	Behavior
`0`	永远等待
`n>0`	等待 n 秒钟

如果仅指定 user_name （作为选项或环境变量）， sqlcmd 会提示输入密码。如果设置了SQLCMDUSER或SQLCMDPASSWORD环境变量，则不会提示用户。如果未提供选项或未提供环境变量，便会使用 Windows 身份验证模式进行登录。例如，若要使用集成安全性连接到 SQL Server 的一个实例 instance1（如 myserver），则会使用以下命令：

:connect myserver\instance1

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

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

[:]!! command

运行操作系统命令。若要运行操作系统命令，请以两个感叹号（!!）开头，后跟操作系统命令。例如：

:!! dir

Note

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

：XML [ON | OFF]

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

:Help

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

sqlcmd 文件名

使用选项或-i命令指定 :r 输入文件。使用-o选项或:Error、:Out和:Perftrace命令指定输出文件。使用这些文件时，请使用以下准则：

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

信息消息

sqlcmd 输出服务器发送的任何信息性消息。在以下示例中， sqlcmd 运行 Transact-SQL 语句后，它将输出信息性消息。

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

USE AdventureWorks2025;
GO

按 Enter 时， sqlcmd 将输出以下信息：

Changed database context to 'AdventureWorks2025'.

Transact-SQL 查询的输出格式

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

sqlcmd 打印出由一系列短划线字符组成的分隔线。以下输出显示了一个示例。

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

USE AdventureWorks2025;

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

按 Enter 时， sqlcmd 将返回以下结果集。

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

尽管BusinessEntityID列的宽度只有四个字符，但它会扩展以适应更长的列名称。默认情况下， sqlcmd 以 80 个字符终止输出。可以通过使用-w选项或设置SQLCMDCOLWIDTH脚本变量来更改此宽度。

XML 输出格式

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

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

Note

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

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

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

XML（流式）数据和行集数据不能混合。 :XML ON命令如果没有在执行输出 XML 流的 Transact-SQL 语句之前发出，则输出会出现乱码。 :XML ON发出命令后，无法运行输出常规行集的 Transact-SQL 语句。

Note

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

JSON 输出格式

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

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

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

使用 Microsoft Entra 身份验证

使用 Microsoft Entra 身份验证的示例：

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

反馈

此页面是否有帮助？

Last updated on 2026-04-22

sqlcmd 实用工具中的命令

编辑命令

[:]ED

[:]RESET

:List

Variables

:Setvar <var> [ "value" ]

:Listvar

输出命令

：Error <filename> | STDERR | STDOUT

：Out <filename> |STDERR |STDOUT

:Perftrace <文件名> | STDERR | STDOUT

执行控制命令

：On Error [ exit | ignore ]

[:]QUIT

[:]EXIT [ ( statement ) ]

GO [count]

其他命令

：r <filename>

:ServerList

：Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

[:]!! command

：XML [ON | OFF]

:Help

sqlcmd 文件名

信息消息

Transact-SQL 查询的输出格式

XML 输出格式

JSON 输出格式

使用 Microsoft Entra 身份验证

相关内容

反馈

其他资源