sqlcmd 公用程式

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

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

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

sqlcmd 有兩個版本：

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

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

若要判斷您已安裝的版本，請在命令列中執行下列陳述式：

sqlcmd "-?"

sqlcmd "-?"

sqlcmd -?

Version: 1.3.1

Microsoft (R) SQL Server Command Line Tool
Version 16.0.4025.1 NT
Copyright (C) 2022 Microsoft Corporation. All rights reserved.

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

• 啟動 Cloud Shell

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

-G 選項僅適用於 Azure SQL Database 與 Azure Synapse Analytics。

Linux 或 macOS 目前不支援 Microsoft Entra 互動式驗證。 Microsoft Entra 整合式驗證需要 Microsoft ODBC Driver 17 for SQL Server 17.6.1 版或更高版本，以及正確設定的 Kerberos 環境。

如需有關 Microsoft Entra 驗證的詳細資訊，請參閱 sqlcmd 中的 Microsoft Entra 驗證。

這是工作站名稱。 此選項會設定 sqlcmd 指令碼變數 SQLCMDWORKSTATION。 工作站名稱列在 hostname 目錄檢視的 sys.sysprocesses 資料行中，而且可以使用預存程序 sp_who 傳回名稱。 如果未指定這個選項，預設值為目前的電腦名稱。 此名稱可用來識別不同的 sqlcmd 工作階段。

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

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

在連線至 SQL Server 的可用性群組接聽程式或 SQL Server 容錯移轉叢集執行個體時，務必指定 -M。 -M 可提供對 (目前) 作用中伺服器更快速的偵測和連線。 如果未指定 -M，則會關閉 -M。 如需有關 監聽程式、用戶端連線能力、應用程式容錯移轉、建立及設定可用性群組 (SQL Server)、容錯移轉叢集與 Always On 可用性群組 (SQL Server)，以及作用中的次要副本：可讀取的次要副本 (Always On 可用性群組) 的更多資訊。

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

對於 sqlcmd (Go) 公用程式，-N 現在會採用字串值，可以是 true、false 或 disable 之一，以指定加密選擇。 (default 與省略參數相同)：

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

使用者指定的密碼。 密碼會區分大小寫。 如果使用 -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 環境變數。

指定要連線的 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 環境變數。

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

如果沒有指定 -U 選項或 -P 選項，sqlcmd 會嘗試使用 Windows 驗證模式進行連線。 這項驗證以執行 sqlcmd 之使用者的 Windows 帳戶為基礎。

如果 -U 選項與 -E 選項搭配使用 (稍後於本文中描述)，即會產生錯誤訊息。 如果 -U 選項後面有多個引數，就會產生錯誤訊息並結束程式。

變更密碼。 以舊密碼取代 <oldpassword>，並以新密碼 <newpassword>。

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

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

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

變更密碼並結束。 以舊密碼取代 <oldpassword>，並以新密碼 <newpassword>。

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

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

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

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

字碼頁轉換規則：

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

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

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

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

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

識別包含 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>

識別用來接收 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>"

包含空格的檔案路徑必須用引號括住。

將錯誤訊息輸出重新導向至畫面 (stderr)。 如果您沒有指定參數，或指定 0，只會重新導向嚴重性層級 11 (含) 以上的錯誤訊息。 如果您指定 1，便會重新導向包括 PRINT 在內的所有錯誤訊息輸出。 如果您使用 -o，此選項沒有任何作用。 根據預設，訊息會傳送到 stdout。

適用於：僅限 ODBC sqlcmd。

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

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

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

適用於：僅限 ODBC sqlcmd。

將 SET QUOTED_IDENTIFIER 連線選項設定為 ON。 根據預設，它會設定為 OFF。 如需詳細資訊，請參閱 SET QUOTED_IDENTIFIER (Transact-SQL)。

當 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 在本文其他地方進行了描述。

啟動 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 在本文其他地方進行了描述。

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

建立 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"

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

指定要在欄位標題之間列印的列數。" 預設值是每一組查詢結果各列印一次標頭。 此選項會設定 sqlcmd 指令碼變數 SQLCMDHEADERS。 使用 -1 來指定不列印標頭。 任何無效的值都會讓 sqlcmd 產生錯誤訊息，並結束作業。

