sqlcmd 实用工具

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

可以通过各种模式，使用 sqlcmd 实用工具输入 Transact-SQL 语句、系统过程和脚本文件：

• 通过命令提示符。
• 在查询编辑器中的 SQLCMD 模式下。
• 在 Windows 脚本文件中。
• 在 SQL Server 代理作业的操作系统 (cmd.exe) 作业步骤中。

sqlcmd 变体

sqlcmd 有两种变体：

• sqlcmd（Go）：基于 go-mssqldb 的 sqlcmd，有时称作 go-sqlcmd。 此版本是可以独立于 SQL Server 下载的独立工具。 它在 Windows、macOS、Linux 和容器中运行。

• sqlcmd （ODBC）：与平台对齐的基于 ODBC 的 sqlcmd，可用于 SQL Server 或 Microsoft 命令行实用工具，也作为 Linux 上 mssql-tools 包的一部分。 它还在 Windows、macOS、Linux 和容器中运行。

若要了解系统上安装了哪个 sqlcmd 变体和版本，请参阅 “检查已安装的 sqlcmd 实用工具版本”。

有关如何获取 sqlcmd 的信息，请参阅 下载并安装 sqlcmd 实用工具。

TDS 8.0 支持

SQL Server 2025 （17.x） 预览版引入了对 sqlcmd 实用工具的 TDS 8.0 支持。

语法

Usage:
  sqlcmd [flags]
  sqlcmd [command]

Examples:
# Install/Create, Query, Uninstall SQL Server
  sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
  sqlcmd open ads
  sqlcmd query "SELECT @@version"
  sqlcmd delete
# View configuration information and connection strings
  sqlcmd config view
  sqlcmd config cs

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Modify sqlconfig files using subcommands like "sqlcmd config use-context mssql"
  create      Install/Create SQL Server, Azure SQL, and Tools
  delete      Uninstall/Delete the current context
  help        Help about any command
  open        Open tools (e.g ADS) for current context
  query       Run a query against the current context
  start       Start current context
  stop        Stop current context

Flags:
  -?, --?                  help for backwards compatibility flags (-S, -U, -E etc.)
  -h, --help               help for sqlcmd
      --sqlconfig string   configuration file (default "/Users/<currentUser>/.sqlcmd/sqlconfig")
      --verbosity int      log level, error=0, warn=1, info=2, debug=3, trace=4 (default 2)
      --version            print version of sqlcmd

Use "sqlcmd [command] --help" for more information about a command.

sqlcmd
   -a packet_size
   -A (dedicated administrator connection)
   -b (terminate batch job if there is an error)
   -c batch_terminator
   -C (trust the server certificate)
   -d db_name
   -D
   -e (echo input)
   -E (use trusted connection)
   -f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]
   -g (enable column encryption)
   -G (use Azure Active Directory for authentication)
   -h rows_per_header
   -H workstation_name
   -i input_file
   -I (enable quoted identifiers)
   -j (Print raw error messages)
   -k[1 | 2] (remove or replace control characters)
   -K application_intent
   -l login_timeout
   -L[c] (list servers, optional clean output)
   -m error_level
   -M multisubnet_failover
   -N (encrypt connection)
   -o output_file
   -p[1] (print statistics, optional colon format)
   -P password
   -q "cmdline query"
   -Q "cmdline query" (and exit)
   -r[0 | 1] (msgs to stderr)
   -R (use client regional settings)
   -s col_separator
   -S [protocol:]server[instance_name][,port]
   -t query_timeout
   -u (unicode output file)
   -U login_id
   -v var = "value"
   -V error_severity_level
   -w screen_width
   -W (remove trailing spaces)
   -x (disable variable substitution)
   -X[1] (disable commands, startup script, environment variables, optional exit)
   -y variable_length_type_display_width
   -Y fixed_length_type_display_width
   -z new_password
   -Z new_password (and exit)
   -? (usage)

命令行选项

下表列出了 sqlcmd 中提供的命令行选项及其支持的作系统。

登录相关选项

-A

适用于： 仅限 Windows。 不支持 Linux 和 macOS。

使用专用管理员连接 (DAC) 登录 SQL Server。 此类型连接用于排除服务器故障。 此连接只适用于支持 DAC 的服务器计算机。 如果 DAC 不可用，sqlcmd 会生成错误消息并退出。 有关 DAC 的详细信息，请参阅 数据库管理员的诊断连接。 不支持同时使用 -A 选项和 -G 选项。 使用 -A 连接到 Azure SQL 数据库时，你必须是逻辑 SQL 服务器的管理员。 DAC 不适用于 Microsoft Entra 管理员。

