共用方式為

sqlcmd 公用程式

適用於：SQL ServerAzure SQL 資料庫Azure SQL 受控執行個體Azure Synapse Analytics分析平台系統 (PDW)Microsoft Fabric 中的 SQL 資料庫

sqlcmd 公用程式可讓您透過下列各種模式，輸入 Transact-SQL 陳述式、系統程序和指令檔：

  • 在命令提示字元中。
  • 在 [查詢編輯器] 中的 SQLCMD 模式中。
  • 在 Windows 指令碼檔案中。
  • 在 SQL Server Agent 作業的作業系統 (cmd.exe) 作業步驟中。

注意

雖然 Microsoft Entra ID 是 Azure Active Directory（Azure AD）的新名稱，但為了防止破壞現有的環境，Azure AD 仍會保留在某些硬式編碼元素中，例如 UI 字段、連線提供者、錯誤碼和 Cmdlet。 在本文中，這兩個名稱是可互換的。

找出您安裝的版本

sqlcmd 有兩個版本：

  • go-mssqldb 型 sqlcmd，有時樣式為 go-sqlcmd。 此版本是獨立工具，您可以獨立於 SQL Server 下載。

  • ODBC 型 sqlcmd，可與 SQL Server 或 Microsoft 命令列公用程式一起使用，並且是 Linux 上的 mssql-tools 套件的一部分。

若要判斷已安裝的版本，請在命令行上執行下列語句：

sqlcmd "-?"

sqlcmd "-?"

sqlcmd -?

如果您使用的是新版 sqlcmd (Go)，輸出會類似下列範例：

Version: 1.8.2

檢查版本

您可以使用 sqlcmd --version 判斷已安裝的版本。 您應已安裝至少 1.0.0 版。

重要

通過套件管理器安裝 sqlcmd （Go）將會在您的環境路徑中，用 sqlcmd （Go） 取代 sqlcmd （ODBC）。 您必須關閉並重新開啟任何目前的命令行會話，此變更才會生效。 sqlcmd （ODBC） 未移除，而且仍可藉由指定可執行檔的完整路徑來使用。 您也可以更新 PATH 變數，以指出哪些優先順序較高。 若要在 Windows 11 中這樣做，請開啟 [系統設定]，然後移至 [關於] > [進階系統設定]。 在 [系統屬性] 開啟時，選取 [環境變數] 按鈕。 在下半部的 [系統變數] 下，選取 [路徑]，然後選取 [編輯]。 如果 sqlcmd (Go) 的儲存位置 (預設為 C:\Program Files\sqlcmd) 列在 C:\Program Files\Microsoft SQL Server\<version>\Tools\Binn 之前，則使用 sqlcmd (Go)。 您可以反轉順序，讓 sqlcmd (ODBC) 再次成為預設值。

下載並安裝 sqlcmd

可以在 Microsoft Windows、macOS 和 Linux 上跨平台安裝 sqlcmd (Go)。 未必所有套件管理員皆可使用比 1.6 新的版本。 他們的可用日期目前尚未確定。

winget (Windows 封裝管理員 CLI)

  1. 如果您還沒有 Windows 封裝管理員用戶端，請加以安裝。

  2. 執行下列命令來安裝 sqlcmd (Go)。

    winget install sqlcmd

Chocolatey

  1. 安裝 Chocolatey (若尚未安裝)。

  2. 執行下列命令來安裝 sqlcmd (Go)。

    choco install sqlcmd

直接下載

  1. 從 GitHub 程式碼存放庫下載 -windows-amd64.zip 或 -windows-arm.zip 資產，這些是 最新版本 sqlcmd (Go) 的對應項。

  2. 從下載的 ZIP 檔案夾擷取 sqlcmd.exe 檔案。

預先安裝

Azure Cloud Shell

根據預設，您可以從 Azure Cloud Shell 試用已預先安裝的 sqlcmd 公用程式：

Azure Data Studio

若要在 Azure Data Studio 中執行 SQLCMD 陳述式，請從編輯器工具列中選取 [啟用 SQLCMD]。

SQL Server Management Studio （SSMS）

若要在 SQL Server Management Studio (SSMS) 中執行 SQLCMD 陳述式，請從上方導覽 [查詢] 功能表的下拉式清單中選取 [SQLCMD 模式]。

SSMS 會使用 Microsoft .NET Framework SqlClient，在 [查詢編輯器] 中執行正規和 SQLCMD 模式。 從命令列執行 sqlcmd 時，sqlcmd 會使用 ODBC 驅動程式。 因為可能會套用不同的預設選項，所以當您在 SQLCMD 模式中的 SSMS 和 sqlcmd 公用程式中執行相同的查詢時，您可能會看到不同的行為。

