sqlcmd 公用程式

發行項
03/03/2023

適用于：SQL Server Azure SQL資料庫 Azure SQL 受控執行個體Azure Synapse Analytics Analytics Platform System (PDW)

注意

如需 SQL Server 2014 和更低版本，請參閱Sqlcmd 公用程式。

如需在 Linux 上使用 sqlcmd 的詳細資訊，請參閱在 Linux上安裝 sqlcmd 與 bcp。

sqlcmd 公用程式可讓您透過下列各種可用的模式，在命令列提示字元中輸入 Transact-SQL 陳述式、系統程序和指令碼檔案：

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

此公用程式會使用 ODBC 來執行 Transact-SQL 批次。

下載並安裝 sqlcmd

Windows

下載 Microsoft 命令列公用程式 15 SQL Server (x64) (2.6 MB)
下載 Microsoft 命令列公用程式 15 for SQL Server (x86) (2.3 MB)

命令列工具是正式運作 (GA) ，不過它們正隨著安裝程式套件發行，SQL Server 2019 (15.x) 。

版本資訊

版本號碼：15.0.2
組建編號：15.0.2000.5
發行日期：2020 年 9 月 11 日

新版本的 SQLCMD 支援 Azure AD 驗證，包括 SQL Database、Azure Synapse Analytics 和 Always Encrypted 功能的 Multi-Factor Authentication (MFA) 支援。新的 BCP 支援 Azure AD 驗證，包括 SQL Database 與 Azure Synapse Analytics 的 Multi-Factor Authentication (MFA) 支援。

系統需求windows 11、Windows 10、Windows 7、Windows 8、Windows 8.1、Windows Server 2008 - 2022。

此元件需要內建的 Windows Installer 5和Microsoft ODBC Driver 17 for SQL Server。

Linux/macOS

如需在 Linux 和 macOS 上安裝 sqlcmd 的指示，請參閱在 Linux 上安裝 sqlcmd 和 bcp 。

檢查版本

若要檢查 SQLCMD 版本執行 sqlcmd -? 命令，並確認正在使用 15.0.2000.5 版或更新版本。

注意

您需要 13.1 版或更新版本才能支援 Always Encrypted (-g) 與 Azure Active Directory 驗證 (-G)。您的電腦上可能已安裝數個版本的 sqlcmd.exe。請務必使用正確的版本。若要判斷版本，請執行 sqlcmd -? 。

預先安裝

Azure Cloud Shell

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

Azure Data Studio

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

SQL Server Management Studio (SSMS)

若要在 SSMS中執行 sqlcmd 語句，請從頂端導覽的 [查詢功能表] 下拉式清單中選取 [SQLCMD 模式]。

重要

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

Syntax

目前， sqlcmd 不需要在命令列選項與值之間保留一個空格。但是在未來的版本中，可能會需要在命令列選項與值之間空一個空格。

如需 sqlcmd 語法和使用的詳細資訊，請參閱：

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)

命令列選項

登入相關選項

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

-C
這個參數由用戶端所設定，以隱含方式信任伺服器憑證而且不進行驗證。這個選項相當於 ADO.NET 選項 TRUSTSERVERCERTIFICATE = true。

-ddb_name
啟動 USEsqlcmd時發出db_name語句。這個選項會設定 sqlcmd 指令碼變數 SQLCMDDBNAME。這項參數會指定初始資料庫。預設值為您登入的預設資料庫屬性。如果資料庫不存在，就會產生錯誤訊息並結束 sqlcmd 。

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

注意

只有 Linux 和 MacOS 用戶端可使用 -D 選項。在 Windows 用戶端上，已移除且忽略以前稱為現已過時的選項。

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

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

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

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

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

重要

此選項 -G 僅適用于 Azure SQL Database 和 Azure Synapse Analytics。 Linux 或 macOS 目前不支援 Azure AD 互動式驗證。 Azure AD 整合式驗證需要Microsoft ODBC Driver 17 for SQL Server 17.6.1 版或更新版本，以及正確設定的 Kerberos 環境。

Azure Active Directory 使用者名稱和密碼：

當您想要使用 Azure Active Directory 使用者名稱和密碼時，您可以提供 -G 選項，並同時提供 -U 和 -P 選項來使用使用者名稱和密碼。
```
Sqlcmd -S testsrv.database.windows.net -d Target_DB_or_DW -U bob@contoso.com -P MyAADPassword -G
```
-G 參數會在後端產生下列連接字串︰
```
  SERVER = Target_DB_or_DW.testsrv.database.windows.net;UID= bob@contoso.com;PWD=MyAADPassword;AUTHENTICATION = ActiveDirectoryPassword
```
Azure Active Directory 整合式

