適用於：SQL ServerAzure SQL 資料庫Azure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System （PDW）Microsoft Fabric 中的 SQL 資料庫
sqlcmd 公用程式可讓您輸入 Transact-SQL 語句、系統程式和腳本檔案。
備註
若要找出系統上已安裝哪些 sqlcmd 變體和版本，請參閱 檢查已安裝的 sqlcmd 公用程式版本。 如需如何取得 sqlcmd 的資訊，請參閱 下載並安裝 sqlcmd 公用程式。
除了 sqlcmd 內的 Transact-SQL 陳述式之外，您也可以使用下列命令：
GO [
: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 [ 「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。 根據預設，輸出會傳送到 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:\
每個新的 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 公用程式
檢查已安裝的 sqlcmd 公用程式版本
啟動 sqlcmd 公用程式
使用 sqlcmd 從腳本檔案執行 T-SQL
使用 sqlcmd