TDS 8.0 支援

SQL Server 2025 （17.x） Preview 引進了 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 語法和使用方式的詳細資訊，請參閱 ODBC sqlcmd 語法。

sqlcmd 中的重大變更 (ODBC)

在 sqlcmd (Go) 公用程式中，已改變數個參數和行為。 如需回溯相容性的遺漏旗標的最新清單，請造訪 GitHub 討論的排定實作回溯相容性旗標的優先順序。

  • 在較早版本的 sqlcmd (Go) 中，-P 參數已暫時移除，且只能透過下列機制提供用於 SQL Server 驗證的密碼：

    • SQLCMDPASSWORD 環境變數
    • :CONNECT 命令
    • 出現提示時，使用者可以鍵入密碼以完成連線

  • -r 需要 0 或 1 引數

  • -R 開關已移除。

  • -I 開關已移除。 若要停用引號識別項行為，請在指令碼中新增 SET QUOTED IDENTIFIER OFF。

  • -N會採用可以是、 true或 false 之一的disable字串值，以指定加密選擇。 (default 與省略參數相同)

    • 如果未提供 -N 和 -C，sqlcmd 會與伺服器交涉驗證，而不會驗證伺服器憑證。
    • 如果提供了 -N 但未提供 -C，sqlcmd 需要驗證伺服器憑證。 加密的 false 值仍然可能會導致登入封包的加密。
    • 如果同時提供 -N 和 -C，sqlcmd 將會使用其值進行加密交涉。
    • 如需用戶端/伺服器加密交涉的詳細資訊，請參閱 MS-TDS PRELOGIN。

    重要

    在 SQL Server 2025 (17.x) 預覽版中，-N 可以是 o（針對 optional）、m（針對 mandatory，預設值），或 s（針對 strict）。 如果您未包含 -N， -Nm 則 （for mandatory） 是預設值。 這是 SQL Server 2022 （16.x） 和舊版的重大變更。

  • -u 產生的 Unicode 輸出檔案會將 UTF-16 小端序位元組順序標記 (BOM) 撰寫在其中。

  • 為了維持與 相容性而保留的某些 OSQL 行為可能已變更，例如某些數據類型的數據行標頭對齊方式。

  • 所有命令必須在一行內，即使是EXIT。 互動式模式不會檢查命令的左括號或引號，且不會提示連續行。 此行為與 ODBC 版本不同，可讓 EXIT(query) 執行的查詢跨越多行。

來自 sqlcmd (Go) 公用程式的連線僅限於 TCP 連線。 go-mssqldb 驅動程式目前不支援具名管道。

提升

  • :Connect具有選擇性-G參數，可選取 Azure SQL Database 的其中一個驗證方法 - SqlAuthentication、、ActiveDirectoryDefault、ActiveDirectoryIntegratedActiveDirectoryServicePrincipal、ActiveDirectoryManagedIdentity、 ActiveDirectoryPassword。 如需詳細資訊，請參閱 在 sqlcmd 中使用 Microsoft Entra ID 進行驗證。 如果未提供 -G，則會使用整合式安全性或 SQL Server 驗證，視 -U 使用者名稱參數是否存在而定。

  • --driver-logging-level命令行參數可讓您查看驅動程序的go-mssqldb追蹤。 使用 64 來查看所有追蹤記錄。

  • sqlcmd （Go） 可以使用垂直格式列印結果。 使用-F vertical命令行開關來設定它。 SQLCMDFORMAT 指令碼變數也會進行控制。

    注意

    這與 -F（ODBC）的切換不同，此選項與-N一起使用以在憑證中指定主機名。

命令列選項

下表列出 sqlcmd 中可用的命令行選項，以及它們支援的作系統。

命令行選項 支援於 Windows 上 Linux 和macOS上支援
登入相關選項
-一個 是的 否
-C 是的 是的
-d db_name 是的 是的
-D 是的 是的
-l login_timeout 是的 是的
-E 是的 是的
-g 是的 是的
-G 是的 是的
-H workstation_name 是的 是的
-j 是的 是的
-K 應用意圖 是的 是的
-M multisubnet_failover 是的 是的
-N 是的 是的
-P 密碼 是的 是的
-S [protocol：]server[\instance_name][，port] 是的 是的
-U 登入_帳號 是的 是的
-z new_password 是的 是的
-Z new_password 是的 是的
輸入/輸出選項
-f codepage | i:codepage[，o:codepage] | o:codepage[，i:codepage] 是的 是的
-i input_file[，input_file2...] 是的 是的
-o 輸出_檔案 是的 是的
-r[0 | 1] 是的 是的
-R 是的 是的
-u 是的 是的
查詢執行選項
-e 是的 是的
-我 是的 是的
-q “cmdline query” 是的 是的
-Q “cmdline query” 是的 是的
-t query_timeout 是的 是的
-v var = value [ var = value... ] 是的 否
-x 是的 是的
格式選項
-h 標頭 是的 是的
-k [1 | 2] 是的 是的
-s col_separator 是的 是的
-w screen_width 是的 是的
-W 是的 是的
-y 變數長度類型顯示寬度 是的 是的
-Y 固定長度類型顯示寬度 是的 是的
錯誤報告選項
-b 是的 是的
-m error_level 是的 是的
-V error_severity_level 是的 是的
其他選項
-a 封包大小 是的 是的
-c batch_terminator 是的 是的
-L[c] 是的 否
-p[1] 是的 是的
-X[1] 是的 是的
-? 是的 是的