-C

该选项供客户端用于将其配置为隐式表示信任服务器证书且无需验证。 此选项等同于 ADO.NET 选项 TRUSTSERVERCERTIFICATE = true。

对于 sqlcmd (Go) 实用程序，以下条件也适用：

• 如果没有提供 -N 和 -C，sqlcmd 将与服务器协商身份验证，而不验证服务器证书。
• 如果提供了 -N 但没有提供 -C，则 sqlcmd 需要验证服务器证书。 如果加密值为 false，仍可能导致登录数据包加密。
• 如果同时提供了 -N 和 -C，sqlcmd 将使用其值进行加密协商。

-d db_name

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

-D

将提供给 -S 的服务器名称解释为 DSN 而不是主机名。 有关详细信息，请参阅 sqlcmd 和 bcp 中的 DSN 支持。

-l login_timeout

指定在你尝试连接到服务器时 sqlcmd 登录 ODBC 驱动程序的超时时间（以秒为单位）。 此选项设置 sqlcmd 脚本变量 SQLCMDLOGINTIMEOUT。 登录到 sqlcmd 的默认超时时间为 8 秒。 使用 -G 选项连接到 Azure SQL 数据库或 Azure Synapse Analytics 并使用 Microsoft Entra ID 进行身份验证时，建议超时值至少为 30 秒。 登录超时必须是介于 0 和 65534 之间的数字。 如果提供的值不是数值或不在此范围内，则 sqlcmd 将生成错误消息。 该值为 0 时，则允许无限制等待。

-E

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

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

-g

将列加密设置设为 Enabled。 有关详细信息，请参阅 Always Encrypted。 仅支持存储在 Windows 证书存储中的主密钥。 -g 选项至少需要 sqlcmd 版本 13.1。 若要确定你的版本，请执行 sqlcmd -?。

-G

连接到 Azure SQL 数据库或 Azure Synapse Analytics 时，客户端使用此选项指定用户使用 Microsoft Entra 身份验证进行身份验证。 此选项设置 sqlcmd 脚本变量 SQLCMDUSEAAD = true。 -G 选项至少需要 sqlcmd 版本 13.1。 若要确定你的版本，请执行 sqlcmd -?。 有关更多信息，请参阅 SQL Server 的 Microsoft Entra 身份验证。 不支持同时使用 -A 选项和 -G 选项。

-G 选项仅适用于 Azure SQL 数据库和 Azure Synapse Analytics。

Linux 或 macOS 目前不支持 Microsoft Entra 交互式身份验证。 Microsoft Entra 集成身份验证需要 下载 ODBC Driver for SQL Server 17.6.1 或更高版本以及 正确配置的 Kerberos 环境。

有关Microsoft Entra 身份验证的详细信息，请参阅 sqlcmd 中使用 Microsoft Entra ID 进行身份验证。

-H workstation_name

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

-j

将原始错误消息输出到屏幕上。

-K application_intent

连接到服务器时声明应用程序工作负荷类型。 目前唯一支持的值是 ReadOnly。 如果未指定 -K，sqlcmd 将不支持连接到可用性组中的次要副本。 有关详细信息，请参阅卸载对 Always On 可用性组的次要副本的只读工作负荷。

有关详细信息，请参阅 Linux 和 macOS 上的高可用性和灾难恢复。

-M multisubnet_failover

在连接到 SQL Server 可用性组或 SQL Server 故障转移群集实例的可用性组侦听程序时，应始终指定 -M。 -M 将为（当前）活动服务器提供更快的检测和连接。 如果未指定 -M，则 -M 处于关闭状态。

有关详细信息，请参见:

• 连接到 Always On 可用性组侦听器
• 有关创建和配置 Always On 可用性组的引用
• 故障转移群集和 Always On 可用性组 (SQL Server)
• 将只读工作负荷卸载到 Always On 可用性组的次要副本

有关详细信息，请参阅 Linux 和 macOS 上的高可用性和灾难恢复。

-N

此选项供客户端用于请求加密连接。

对于 sqlcmd （Go） 实用工具，-N 接受一个字符串值，该值可以是 true、false 或 disable 之一，以指定加密选项。 （default 与省略该参数的行为相同）：

• 如果没有提供 -N 和 -C，sqlcmd 将与服务器协商身份验证，而不验证服务器证书。

• 如果提供了 -N 但没有提供 -C，则 sqlcmd 需要验证服务器证书。 如果加密值为 false，仍可能导致登录数据包加密。