若是 Azure Active Directory 整合式驗證，請提供 -G 選項，但不提供使用者名稱或密碼。 AAD 整合式驗證需要Microsoft ODBC Driver 17，才能SQL Server 17.6.1 版或更新版本，以及正確設定的 Kerberos 環境。

Sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G

這會在後端產生下列連接字串：

SERVER = Target_DB_or_DW.testsrv.database.windows.net Authentication = ActiveDirectoryIntegrated; Trusted_Connection=NO

注意

-E 選項 (Trusted_Connection) 不能搭配 -G 選項一起使用。

Azure Active Directory 互動式

Azure SQL Database 與 Azure Synapse Analytics 的 Azure AD 互動式驗證，其允許使用支援 Multi-Factor Authentication 的互動式方法。如需詳細資訊，請參閱 Active Directory 互動式驗證。

Azure AD 互動需要 sqlcmd15.0.1000.34 版或更新版本，以及 ODBC 17.2 版或更新版本。

若要啟用互動式驗證，請在不使用密碼的情況下，僅以使用者名稱 (-U) 提供 -G 選項。

下列範例會使用 Azure AD 互動式模式匯出資料，指出使用者代表 Azure AD 帳戶的使用者名稱。此為與在上一區段中所使用的相同範例：Azure Active Directory 使用者名稱與密碼。

互動模式需要手動輸入密碼，若為已啟用多重要素驗證的帳戶，請完成您已設定的 MFA 驗證方法。
```
sqlcmd -S testsrv.database.windows.net -d Target_DB_or_DW -G -U alice@aadtest.onmicrosoft.com
```
先前的命令會在後端產生下列連接字串︰
```
SERVER = Target_DB_or_DW.testsrv.database.windows.net;UID=alice@aadtest.onmicrosoft.com; AUTHENTICATION = ActiveDirectoryInteractive
```
如果 Azure AD 使用者是使用 Windows 帳戶的網域同盟使用者，命令列中所需的使用者名稱包含其網域帳戶 (， joe@contoso.com 請參閱下列) ：
```
sqlcmd -S testsrv.database.windows.net -d Target_DB_or_DW -G -U joe@contoso.com
```
如果來賓使用者存在於特定 Azure AD 中，且屬於 SQL Database 中具有執行 sqlcmd 命令的資料庫權限群組，則會使用其來賓使用者別名 (例如， keith0@adventureworks.com )。

重要

使用 -G 與 -U 選項搭配 SQLCMD 時，存在一個已知問題：若在 -G 選項之前放置 -U 選項可能會導致驗證失敗。請一律先以 -G 選項開始，再放置 -U 選項。

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

sqlcmd 工作階段。

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

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

-Mmultisubnet_failover
在連線到SQL Server可用性群組的可用性群組接聽程式或SQL Server容錯移轉叢集實例時，請一律指定-M。 -M 可提供對 (目前) 作用中伺服器更快速的偵測與連接。如果未指定 -M ， 則 -M 會關閉。如需接聽程式、用戶端連線、應用程式容錯移轉、可用性群組 (SQL Server) 的建立和設定、容錯移轉叢集和Always On可用性群組 (SQL Server) 和作用中次要複本的詳細資訊：可讀取的次要複本 (Always On可用性群組) 。

-N
用戶端會用這個參數要求加密的連接。

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

重要

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

建議您使用強式密碼。

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

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

SQLCMDPASSWORD 環境變數可讓您設定目前工作階段的預設密碼。因此，密碼不需要硬式編碼成批次檔。

下列範例會先在命令提示字元處設定 SQLCMDPASSWORD 變數，再存取 sqlcmd 公用程式。在命令提示字元中，輸入：

SET SQLCMDPASSWORD= p@a$$w0rd
請在下列命令提示字元之下，輸入：

sqlcmd

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

注意

保留 OSQLPASSWORD 環境變數的目的是為了與舊版相容。 SQLCMDPASSWORD 環境變數會優先於 OSQLPASSWORD 環境變數。 OSQLPASSWORD 現在已不再共用，sqlcmd 與 osql 公用程式可以在彼此之間使用，而不會受到干擾。舊版指令碼仍可繼續使用。

如果同時使用 -P 選項和 -E 選項，就會產生錯誤訊息。

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

-S [protocol：]server[ \instance_name][，port]
指定要連接的SQL Server實例。它會設定 sqlcmd 指令碼變數 SQLCMDSERVER。