-一個

適用於：僅限 Windows。 不支援Linux和macOS。

使用專用管理員連接 (DAC) 來登入 SQL Server。 這種連接可用以進行伺服器的疑難排解。 此連接只適用於支援 DAC 的伺服器電腦。 如果無法使用 DAC，sqlcmd 會產生一則錯誤訊息，並結束作業。 如需 DAC 的詳細資訊，請參閱 資料庫管理員的診斷連線。 -A 選項不支援 -G 選項。 當使用 -A 連線到 Azure SQL 資料庫時，您必須為邏輯 SQL Server 系統管理員。 DAC 不適用於 Microsoft Entra 系統管理員。

注意

如需如何在 macOS 或 Linux 上建立專用系統管理員連線 （DAC） 的資訊，請參閱 程式設計指導方針。

-C

用戶端使用此選項將其設定為以隱含方式信任伺服器憑證而不進行驗證。 這個選項相當於 ADO.NET 選項 TRUSTSERVERCERTIFICATE = true。

對於 sqlcmd (Go) 公用程式，下列條件也適用：

  • 如果未提供 -N 和 -C，sqlcmd 會與伺服器交涉驗證，而不會驗證伺服器憑證。
  • 如果提供了 -N 但未提供 -C，sqlcmd 需要驗證伺服器憑證。 加密的 false 值仍然可能會導致登入封包的加密。
  • 如果同時提供 -N 和 -C，sqlcmd 將會使用其值進行加密交涉。

-d db_name

當您啟動 USE <db_name> 時發出 陳述式。 此選項會設定 sqlcmd 指令碼變數 SQLCMDDBNAME。 這項參數會指定初始資料庫。 預設值為您登入帳號的預設資料庫屬性。 如果資料庫不存在，系統會產生一則錯誤訊息，且會結束 sqlcmd。

-D

將提供給 -S 的伺服器名稱解譯為 DSN，而不是主機名稱。 如需詳細資訊，請參閱 sqlcmd 和 bcp 中的 DSN 支援。

注意

只有 Linux 和 macOS 用戶端可使用 -D 選項。 在 Windows 用戶端上，它是指已移除且忽略的過時選項。

-l login_timeout

指定在您嘗試連接到伺服器時， sqlcmd 登入 ODBC 驅動程式逾時之前的秒數。 此選項會設定 sqlcmd 指令碼變數 SQLCMDLOGINTIMEOUT。 sqlcmd 的預設登入逾時值是 8 秒。 使用 -G 選項連線到 Azure SQL Database 或 Azure Synapse Analytics 並使用 Microsoft Entra ID 進行驗證時，建議使用至少 30 秒的逾時值。 此登入逾時必須是介於 0 和 65534 之間的數字。 如果所提供的值不是數值或不在該範圍內，sqlcmd 就會產生錯誤訊息。 0 值指定逾時為無限。

-E

使用信任連線登入 SQL Server，而不用使用者名稱和密碼。 根據預設，如果沒有指定 -E，sqlcmd 會使用信任連接選項。

-E 選項會忽略可能出現的使用者名稱與密碼環境變數設定，例如 SQLCMDPASSWORD。 如果 -E 選項與 -U 選項或 -P 選項一起使用，則會產生錯誤訊息。

注意

如需從 Linux 或 macOS 用戶端建立使用整合式驗證之受信任連線的詳細資訊，請參閱 使用整合式驗證。

-g

將 [資料行加密設定] 設定為 Enabled。 如需詳細資訊，請參閱 Always Encrypted。 僅支援儲存在 Windows 憑證存放區中的主要金鑰。 -g 選項至少需要 sqlcmd13.1 版。 若要判斷您的版本，請執行 sqlcmd -?。

-G