• 如果同时提供了 -N 和 -C，sqlcmd 将使用其值进行加密协商。

• 在 sqlcmd （ODBC）中，用于 -F 在证书中指定主机名。 例如：

  sqlcmd -S server01 -Q "SELECT TOP 100 * FROM WideWorldImporters.Sales.Orders" -A -Ns -F server01.adventure-works.com
  

  注意

  这不同于 sqlcmd (Go) 的 -F 开关，该开关用于使用垂直格式打印结果。

-P 密码

用户指定的密码。 密码是区分大小写的。 如果使用了-U选项，而未使用-P选项，并且SQLCMDPASSWORD环境变量未设置，那么sqlcmd 会提示用户输入密码。 我们不建议使用 null（空）密码，但你可以通过对参数值 ("") 使用一对连续的双引号来指定 null 密码。

建议使用强密码。

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

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

使用 SQLCMDPASSWORD 环境变量可以为当前会话设置默认密码。 因此，不必将密码硬编码到批处理文件中。 以下示例首先在命令提示符处设置 SQLCMDPASSWORD 变量，然后访问 sqlcmd 实用工具。

在命令提示符处，键入以下命令。 将 <password> 替换为有效的密码。

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

如果用户名和密码组合不正确，将生成错误消息。

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

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

包含特殊字符的密码可以生成错误消息。 使用 -P 时应转义特殊字符，或者转而使用 SQLCMDPASSWORD 环境变量。

在 Linux 和 macOS 上，当使用-G选项且不使用-U时，-P指定一个包含访问令牌的文件（v17.8+）。 令牌文件的格式应为 UTF-16LE（无 BOM）。

可以通过各种方法获取访问令牌。 你必须确保访问令牌逐字节正确，因为它是按原样发送的。 下面是获取访问令牌的示例命令。 该命令使用 Azure CLI 和 Linux 命令，并以适当的格式保存到文件中。 如果系统或终端的默认编码不是 ASCII 或 UTF-8，则可能需要调整 iconv 选项。 一定要小心保护生成的文件，并在不再需要时将其删除。

az account get-access-token --resource https://database.windows.net --output tsv | cut -f 1 | tr -d '\n' | iconv -f ascii -t UTF-16LE > /tmp/tokenFile

-S [protocol:]server[\instance_name][,port]

指定要连接到的 SQL Server 实例。 它设置 sqlcmd 脚本变量 SQLCMDSERVER。

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

protocol 可以是 tcp (TCP/IP)、 lpc （共享内存）或 np （命名管道）。

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

Linux 和 macOS 上的 ODBC 驱动程序需要 -S。 唯一有效的协议值为 tcp.

-U login_id

登录名或包含的数据库用户名。 对于包含的数据库用户，必须提供数据库名称选项 (-d)。

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

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

-z new_password

更改密码。 将<oldpassword>替换为旧密码，将<newpassword>替换为新密码。

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

sqlcmd -U someuser -P <oldpassword> -z <newpassword>

-Z new_password

更改密码并退出。 将<oldpassword>替换为旧密码，将<newpassword>替换为新密码。

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

sqlcmd -U someuser -P <oldpassword> -Z <newpassword>

输入/输出选项

-f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]

指定输入和输出代码页。 代码页页码是指定已安装的 Windows 代码页的数值。

代码页转换规则：

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

• sqlcmd 自动识别 Big-endian Unicode 和 Little-endian Unicode 输入文件。 如果指定了 -u 选项，则输出始终为小字节序 Unicode。

• 如果未指定输出文件，输出代码页为控制台代码页。 借助此方法，可以在控制台上正确显示输出。

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

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

-i input_file[,input_file2...]

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

路径示例：

-i C:\<filename>
-i \\<Server>\<Share$>\<filename>
-i "C:\Some Folder\<file name>"

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

此选项可以多次使用：

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

-o output_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>"

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

-r[0 | 1]

将错误消息输出重定向到屏幕 (stderr)。 如果未指定参数或指定参数为 0，则仅重定向严重级别为 11 或更高的错误消息。 如果指定参数为 1，则将重定向所有消息输出（包括 PRINT）。 如果使用 -o，则此选项不起作用。 默认情况下，消息将发送到 stdout。

-R

适用于：仅限 ODBC sqlcmd。

让 sqlcmd 根据客户端的区域设置，本地化从 SQL Server 中检索到的数字、货币、日期和时间列。 默认情况下，这些列使用服务器的区域设置进行显示。

-u