指定server_name連線到該伺服器電腦上的預設實例SQL Server。指定[\instance_name] server_name ，以連線到該伺服器電腦上的具名實例SQL Server。如果未指定伺服器電腦，sqlcmd會連線到本機電腦上的預設實例SQL Server。當您從網路的遠端電腦執行 sqlcmd 時，需要這個選項。

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

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

注意

保留 OSQLSERVER 環境變數的目的是為了與舊版相容。 SQLCMDSERVER 環境變數優先於 OSQLSERVER 環境變數；這表示您可以先後使用 sqlcmd 和 osql ，它們不會互相干擾，舊的指令碼仍能運作。

-Ulogin_id
是登入名稱或自主資料庫使用者名稱。針對自主資料庫使用者，您必須提供資料庫名稱選項 (-d)。

注意

可利用 OSQLUSER 環境變數達到回溯相容性。 SQLCMDUSER 環境變數優先於 OSQLUSER 環境變數。這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。這也表示現有的 osql 指令碼仍然有效。

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

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

-znew_password
變更密碼：

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

-Znew_password

變更密碼並結束：

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

輸入/輸出選項
-fcodepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]

指定輸入和輸出字碼頁。字碼頁碼是一個數值，指定已安裝的 Windows 字碼頁。

字碼頁轉換規則：

如果未指定字碼頁，則 sqlcmd 會在輸入檔和輸出檔中使用目前的字碼頁，除非輸入檔是 Unicode 檔，否則就不需要轉換。
sqlcmd 會自動識別位元組由大到小 (Big-Endian) 和位元組由小到大 (Little-Endian) 的 Unicode 輸入檔。如果已指定 -u 選項，則輸出一律為位元組由小到大的 Unicode。
如果未指定輸出檔，則輸出字碼頁會是主控台字碼頁。此方法可讓輸出正確地顯示在主控台上。
假設多個輸入檔都是相同的字碼頁。 Unicode 與非 Unicode 的輸入檔可以混合使用。

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

-iinput_file[，input_file2...]
識別包含 SQL 陳述式或預存程序的批次之檔案。您可以指定多個檔案，它們會依照順序加以讀取和處理。請勿在檔案名之間使用任何空格。 sqlcmd 會先檢查指定的檔案是否全部存在。如果一或多個檔案不存在， sqlcmd 將會結束。 -i 和 -Q/-q 為互斥選項。

路徑範例：

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

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

此選項可以使用一次以上：-iinput_file-Iinput_file。

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

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

查詢執行選項
-e
將輸入指令碼寫入標準的輸出裝置 (stdout) 中。

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

-q "cmdline query"
在 sqlcmd 啟動時執行查詢，但在查詢完成執行時不會結束 sqlcmd 。可以執行多項以分號分隔的查詢。請依照下列範例所示，利用引號來括住查詢。

在命令提示字元中，輸入：

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

sqlcmd -d AdventureWorks2012 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

重要

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

如果使用此選項時指定 -b ， sqlcmd 會發生錯誤，並結束作業。本文稍後將描述 -b。

-Q 「cmdline query」
啟動 sqlcmd 時執行查詢，然後立即結束 sqlcmd。可以執行多項以分號分隔的查詢。

請依照下列範例所示，利用引號來括住查詢。

在命令提示字元中，輸入：

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

sqlcmd -d AdventureWorks2012 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

重要

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

如果使用此選項時指定 -b ， sqlcmd 會發生錯誤，並結束作業。本文稍後將描述 -b。

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

注意

實際逾時值可能與指定的 time_out 值之間有幾秒的差異。

-v var =value[ var =value...]
建立 sqlcmd指令碼中所能使用的 sqlcmd 指令碼變數。如果值包含空格，請用引號括住該值。您可以指定多個 var="values" 值。如果指定的任何值發生錯誤， sqlcmd 會產生一則錯誤訊息，並結束作業。

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

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

-x
讓 sqlcmd 忽略指令碼變數。當指令碼所包含的許多 INSERT 陳述式可能含有與一般變數 (例如 $(variable_name)) 相同格式的字串時，此參數就很有用。

格式化選項
-hheaders
指定資料行標頭之間所要列印的資料列數。預設值是每一組查詢結果各列印一次標頭。這個選項會設定 sqlcmd 指令碼變數 SQLCMDHEADERS。使用 -1 來指定不列印標頭。任何無效的值都會讓 sqlcmd 產生錯誤訊息，並結束作業。