當連線到 Azure SQL Database 或 Azure Synapse Analytics 時，用戶端會使用此選項，以指定使用者已使用 Microsoft Entra 驗證進行驗證。 此選項會設定 sqlcmd 指令碼變數 SQLCMDUSEAAD = true。 -G 選項至少需要 sqlcmd13.1 版。 若要判斷您的版本，請執行 sqlcmd -?。 如需詳細資訊，請參閱 Microsoft Azure SQL 的 Entra 驗證。 -A 選項不支援 -G 選項。

-G 選項僅適用於 Azure SQL Database 與 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。 工作站名稱列在 hostname 目錄檢視的 sys.sysprocesses 資料行中，而且可以使用預存程序 sp_who 傳回名稱。 如果未指定這個選項，預設值為目前的電腦名稱。 此名稱可用來識別不同的 sqlcmd 工作階段。

-j

將原始錯誤訊息列印至畫面。

-K 應用程式意圖

宣告連接到伺服器時的應用程式工作負載類型。 目前唯一支援的值是 ReadOnly。 如果未指定 -K，sqlcmd 即不支援對可用性群組中的次要複本進行連線。 如需詳細資訊，請參閱將唯讀工作負載卸載至 Always On 可用性群組的次要複本。

注意

-K SUSE Linux Enterprise Server （SLES） 不支援 。 不過，您可以在傳遞至 ApplicationIntent=ReadOnly 的 DSN 檔案中指定 關鍵詞。 如需詳細資訊，請參閱本文稍後 的 sqlcmd 和 bcp 中的 DSN 支援 。

如需詳細資訊，請參閱 Linux 和 macOS 上的高可用性和災害復原。

-M multisubnet_failover

在連線至 SQL Server 的可用性群組接聽程式或 SQL Server 容錯移轉叢集執行個體時，務必指定 -M。 -M 可提供對 (目前) 作用中伺服器更快速的偵測和連線。 如果未指定 -M，則會關閉 -M。

如需詳細資訊，請參閱：

注意

-M SUSE Linux Enterprise Server （SLES） 不支援 。 不過，您可以在傳遞至 MultiSubnetFailover=Yes 的 DSN 檔案中指定 關鍵詞。 如需詳細資訊，請參閱本文稍後 的 sqlcmd 和 bcp 中的 DSN 支援 。

如需詳細資訊，請參閱 Linux 和 macOS 上的高可用性和災害復原。

-N

用戶端會用此選項要求加密的連線。

針對 sqlcmd （Go） 公用程式，-N接受可以是 、 truefalse或 disable 的字串值來指定加密選擇。 (default 與省略參數相同)：

注意

在 Linux 和 macOS 上，已在 [s|m|o] 18.0 中新增 。 -N 可以是 o（針對 optional）、m（針對 mandatory，這是預設值），或 s（針對 strict）。 在 SQL Server 2025 （17.x） 預覽中，如果您未包含 -N， -Nm 則 （for mandatory） 是預設值。 這是 SQL Server 2022 （16.x） 和舊版的重大變更，其中 -No 是預設值。

  • 如果未提供 -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

    注意

    這與用於以垂直格式列印結果的 -F（Go）的開關不同。

-P 密碼

使用者指定的密碼。 密碼會區分大小寫。 如果使用-U選項，而不使用-P選項且未設定SQLCMDPASSWORD環境變數，sqlcmd會提示使用者輸入密碼。 我們不建議使用 Null (空白) 密碼，但您可以針對參數值 ("") 使用一組連續雙引號來指定 Null 密碼。

重要

使用 -P 應視為不安全。 請避免在命令列上提供密碼。 或者，使用 SQLCMDPASSWORD 環境變數，或省略 -P 選項以互動方式輸入密碼。

我們建議您使用強式密碼。

密碼提示的顯示方式，會以將密碼提示輸出到主控台的方式顯示，如： Password:

使用者輸入為隱藏狀態。 這表示畫面上不會顯示任何內容，而且游標也不會移動。

SQLCMDPASSWORD 環境變數可讓您設定目前工作階段的預設密碼。 因此，您不需要將密碼寫在批次檔中。 下列範例會先在命令提示字元處設定 SQLCMDPASSWORD 變數，再存取 sqlcmd 公用程式。

在命令提示字元中，輸入下列命令。 以有效的密碼取代 <password>。

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

SET SQLCMDPASSWORD=<password>
sqlcmd

如果使用者名稱和密碼的組合不正確，會產生錯誤訊息。

注意

OSQLPASSWORD環境變數會保留以供回溯相容性使用。 SQLCMDPASSWORD 環境變數優先於 OSQLPASSWORD 環境變數。 這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。 舊腳本會繼續運作。

如果 -P 選項與 -E 選項搭配使用，會產生錯誤訊息。

如果 -P 選項後面有多個引數，就會產生錯誤訊息並結束程式。