指定无论 input_file 为何种格式，都以 Unicode 格式存储 output_file。

查询执行选项

-e

将输入脚本写入标准输出设备 (stdout)。

-我

适用于：仅限 ODBC sqlcmd。

将 SET QUOTED_IDENTIFIER 连接选项设置为 ON。 默认设置为 OFF。 有关详细信息，请参阅 SET QUOTED_IDENTIFIER。

-q "cmdline query"

在 sqlcmd 启动时执行查询，但在查询完成后不会退出 sqlcmd 。 可以执行多个分号分隔的查询。 将查询用引号引起来，如下例所示。

在命令提示符处，键入：

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

如果在指定此选项的同时还指定了 -b ， sqlcmd 在遇到错误时将退出。 -b 将在本文其他部分进行介绍。

-Q "cmdline query"

在 sqlcmd 启动时执行查询，随后立即退出 sqlcmd。 可以执行多个以分号分隔的查询。

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

在命令提示符处，键入：

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"
sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

如果在指定此选项的同时还指定了 -b ， sqlcmd 在遇到错误时将退出。 -b 将在本文其他部分进行介绍。

-t query_timeout

指定命令（或 Transact-SQL 语句）超时的时间。此选项设置 sqlcmd 脚本变量 SQLCMDSTATTIMEOUT。 如果未指定 query_timeout 值，则命令不会超时。query_timeout 必须是介于 1 和 65534 之间的数字。 如果提供的值不是数值或不在此范围内，则 sqlcmd 将生成错误消息。

-v var = value [ var = value... ]

适用于： 仅限 Windows。 不支持 Linux 和 macOS。

创建可在 sqlcmd 脚本中使用的 sqlcmd 脚本变量。

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

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

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

:setvar ColumnName object_id
:setvar TableName sys.objects

SELECT $(ColumnName) FROM $(TableName)

cat a.sql > c.sql
cat b.sql >> c.sql

sqlcmd -S<...> -P<..> -U<..> -I c.sql

-x

导致 sqlcmd 忽略脚本变量。 当脚本包含许多 INSERT 语句时，此参数非常有用，这些语句可能包含与常规变量具有相同格式的字符串，例如 $(<variable_name>)。

格式选项

-h headers

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

-k [1 | 2]

删除输出中的所有控制字符，例如制表符和换行符。 此参数在返回数据时保留列格式。

• -k 移除控制字符。
• -k1 将每个控制字符替换为空格。
• -k2 将连续的控制字符替换为单个空格。

-s col_separator

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

-w screen_width

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

-w

此选项删除列的尾随空格。 在准备要导出到另一应用程序的数据时，请将此选项和 -s 选项一起使用。 不能与 -y 或 -Y 选项一起使用。

-y variable_length_type_display_width

设置 sqlcmd 脚本变量 SQLCMDMAXVARTYPEWIDTH。 默认为 256。 它限制为下列大型可变长度数据类型返回的字符的数目：

• varchar（max）
• nvarchar（max）
• varbinary（max）
• xml
• 用户定义的数据类型 (UDT)
• 文本
• ntext
• 映像

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

-Y fixed_length_type_display_width

设置 sqlcmd 脚本变量 SQLCMDMAXFIXEDTYPEWIDTH。 默认值为 0（无限制）。 它限制为以下数据类型返回的字符数：

• char(n)，其中 1 <= n<= 8000
• nchar(n)，其中 1 <= n<= 4000
• varchar(n)，其中 1 <= n<= 8000
• nvarchar(n)，其中 1 <= n<= 4000
• varbinary(n)，其中 1 <= n<= 4000
• sql_variant

错误报告选项

-b

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

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

-m error_level

控制将哪些错误消息发送到 stdout。 将发送严重级别大于或等于此级别的消息。 如果此值设置为 -1，将发送所有消息（包括信息性消息）。 在 -m 和 -1 之间不允许有空格。 例如，-m-1 有效，而 -m -1 无效。

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

-V error_severity_level

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

杂项选项

-a packet_size

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

-c batch_terminator

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

-L[c]

适用于： 仅限 Windows。 不支持 Linux 和 macOS。

列出本地配置的服务器计算机和在网络上播发的服务器计算机的名称。 此参数不能与其他参数结合使用。 可以列出的服务器的最大数目是 3000。 如果服务器列表由于缓冲区大小而被截断，则会显示错误消息。

如果指定了可选参数 c，输出就不会包含 Servers: 标题行，且列出的每个服务器行都没有前导空格。 此演示文稿被称为清除输出。 清除输出可以提高脚本语言的处理性能。