-k [1 | 2]
從輸出中移除所有控制字元，如定位字元和新行字元。此參數會在資料傳回時，保留資料行的格式。如果指定 1，會用單一空格來取代控制字元。如果指定 2，會用單一空格取代連續控制字元。 -k 與 -k1相同。

-scol_separator
指定資料行分隔字元。預設值是空格。這個選項會設定 sqlcmd 指令碼變數 SQLCMDCOLSEP。若要使用對作業系統有特殊意義的字元，例如 ampersand () & 或分號 (;) ，請將字元括在引號 (「) 。資料行分隔字元可以是任何 8 位元的字元。

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

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

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

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

注意

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

重要

使用 -y 0 選項時，要非常小心，因為它可能會讓伺服器和網路出現嚴重的效能問題，這會隨著傳回的資料大小而不同。

-Yfixed_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時，傳回至 DOS ERRORLEVEL 變數的值為 1;否則，傳回的值為0。如果除了設定 -b 以外，還設定了 -V選項，且嚴重性層級低於使用 -V 所設定的值，則 sqlcmd不會報告發生錯誤。命令提示字元批次檔案可以測試 ERRORLEVEL 的值，而且能夠適當地處理錯誤。 sqlcmd 不會報告嚴重性層級 10 (資訊訊息) 的錯誤。

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

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

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

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

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

-cbatch_terminator
指定批次結束字元。根據預設，命令會終止並傳送至SQL Server，方法是在一行自行輸入「GO」一詞。當您重設批次結束字元時，請勿使用對作業系統具有特殊意義的 Transact-SQL 保留關鍵字或字元，即使它們前面有反斜線也一樣。

-L[c]
列出設定在本機的伺服器電腦，以及在網路中進行廣播的伺服器電腦名稱。此參數無法與其他參數搭配使用。可以列出的最大伺服器電腦數目為 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 選項的語法摘要。

備註

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

傳回多項結果時， sqlcmd 會在批次的各結果集之間，列印一行空白行。此外， <x> rows affected 當訊息不適用於執行的語句時，就不會顯示訊息。

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

注意

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

命令環境 (Cmd.exe) 中 sqlcmd 命令列的總長度 (包括所有引數和擴充的變數)，皆由 Cmd.exe 的作業系統決定。

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

系統層級環境變數
使用者層級環境變數
執行sqlcmd 之前，在命令提示字元處設定的命令殼層 ( SETX=Y)。
sqlcmd-v X=Y
:Setvar X Y

注意

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

sqlcmd 指令碼變數

變數	相關參數	R/W	預設
SQLCMDUSER	-U	R	""
SQLCMDPASSWORD	-P	--	""
SQLCMDSERVER	-S	R	"DefaultLocalInstance"
SQLCMDWORKSTATION	-H	R	"ComputerName"
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

:Out

[:] !!

:Perftrace

[ : ] QUIT

:Connect

[ : ] EXIT

:On Error

:Help

:ServerList

:XML [ON | OFF]

:Setvar

:Listvar

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

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

重要

為了顧及與現有 osql 指令碼的回溯相容性，也會辨識部分沒有冒號的命令，其以 [ : ] 表示。
sqlcmd 命令必須在行首，才能夠辨識。
所有 sqlcmd 命令都不區分大小寫。
每個命令都必須在不同行中。命令後面不能接著 Transact-SQL 語句或其他命令。
命令會立即執行，它們不會放在執行緩衝區中，因為 Transact-SQL 語句是。

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

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

SET SQLCMDEDITOR=notepad

[ : ] RESET
清除陳述式快取。

:List
列印陳述式快取內容。

變數
：Setvar<無功>[ 「value」 ]
定義 sqlcmd 指令碼變數。指令碼變數的格式如下： $(VARNAME)。

變數名稱不區分大小寫。

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

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

注意

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

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

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

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

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

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

注意

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

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

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

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

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

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

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

執行控制命令
:On Error[ exit | ignore]
設定執行指令碼或批次發生錯誤時所要執行的動作。

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

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

[ : ] QUIT
導致 sqlcmd 結束。

[ : ] EXIT[ (statement) ]
可讓您使用 SELECT 陳述式的結果作為 sqlcmd的傳回值。如果為數值，最後一個結果資料列的第一個資料行會轉換成 4 位元組的整數 (long)。 MS-DOS、Linux 和 Mac 會將低位元組傳遞給父處理序或作業系統錯誤層級。 Windows 200x 會傳遞完整的 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 會結束作業，且會將訊息識別碼傳回用戶端。例如：