包含特殊字元的密碼可能會產生錯誤訊息。 您應在使用 -P 時逸出特殊字元，或改用 SQLCMDPASSWORD 環境變數。

在 Linux 和 macOS 上，當與 -G 選項搭配且不使用 -U 時，-P 指定包含存取令牌的檔案（v17.8+）。 令牌檔案應為UTF-16LE（無 BOM） 格式。

您可以透過各種方法取得存取令牌。 您必須確保存取權杖逐位元組相符，因為它被傳送 as-is。 以下是取得存取令牌的範例命令。 此命令會使用 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 的預設執行個體。 指定 server_name[\instance_name]，即可連線到該伺服器電腦的 SQL Server 具名執行個體。 如果未指定伺服器電腦，sqlcmd 會連線至本機電腦上 SQL Server 的預設執行個體。 當您從網路的遠端電腦執行 sqlcmd 時，需要這個選項。

protocol 可以是 tcp (TCP/IP)、lpc (共用記憶體) 或 np (具名管道)。

如果您啟動 sqlcmd 時，並未指定 server_name[\instance_name]，SQL Server 會檢查並使用 SQLCMDSERVER 環境變數。

注意

OSQLSERVER環境變數會保留以供回溯相容性使用。 SQLCMDSERVER 環境變數優先於 OSQLSERVER 環境變數。 這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。 舊腳本會繼續運作。

Linux 和 macOS 上的 ODBC 驅動程式需要 -S。 唯一有效的通訊協定值為 tcp。

-U login_id

登入名稱或包含在資料庫內的使用者名稱。 針對限定資料庫使用者，您必須提供資料庫名稱選項 (-d)。

注意

OSQLUSER環境變數會保留以供回溯相容性使用。 SQLCMDUSER 環境變數優先於 OSQLUSER 環境變數。 這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。 舊腳本會繼續運作。

如果沒有指定 -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 編碼頁 |i:編碼頁[，o:編碼頁] |o:編碼頁[，i:編碼頁]

指定輸入和輸出字碼頁。 代碼頁面編號是指定已安裝 Windows 代碼頁的數值。

代碼頁轉換規則：

  • 如果未指定字碼頁，則 sqlcmd 會在輸入檔和輸出檔中使用目前的字碼頁，除非輸入檔是 Unicode 檔，否則就不需要轉換。

  • sqlcmd 會自動識別位元組由大到小 (Big-Endian) 和位元組由小到大 (Little-Endian) 的 Unicode 輸入檔。 如果指定了 -u 選項，則輸出一律為小端序 Unicode。

  • 如果未指定輸出檔案，則輸出字碼頁會是主控台字碼頁。 此方法可讓輸出正確地顯示在主控台上。

  • 假設多個輸入檔都是相同的字碼頁。 Unicode 與非 Unicode 的輸入檔可以混合使用。

在命令提示字元下輸入 chcp，以驗證 cmd.exe 的字碼頁。

注意

在 Linux 上，代碼頁編號是一個數值，指定已安裝的 Linux 代碼頁（自 17.5.1.1 起可用）。

-i input_file[，input_file2...]

識別包含 Transact-SQL 陳述式或預存程序的批次之檔案。 可能會指定多個檔案，以便依序讀取和處理。 檔案名稱之間不能有空格。 sqlcmd 會先查看指定的檔案是否全部存在。 如果有一個或多個檔案不存在，sqlcmd 會結束作業。 -i 和 -Q/-q 選項互斥。

注意

如果您使用 [-i] 選項，後面接著一或多個其他參數，則必須使用 參數與值之間的空格。 這是 sqlcmd （Go） 中的已知問題。

路徑範例：

-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。

注意

對於 sqlcmd (Go) 公用程式，-r 需要 0 或 1 引數。

-R

適用於：僅限 ODBC sqlcmd。

讓 sqlcmd 根據用戶端的地區設定，將從 SQL Server 擷取的數值、貨幣、日期和時間資料行當地語系化。 根據預設，這些資料行會使用伺服器的地區設定來顯示。

注意

在 Linux 和 macOS 上， -R 目前只會使用 en_US （US English） 格式。

-u

指定無論 input_file 的格式為何， output_file 均以 Unicode 格式儲存。

注意

對於 sqlcmd (Go) 公用程式，產生的 Unicode 輸出檔案會將 UTF-16 小端序的位元組順序標記 (BOM) 寫入其中。

查詢執行選項

-e

將輸入指令碼寫入標準輸出裝置 (stdout) 中。

-我

適用於：僅限 ODBC sqlcmd。

將 SET QUOTED_IDENTIFIER 連線選項設定為 ON。 預設設定是 OFF。 如需詳細資訊，請參閱 SET QUOTED_IDENTIFIER。

注意