-p[1]

输出每个结果集的性能统计信息。 下面的输出显示示例展示了性能统计信息的格式：

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]

从批处理文件执行 sqlcmd 时，将禁用可能危及系统安全的命令。 禁用的命令仍然可以被识别； sqlcmd 发出警告消息并继续。 如果指定了可选参数 1 ，则 sqlcmd 将生成错误消息，然后退出。 使用 -X 选项时，将禁用以下命令：

• ED
• !!命令

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

-?

显示 sqlcmd 的版本和 sqlcmd 选项的语法摘要。

注解

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

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

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

命令环境（例如 cmd.exe 或 bash）中的 sqlcmd 命令行的总长度（包括所有参数和扩展变量）取决于底层操作系统。

sqlcmd 和 bcp 中的 DSN 支持

如果指定，可以在 bcp -S 或sqlcmd :Connect选项（或-D命令）中指定数据源名称（DSN），而不是服务器名称。 -D 使 sqlcmd 或 bcp 通过 -S 选项连接到 DSN 中指定的服务器。

系统 DSN 存储在位于 ODBC odbc.ini 目录中的 SysConfigDir 文件（在标准安装中为 /etc/odbc.ini）。 用户 DSN 存储在用户主目录 (~/.odbc.ini) 的 .odbc.ini 中。

在 Windows 系统上，系统和用户 DSN 存储在注册表中，并通过该 odbcad32.exe注册表进行管理。 bcp 和 sqlcmd 不支持文件 DSN。

有关驱动程序支持的条目列表，请参阅 DSN 和连接字符串关键字和属性。

在 DSN 中，只需 DRIVER 输入，但若要连接到远程服务器， sqlcmd 或 bcp 需要元素中的 SERVER 值。 SERVER如果 DSN 中元素为空或不存在，则 sqlcmd 和 bcp 尝试连接到本地系统上的默认实例。

在 Windows 系统上使用 bcp 时，SQL Server 2017 （14.x） 和早期版本需要 SQL Native Client 11 驱动程序（sqlncli11.dll），而 SQL Server 2019 （15.x） 及更高版本需要 SQL Server 驱动程序的 Microsoft ODBC Driver 17（msodbcsql17.dll）。

如果在 DSN 和 sqlcmd 或 bcp 命令行中指定了相同的选项，则命令行选项将替代 DSN 中使用的值。 例如，如果 DSN 具有 DATABASE 条目且 sqlcmd 命令行包含 -d，则使用传递给 -d 的值。 如果在 Trusted_Connection=yes DSN 中指定，则使用 Kerberos 身份验证;用户名（-U）和密码（-P如果提供）将被忽略。

可以通过定义以下别名来修改调用isql以使用 sqlcmd 的现有脚本： alias isql="sqlcmd -D"

sqlcmd 最佳做法

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

• 使用集成安全性。

• 在自动化环境中使用 -X[1]。

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

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

• 为批处理或查询的执行设置超时值，应高于您预计批处理或查询所需的时间。

使用以下方法来帮助实现最高的正确性：

• 使用 -V 16 记录任何严重性级别为 16 的消息。 严重性级别为 16 的消息指示可由用户纠正的常规错误。

• 在进程退出后检查退出代码和 DOS ERRORLEVEL 变量。 sqlcmd 会正常返回 0，否则它会将 ERRORLEVEL 设置为 -V 配置的值。 换句话说，ERRORLEVEL 的值不应与 SQL Server 报告的错误号相同。 错误号是对应于系统函数 @@ERROR的特定于 SQL Server 的值。 ERRORLEVEL 是 sqlcmd 特定的值，用于指示 sqlcmd 终止的原因，并且它的值会通过指定 -b 命令行参数来影响。

将使用 -V 16 与检查退出代码和 DOS ERRORLEVEL 相结合，有助于捕获自动化环境（尤其是生产发布之前的质量检验关）中的错误。

相关内容

• 检查已安装的 sqlcmd 实用工具版本
• 下载并安装 sqlcmd 实用工具
• sqlcmd 实用工具中的命令
• 将 sqlcmd 与脚本变量配合使用
• 快速入门：使用 Docker 运行 SQL Server Linux 容器映像
• 启动 sqlcmd 实用程序
• 使用 sqlcmd 从脚本文件执行 T-SQL
• 使用 sqlcmd
• 使用 sqlcmd 连接到 SQL Server
• 使用查询编辑器编辑 SQLCMD 脚本
• 创建 CmdExec 作业步骤