RAISERROR(50001, 10, 127)

這個錯誤會使得 sqlcmd 指令碼結束作業，並將訊息識別碼 50001 傳回用戶端。

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

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

GO [count]
GO 會發出批次結束及執行任何快取的 Transact-SQL 陳述式的信號。該批次會作為個別批次執行數次。您無法在單一批次中宣告變數超過一次。

其他命令
：R <檔案名>
將檔案名> 所 < 指定檔案的其他 Transact-SQL 語句和sqlcmd命令剖析成語句快取。

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

注意

<檔案名稱> 會在與執行 sqlcmd 的啟動目錄相對位置中讀取。

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

注意

每次發現 :r 命令時，以互動模式顯示的行數便會加 1。 :r 命令會出現在 list 命令的輸出中。

:Serverlist
列出設定在本機的伺服器，以及在網路中進行廣播的伺服器名稱。

：Connectserver_name[ \instance_name] [-l timeout] [-U user_name [-P password]]
連接到 SQL Server 的實例。此外也會關閉目前的連接。

逾時選項：

值	行為
0	永久等候
n > 0	等候 n 秒

SQLCMDSERVER 指令碼變數會反映目前作用中的連接。

如果沒有指定 timeout ，預設值就是 SQLCMDLOGINTIMEOUT 變數的值。

如果只指定 user_name (作為選項或作為環境變數)，則會提示使用者輸入密碼。如果已設定 SQLCMDUSER 或 SQLCMDPASSWORD 環境變數，就不會提示使用者。如果既沒有提供選項，也沒有提供環境變數，就會利用 Windows 驗證模式來登入。例如，若要使用整合式安全性連線到實例， instance1 SQL Server 的 myserver ，您可以使用下列命令：

:connect myserver\instance1

若要利用指令碼變數來連接 myserver 的預設執行個體，您將使用下列命令：

:setvar myusername test

:setvar myservername myserver

:connect $(myservername) $(myusername)

[ : ] !!<command>
執行作業系統命令。若要執行作業系統命令，請在行首輸入兩個驚歎號 ( !! )，後面再接著作業系統命令。例如：

:!! Dir

注意

這個命令會在執行 sqlcmd 的電腦上執行。

:XML [ON | OFF]
如需詳細資訊，請參閱本文中的 XML 輸出格式和 JSON 輸出格式

:Help
列出 sqlcmd 命令及各命令的簡短描述。

sqlcmd 檔案名稱

您可以使用sqlcmd 選項或 sqlcmd 命令指定 sqlcmd 輸入檔。輸出檔則可以使用 -o 選項或 :Error、 :Out 和 :Perftrace 命令予以指定。以下列出使用這些檔案的幾項指導方針：

:Error、 :Out 和 :Perftrace 應該使用不同的 <filename > 。如果使用相同的 <filename > ，命令所產生的輸入可能會混合在一起。
如果從本機電腦的 sqlcmd 呼叫位於遠端伺服器上的輸入檔，且檔案中包含磁碟機檔案路徑 (例如 :Out c:\OutputFile.txt)，即會在本機電腦建立輸出檔案，而不是在遠端伺服器建立。
有效的檔案路徑包括︰C:\<filename>、\\<Server>\<Share$>\<filename> 與 "C:\Some Folder\<file name>"。如果路徑中有空格，請使用引號。
每個新的 sqlcmd 工作階段都會覆寫現有的同名檔案。

參考用訊息

sqlcmd 會列印伺服器所傳送的所有參考用訊息。在下列範例中，執行 Transact-SQL 陳述式之後，會列印一則參考用訊息。

於命令提示字元中，輸入命令：

sqlcmd

在 sqlcmd 提示字元中鍵入：

USE AdventureWorks2012;

GO

當您按 ENTER 時，會列印下列參考訊息：「已將資料庫內容變更為 'AdventureWorks2012'。」

Transact-SQL 查詢的輸出格式

sqlcmd 會先列印包含選取清單中所指定之資料行名稱的資料行標頭。資料行名稱是以 SQLCMDCOLSEP 字元分隔。根據預設，這是一個空格。如果資料行名稱長度小於資料行寬度，便會在輸出中填補空格直到下一個資料行。

這一行後面接著一連串虛線字元的分隔符號。下列輸出顯示一個範例。

啟動 sqlcmd。在 sqlcmd 命令提示字元中，鍵入下列查詢：

USE AdventureWorks2012;

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。

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

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

注意

:XML 命令不支援 SET STATISTICS XML 陳述式。

JSON 輸出格式

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