若要在 sqlcmd (Go) 公用程式中停用引號識別項行為，請在指令碼中新增 SET QUOTED IDENTIFIER OFF。

-q "命令行查詢"

在 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;"

重要

請勿在查詢中使用 GO 結束字元。

如果使用此選項時指定 -b，sqlcmd 會發生錯誤，並結束作業。 -b 在文章的 其他部分 有說明。

-Q "命令行查詢"

啟動 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;"

重要

請勿在查詢中使用 GO 結束字元。

如果使用此選項時指定 -b，sqlcmd 會發生錯誤，並結束作業。 -b 在文章的 其他部分 有說明。

-t query_timeout

指定命令 (或 Transact-SQL 陳述式) 逾時之前的秒數。此選項會設定 sqlcmd 指令碼變數 SQLCMDSTATTIMEOUT。 如果未指定 query_timeout 值，命令不會逾時。query_timeout 必須是介於 1 與 65534 之間的數字。 如果所提供的值不是數值或不在該範圍內，sqlcmd 就會產生錯誤訊息。

注意

實際逾時值可能會因指定的 query_timeout 值而有所不同，以數秒為單位。

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

適用於：僅限 Windows。 不支援Linux和macOS。

建立 sqlcmd 指令碼中所能使用的 sqlcmd 指令碼變數。

如果值包含空格，請用引號括住該值。 您可以指定多個 <var>="<value>" 值。 如果指定的任何值發生錯誤， 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"

-x

讓 sqlcmd 忽略指令碼變數。 當文稿包含許多 INSERT 語句時，此參數很有用，這些語句可能包含與一般變數具有相同格式的字串，例如 $(<variable_name>)。

格式選項

-h 標頭檔

指定要在欄位標題之間列印的列數。" 預設值是每一組查詢結果各列印一次標頭。 此選項會設定 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 變量長度類型顯示寬度

設定 sqlcmd 指令碼變數 SQLCMDMAXVARTYPEWIDTH。 預設值為 256。 這會限制大型可變長度資料類型的傳回字元數：

  • varchar（max）
  • nvarchar（max）
  • varbinary（max）
  • xml
  • 使用者定義資料類型 (UDT)
  • 文字
  • 內容
  • 圖像

UDT 可以是固定長度，這會隨著實作情況而不同。 如果固定長度 UDT 的長度小於 display_width，傳回的 UDT 值不會受到影響。 不過，如果長度超出 display_width，便會截斷輸出。

警告

請謹慎使用-y 0選項，因為它可能會根據傳回的數據大小，在伺服器和網路上造成顯著的效能問題。

-Y 固定長度類型顯示寬度

設定 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。 如果設定了-V選項，那麼除了 -b之外，當嚴重性層級低於使用 設定的值時，-V 不會報告錯誤。 命令提示字元批次檔案可以測試 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。 較大的封包大小可以提升執行具有許多 Transact-SQL 陳述式的指令碼在 GO 命令之間的效能。 您可以要求較大的封包。 但是，若要求遭到拒絕， sqlcmd 便會使用伺服器預設的封包大小。

-c batch_terminator

指定批次終止符。 根據預設，在一行中單獨鍵入 GO 這個字，便會終止命令，並將命令傳給 SQL Server。 當您重置批處理終止符時，即使在前面加了反斜線也不要使用 Transact-SQL 的保留關鍵字或對作業系統具有特殊意義的字元。

-L[c]

適用於：僅限 Windows。 不支援Linux和macOS。

列出設在本機上的伺服器電腦，以及在網路中進行廣播的伺服器電腦名稱。 這個參數不能結合其他參數來使用。 可以列出的最大伺服器電腦數目為 3000。 如果伺服器清單因為緩衝區的大小而遭到截斷，將會顯示一則警告訊息。

注意

由於網路上廣播的性質，sqlcmd 可能不會收到來自所有伺服器的及時回應。 因此，傳回的伺服器清單可能會因這個選項的每個調用而有所不同。

如果指定了選擇性參數 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 選項的語法摘要。

注意

在 macOS 上，改為執行 sqlcmd '-?' (帶引號)。

備註

您不需要按照語法區段中顯示的順序使用選項。

注意

如果您使用 [-i] 選項，後面接著一或多個其他參數，則必須使用 參數與值之間的空格。 這是 sqlcmd （Go） 中的已知問題。

傳回多項結果時， sqlcmd 會在批次的各結果集之間，列印一行空白行。 另外，當 <x> rows affected 的訊息不適合執行的陳述式時，便不會出現這則訊息。

若要以互動方式使用 sqlcmd，請在命令提示字元處鍵入 sqlcmd，並指定本文稍早所述的一或多個選項。 如需詳細資訊，請參閱 使用 sqlcmd。