從輸出中移除所有控制字符，如制表符和換行符。 此參數會在資料傳回時，保留資料行的格式。

• -k 會移除控制字元。
• -k1 會將每個控制字元取代為空格。
• -k2 會將連續控制字元取代為單一空格。

指定資料行分隔字元。 預設值是空格。 此選項會設定 sqlcmd 指令碼變數 SQLCMDCOLSEP。 若要使用對作業系統有特殊意義的字元，如連字號 (&) 或分號 (;)，請用引號 (") 括住該字元。 欄位分隔符可以是任何 8 位元字元。

指定輸出的螢幕寬度。 此選項會設定 sqlcmd 指令碼變數 SQLCMDCOLWIDTH。 資料行寬度必須是大於 8 且小於 65536 的數字。 如果指定的資料行寬度不在該範圍內，sqlcmd 會產生錯誤訊息。 預設寬度是 80 個字元。 當一行輸出超出指定的欄寬時，該行會自動換行到下一行。

這個選項會從資料行中移除尾端的空格。 在準備要匯出到另一個應用程式的資料時，請同時使用這個選項和 -s 選項。 不能與 -y 或 -Y 選項搭配使用。

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

• varchar(max)
• nvarchar(max)
• varbinary(max)
• xml
• 使用者定義資料類型 (UDT)
• text
• ntext
• image

UDT 可以是固定長度，這會隨著實作情況而不同。 如果固定長度 UDT 的長度小於 display_width，傳回的 UDT 值不會受到影響。 不過，如果長度超出 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

指定在發生錯誤時，sqlcmd 會結束作業並傳回 DOS ERRORLEVEL 值。 當 SQL Server 錯誤訊息的嚴重性層級大於 10 時，傳回 ERRORLEVEL 變數的值是 1；否則，傳回的值是 0。 如果除了設定 -V 選項外，還設定了 -b 選項，則當嚴重性層級低於使用 -V 所設定的值時，sqlcmd 不會報告錯誤。 命令提示字元批次檔案可以測試 ERRORLEVEL 的值，而且能夠適當地處理錯誤。 sqlcmd 不會報告嚴重性層級 10 (資訊訊息) 的錯誤。

如果 sqlcmd 指令碼包含不正確的命令、語法錯誤，或遺漏指令碼變數，則傳回的 ERRORLEVEL 便是 1。

控制哪些錯誤訊息會傳送至stdout。 系統會傳送嚴重性層級大於或等於這個層級的訊息。 當這個值設定為 -1 時，系統就會傳送包括資訊訊息的所有訊息。 -m 與 -1 之間不允許有空格。 例如，-m-1 為有效，而 -m -1 為無效。

這個選項也會設定 sqlcmd 指令碼變數 SQLCMDERRORLEVEL。 這個變數具有預設值 0。

控制用來設定 ERRORLEVEL 變數的嚴重性層級。 嚴重性層級大於或等於這個值的錯誤訊息會設定 ERRORLEVEL。 小於 0 的值會回報成 0。 批次和 CMD 檔案可用來測試 ERRORLEVEL 變數的值。

要求不同大小的封包。 此選項會設定 sqlcmd 指令碼變數 SQLCMDPACKETSIZE。 packet_size 必須是介於 512 與 32767 之間的值。 預設值為 4096。 較大的封包大小可以提升執行具有許多 Transact-SQL 陳述式的指令碼在 GO 命令之間的效能。 您可以要求較大的封包。 但是，若要求遭到拒絕， sqlcmd 便會使用伺服器預設的封包大小。

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

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

如果指定了選擇性參數 c，顯示的輸出不會有 Servers: 標頭行，列出的每個伺服器行也都不會有開頭空白。 這種呈現方式稱為乾淨輸出。 乾淨的輸出可以增進指令碼語言的處理效能。

列印每個結果集的效能統計資料。 以下顯示的是效能統計資料的格式範例：

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。

停用從批次檔執行 sqlcmd 時，可能會危及系統安全性的命令。 仍會辨識停用的命令； sqlcmd 會發出一則警告訊息，並繼續作業。 如果指定了選擇性參數 1，sqlcmd 會產生一則錯誤訊息，並結束作業。 使用 -X 選項時，會停用下列命令：

• ED
• !! 命令

如果指定 -X 選項，您就無法將環境變數傳給 sqlcmd。 也無法執行利用 SQLCMDINI 指令碼變數所指定的啟動指令碼。 如需有關 sqlcmd 指令碼變數的詳細資訊，請參閱 sqlcmd - 搭配指令碼變數使用。

顯示 sqlcmd 的版本和 sqlcmd 選項的語法摘要。

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

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

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

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

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

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

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

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

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

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

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

  重要

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

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

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

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

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

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

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

SET SQLCMDEDITOR=notepad

清除陳述式快取。

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

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

變數名稱不區分大小寫。

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

• 隱含地使用命令列選項。 例如，-l 選項會設定 SQLCMDLOGINTIMEOUTsqlcmd 變數。

• 明確地使用 :Setvar 命令。

• 在您執行 sqlcmd 之前，定義環境變數。

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

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

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

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

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

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

• filename

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

• STDERR

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

• STDOUT

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

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

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

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

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

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

導致 sqlcmd 退出。

可讓您使用 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 定義下列額外傳回值：

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

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

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

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

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

連線至 SQL Server 的執行個體。 此外也會關閉目前的連接。

逾時選項：

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

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

列出 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'.

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 指令碼變數，變更此寬度。

FOR XML 子句所產生的 XML 輸出，會在連續資料流中以未格式化的形式輸出。

當您希望產生 XML 輸出時，請使用下列命令： :XML ON。

若要將 XML 模式設定為關閉，請使用下列命令：:XML OFF。

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

XML (資料流) 資料和資料列集資料不能混合。 如果在執行輸出 XML 資料流的 Transact-SQL 陳述式之前未發出 :XML ON 命令，則輸出的結果會變得混亂。 已發出 :XML ON 命令之後，您就不能執行輸出正規資料列集的 Transact-SQL 陳述式。

當您希望產生 JSON 輸出時，請使用下列命令： :XML ON。 否則，輸出會同時包含資料行名稱和 JSON 文字。 此輸出不是有效的 JSON。

若要將 XML 模式設定為關閉，請使用下列命令：:XML OFF。

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

使用 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

請採用下列作法以提高安全性與效率。

• 使用整合式安全性。

• 在自動化環境中使用 -X[1]。

• 使用適當的檔案系統權限保護輸入檔和輸出檔。

• 為提高效能，請盡可能在單一 sqlcmd 工作階段中執行所有工作，而不要使用一連串的工作階段。

• 設定批次或查詢執行的逾時值，高於預期執行批次或查詢所需的時間。

使用下列作法以協助將正確性最大化：

• 使用 -V 16 來記錄任何嚴重性16級別訊息。 16 級嚴重性訊息指出使用者可以更正的一般錯誤。

• 在處理序結束之後檢查結束代碼與 DOS ERRORLEVEL 變數。 sqlcmd 會正常返回 0，否則會按照 -V 設定 ERRORLEVEL。 換句話說，不應該預期 ERRORLEVEL 會與 SQL Server 回報的錯誤號碼相同。 錯誤號碼是 SQL Server 特有值，其會與系統函數 @@ERROR 相對應。 ERRORLEVEL 是 sqlcmd 特有值，是用來指出 sqlcmd 終止的原因，且其值可透過指定 -b 命令列引數來加以影響。

使用 -V 16 搭配檢查結束代碼與 DOS ERRORLEVEL，可以幫助在自動化環境中捕捉錯誤，特別是在生產發布前的品質關卡中。

• 深入了解 GitHub 上的新 go-sqlcmd 工具
• 快速入門：使用 Docker 執行 SQL Server Linux 容器映像
• sqlcmd - 啟動公用程式
• sqlcmd - 執行 Transact-SQL 指令碼檔案
• sqlcmd - 使用公用程式
• sqlcmd - 與指令碼變數搭配使用
• sqlcmd - 連線至資料庫引擎
• 使用查詢編輯器編輯 SQLCMD 指令碼
• 管理作業步驟
• 建立 CmdExec 作業步驟