注意

-l、-Q、-Z 或 -i 選項造成 sqlcmd 在執行之後結束。

命令環境 (例如， 或 cmd.exe) 中 bash 命令列的總長度 (包括所有引數和擴充的變數)，皆由基礎作業系統決定。

變數優先順序 (由低至高)

  1. 系統層級環境變數
  2. 使用者層級環境變數
  3. 在執行 SET X=Y 之前，請在命令提示字元處設置命令殼層 ()
  4. sqlcmd -v X=Y
  5. :Setvar X Y

注意

若要檢視環境變數，請在 [控制台] 中開啟 [系統]，然後選取 [進階] 索引標籤。

sqlcmd 指令碼變數

變數 相關的選項 R/W 預設
SQLCMDUSER -U R ""
SQLCMDPASSWORD -P -- ""
SQLCMDSERVER -S R 預設本地實例
SQLCMDWORKSTATION -H R 電腦名稱
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 ""
SQLCMDUSEAAD -G R/W ""

  • 使用 SQLCMDUSER 時，會設定 SQLCMDPASSWORD、SQLCMDSERVER 和 :Connect。

  • R 表示在程式初始化期間只能設定該值一次。

  • R/W 表示可以使用 :setvar 命令修改該值，且後續的命令會受新值影響。

sqlcmd 命令

除了 sqlcmd 內的 Transact-SQL 陳述式之外，您也可以使用下列命令：

  • GO [ <count> ]
  • :List
  • [:]RESET
  • :Error
  • [:]ED 1
  • :Out
  • [:]!!
  • :Perftrace
  • [:]QUIT
  • :Connect
  • [:]EXIT
  • :On Error
  • :r
  • :Help
  • :ServerList 1
  • :XML [ ON | OFF ] 1
  • :Setvar
  • :Listvar

1 Linux 或macOS不支援。

使用 sqlcmd 命令時請注意下列事項：

  • 除了 之外的所有 GO 命令開頭都必須加上冒號 (:)。

    重要

    為了維持與現有 osql 腳本的回溯相容性，有些命令會被辨識為不帶冒號，這由 :表示。

  • sqlcmd 命令必須在行首，才能夠辨識。

  • 所有 sqlcmd 命令都不區分大小寫。

  • 每個命令都必須在不同行中。 命令後面不能有 Transact-SQL 陳述式或另一個命令。

  • 命令會立即執行， 不會像 Transact-SQL 陳述式一樣放在執行緩衝區中。

編輯指令

[:]勃起功能障礙

啟動文字編輯器。 您可以使用這個編輯器編輯目前的 Transact-SQL 批次，或上次執行的批次。 若要編輯上次執行的批次，在上一個批次執行完成之後，必須立即鍵入 ED 命令。

文字編輯器由 SQLCMDEDITOR 環境變數來定義。 預設編輯器是 Edit。 若要變更編輯器，請設定 SQLCMDEDITOR 環境變數。 例如，若要將編輯器設為 Microsoft Notepad，請在命令提示字元之下，鍵入：

SET SQLCMDEDITOR=notepad

[:]重置

清除陳述式快取。

清單

列印出陳述式快取的內容。

變數

:Setvar <var> [ 「value」 ]

定義 sqlcmd 指令碼變數。 指令碼變數的格式如下： $(VARNAME)。

變數名稱不區分大小寫。

指令碼變數可以透過下列幾種方式設定：

  • 隱含地使用命令列選項。 例如，-l 選項會設定 SQLCMDLOGINTIMEOUTsqlcmd 變數。
  • 明確地使用 :Setvar 命令。
  • 在您執行 sqlcmd 之前，定義環境變數。

注意

-X 選項會讓您無法將環境變數傳給 sqlcmd。

如果使用 :Setvar 所定義的變數和環境變數同名，則以使用 :Setvar 所定義的變數優先。

變數名稱不能包含空格字元。

變數名稱的格式不能與變數運算式 (例如 $(var)) 相同。

如果指令碼變數的字串值包含空格，請用引號括住這個值。 如果未指定指令碼變數值，就會卸除指令碼變數。

：Listvar

顯示目前所設定之指令碼變數的清單。

注意

只會顯示 sqlcmd 所設定的腳本變數，以及使用 命令設定的 :Setvar 變數。

輸出命令

：錯誤 <檔名> |STDERR |STDOUT

將所有錯誤輸出重新導向至 filename 所指定的檔案、stderr 或 stdout。 在指令碼中，:Error 命令可以重複出現。 根據預設，錯誤輸出會傳送到 stderr。

  • 檔名

    建立和開啟用來接收輸出的檔案。 如果檔案已經存在，它會截斷成零位元組。 如果檔案因為權限或其他原因無法使用，輸出將不會切換，並會送往最後指定或預設的目的地。

  • STDERR

    將錯誤輸出切換到 stderr 資料流。 如果它已重新導向，資料流所重新導向的目標會接收這個錯誤輸出。

  • 標準輸出（STDOUT）

    將錯誤輸出切換到 stdout 資料流。 如果它已重新導向，資料流所重新導向的目標會接收這個錯誤輸出。

：Out <filename> | STDERR | STDOUT

建立並將所有查詢結果重新導向至 filename 所指定的檔案、stderr 或 stdout。 根據預設，輸出會傳送到 stdout。 如果檔案已經存在，它會截斷成零位元組。 在指令碼中，:Out 命令可以重複出現。

:Perftrace <檔名> |STDERR |STDOUT

建立並將所有效能追蹤資訊重新導向至 filename 所指定的檔案、stderr 或 stdout。 根據預設，效能追蹤輸出會傳送到 stdout。 如果檔案已經存在，它會截斷成零位元組。 在指令碼中，:Perftrace 命令可以重複出現。

執行控制命令

:當錯誤發生時 [ 結束 | 忽略 ]

設定執行指令碼或批次發生錯誤時所要執行的動作。

使用 exit 選項時，sqlcmd 會結束作業，並會出現適當的錯誤值。

使用 ignore 選項時，sqlcmd 會忽略錯誤，並繼續執行批次或指令碼。 根據預設，會列印錯誤訊息。

[:]退出

導致 sqlcmd 退出。

[:]退出 [ ( statement ) ]

可讓您使用 SELECT 陳述式的結果作為 sqlcmd 的傳回值。 如果為數值，最後一個結果資料列的第一個資料行會轉換成 4 位元組的整數 (long)。 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)

    執行包含查詢的批次，傳回查詢結果之後再結束。

如果在 RAISERROR 指令碼內使用 ，且產生 127 狀態，sqlcmd 會結束作業，且會將訊息 ID 傳回用戶端。 例如：

RAISERROR(50001, 10, 127)

這個錯誤會導致 sqlcmd 指令碼結束作業，並將訊息 ID 50001 傳回用戶端。

傳回值 -1 到 -99 會由 SQL Server 保留，而 sqlcmd 定義下列額外傳回值：

傳回值 描述
-100 選取傳回值之前發生錯誤。
-101 在選取傳回值時，找不到任何資料列。
-102 在選取傳回值時，發生轉換錯誤。

執行 [count]

GO 會指示批次結束及執行任何快取的 Transact-SQL 陳述式。 該批次會多次以個別批次的方式執行。 您無法在單一批次中宣告變數超過一次。

其他命令

:r <檔案名稱>

將 filename 所指定檔案中的其他 Transact-SQL 陳述式與 sqlcmd 命令，剖析至陳述式快取中。 檔案名稱 會在與執行 sqlcmd 的啟動目錄相對位置中讀取。

如果檔案包含的 Transact-SQL 陳述式後面沒有緊接著 GO，您必須在 GO 之後的一行輸入 :r。

在發現批次結束字元之後，這個檔案便會被讀取和執行。 您可以發出多個 :r 命令。 檔案可以包含任何 sqlcmd 命令，包括批次終止符 GO。

注意

在互動式模式中顯示的行數會每當遇到一個 :r 命令時增加一行。 :r 命令會出現在 list 命令的輸出中。

:伺服器列表

列出本機設定的伺服器，以及在網路上廣播的伺服器名稱。

：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 [ 開啟 | 關閉 ]

如需詳細資訊，請參閱本文中的 XML 輸出格式和 JSON 輸出格式。

:幫助

列出 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。

在發出 GO 命令之前，不應出現 :XML OFF 命令，因為 :XML OFF 命令會將 sqlcmd 切換回資料列導向的輸出。

XML (資料流) 資料和資料列集資料不能混合。 如果在執行輸出 XML 資料流的 Transact-SQL 語句之前未發出 :XML ON 命令，輸出將會變得混亂。 :XML ON命令發出後，您無法執行輸出一般數據列集的 Transact-SQL 語句。

注意

: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

sqlcmd 和 bcp 中的 DSN 支援

如果您指定 ，您可以在 bcp -S 或 sqlcmd :Connect 選項 （或 -D 命令） 中指定資料來源名稱 （DSN），而不是伺服器名稱。 -D 會讓 sqlcmd 或 bcp 連線到 DSN -S 中指定的伺服器選項。

系統 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） 和更新版本需要 MICROSOFT ODBC Driver 17 for SQL Server 驅動程式 （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，可以幫助在自動化環境中捕捉錯誤，特別是在生產發布前的品質關卡中。

相關內容