sqlcmd 公用程式

發行項
06/03/2023

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)

sqlcmd公用程式可讓您透過各種模式輸入 Transact-SQL 語句、系統程式和腳本檔案：

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

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

注意

如需 SQL Server 2014 (12.x) 和舊版，請參閱sqlcmd 公用程式。

如需在 Linux 上使用 sqlcmd ，請參閱在 Linux 上安裝 sqlcmd 和 bcp。

下載並安裝 sqlcmd

Windows

下載適用於 SQL Server 的 Microsoft 命令列公用程式 15 (x64)

下載適用於 SQL Server 的 Microsoft 命令列公用程式 15 (x86)

命令列工具已正式推出，不過，其將透過 SQL Server 2019 (15.x) 的安裝程式封裝發行。

版本資訊

版本號碼：15.0.4298.1
組建編號：15.0.4298.1
發行日期：2023 年 4 月 7 日

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

系統需求

Windows 7 到 Windows 11
Windows Server 2008 到 Windows Server - 2022

此元件同時需要內建 Windows Installer 5 及 Microsoft ODBC Driver 17 for SQL Server。

Linux 與 macOS

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

檢查版本

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

注意

您需要 13.1 版或更新版本來支援Always Encrypted () -g 和 Azure AD 驗證 (-G) 。您的電腦上可能已安裝數個版本的 sqlcmd 。請務必使用正確的版本。若要判斷版本，請執行 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 模式在 SQL Server Management Studio 中以及在 sqlcmd 公用程式中執行相同的查詢時，可能會看到不同的行為。

Syntax

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

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

-c

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

-d db_name

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

-d

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

注意

此選項 -D 僅適用于 Linux 和 macOS 用戶端。在 Windows 用戶端上，已移除且忽略以前稱為現已過時的選項。

-l login_timeout

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

-E

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

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

-g

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

-G

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

-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 AD 使用者名稱和密碼時，您可以使用和 -P 選項， -U 提供 -G 具有使用者名稱和密碼的選項。

sqlcmd -S testsrv.database.windows.net -d Target_DB_or_DW -U bob@contoso.com -P MyAzureADPassword -G

參數 -G 會在後端產生下列連接字串：

  SERVER = Target_DB_or_DW.testsrv.database.windows.net;UID=bob@contoso.com;PWD=MyAzureADPassword;AUTHENTICATION=ActiveDirectoryPassword;

Azure Active Directory 整合式驗證

針對 Azure AD 整合式驗證，請提供 -G 沒有使用者名稱或密碼的選項。 Azure AD 整合式驗證需要Microsoft ODBC Driver 17 for 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 互動式驗證，可讓您使用支援多重要素驗證的互動式方法。如需詳細資訊，請參閱 Active Directory 互動式驗證。

Azure AD 互動式驗證需要 sqlcmd15.0.1000.34 版和更新版本，以及 ODBC 17.2 版和更新版本。

若要啟用互動式驗證，請只提供 -G 使用者名稱 (-U) 選項，而不使用密碼。

下列範例會使用 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 租使用者中，而且屬於具有執行 sqlcmd命令之資料庫許可權的Azure SQL資料庫中的群組，則會使用其來賓使用者別名 (例如) keith0@adventureworks.com 。

重要

搭配sqlcmd使用 -G 和 -U 選項時，有一個已知問題，其中將選項放在 -U 選項之前 -G 可能會導致驗證失敗。請一律先以 -G 選項開始，再放置 -U 選項。

-H workstation_name

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

-j

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

-K application_intent

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

-M multisubnet_failover

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

-N

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

-P password

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

重要

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

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

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

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

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

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

SET SQLCMDPASSWORD=p@a$$w0rd

請在下列命令提示字元之下，輸入：

sqlcmd

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

注意

OSQLPASSWORD環境變數已保留供回溯相容性使用。 SQLCMDPASSWORD環境變數優先于 OSQLPASSWORD 環境變數。這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。舊版指令碼仍可繼續使用。

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

-P如果選項後面接著一個以上的引數，就會產生錯誤訊息並結束程式。

-S [protocol：]server[\instance_name][，port]

指定要連線的 SQL Server 執行個體。它會設定 sqlcmd 腳本變數 SQLCMDSERVER 。

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

通訊協定可以 tcp (TCP/IP) 、 lpc (共用記憶體) ，或 np (具名管道) 。

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

注意

OSQLSERVER環境變數已保留供回溯相容性使用。 SQLCMDSERVER環境變數優先于 OSQLSERVER 環境變數。這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。舊版指令碼仍可繼續使用。

-U login_id

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

注意

OSQLUSER環境變數已保留供回溯相容性使用。 SQLCMDUSER環境變數優先于 OSQLUSER 環境變數。這表示您可以先後使用 sqlcmd 和 osql ，而不會發生互相干擾的狀況。舊版指令碼仍可繼續使用。

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

-U如果選項與 -E 本文稍後所述的選項 (搭配使用，) ，就會產生錯誤訊息。 -U如果選項後面接著一個以上的引數，就會產生錯誤訊息並結束程式。

-z new_password

變更密碼：

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

-Z new_password

變更密碼並結束：

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

輸入/輸出選項

-f 字碼頁 |i：codepage[，o：codepage] |o：codepage[，i：codepage]

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

字碼頁轉換規則：

如果未指定字碼頁， sqlcmd 會針對輸入和輸出檔案使用目前的字碼頁，除非輸入檔是 Unicode 檔案，在此情況下不需要轉換。
sqlcmd 會自動識別位元組由大到小 (Big-Endian) 和位元組由小到大 (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>

-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

讓 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 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 「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;"

重要

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

如果 -b 與此選項一起指定， sqlcmd 會在錯誤時結束。 -b 本文的其他地方會說明。

-t query_timeout

指定命令 (或 Transact-SQL 語句) 逾時之前的秒數。此選項會設定 sqlcmd 腳本變數 SQLCMDSTATTIMEOUT 。如果未指定query_timeout值，命令就不會逾時。query_timeout必須是和 65534 之間的 1 數位。如果所提供的值不是數值或不在該範圍內，sqlcmd 就會產生錯誤訊息。

注意

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

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

建立 可用於 sqlcmd 腳本的 sqlcmd 腳本變數。如果值包含空格，請用引號括住該值。您可以指定多個 <var>="<value>" 值。如果指定的任何值發生錯誤， sqlcmd 會產生一則錯誤訊息，並結束作業。

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]

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

-s col_separator

指定資料行分隔字元。預設值是空格。此選項會設定 sqlcmd 腳本變數 SQLCMDCOLSEP 。若要使用對作業系統有特殊意義的字元，例如 ampersand () & 或分號 (;) ，請將字元括在引號 () " 。資料行分隔字元可以是任何 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)
text
ntext
image

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

警告

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

-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 回值。傳回變數 ERRORLEVEL 的值是 1 當SQL Server錯誤訊息的嚴重性層級大於 10 時，否則傳回的值為 0 。 -V如果除了已設定 -b 選項之外，如果嚴重性層級低於使用 -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 。 Batch 和 CMD 檔案可用來測試變數的值 ERRORLEVEL 。

其他選項

-a packet_size

要求不同大小的封包。此選項會設定 sqlcmd 腳本變數 SQLCMDPACKETSIZE 。 packet_size必須是和 32767 之間的 512 值。預設值為 4096。較大的封包大小可以增強執行命令之間 GO 有許多 Transact-SQL 語句的腳本效能。您可以要求較大的封包。但是，若要求遭到拒絕， sqlcmd 便會使用伺服器預設的封包大小。

-c batch_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 ，或 bash) ，包括所有引數和展開變數，在命令環境中 (sqlcmd命令列的總長度是由基礎作業系統決定。

變數優先順序 (低到高)

系統層級環境變數
使用者層級環境變數
命令殼層 (SET X=Y 在執行sqlcmd之前，先在命令提示字元中設定)
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使用時 :Connect ，會設定、 SQLCMDPASSWORD 和 SQLCMDSERVER 。

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

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

sqlcmd 命令

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

GO [ count ]

:List

[:]RESET

:Error

[:]ED

:Out

[:]!!

:Perftrace

[:]QUIT

:Connect

[:]EXIT

:On Error

:r

: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

[:]重置

清除陳述式快取。

:List

列印陳述式快取內容。

變數

：Setvar < var > [ 「value」 ]

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

變數名稱不區分大小寫。

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

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

注意

此選項 -X 可防止環境變數傳遞至 sqlcmd。

如果使用所 :Setvar 定義的變數和環境變數具有相同的名稱，則使用 :Setvar 所定義的變數會優先使用。

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

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

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

:Listvar

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

注意

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

輸出命令

：錯誤 <檔名> |STDERR |STDOUT

將所有錯誤輸出重新導向至 檔案名所指定的檔案， stderr 或重新導向至 stdout 。 :Error命令可以在腳本中出現多次。根據預設，錯誤輸出會傳送至 stderr 。

filename

建立並開啟接收輸出的檔案。如果檔案已經存在，它會截斷成零位元組。如果檔案因許可權或其他原因而無法使用，則不會切換輸出，而且會傳送至最後一個指定的或預設目的地。
STDERR

將錯誤輸出切換至 stderr 資料流程。如果已重新導向此專案，則已重新導向資料流程的目標會收到錯誤輸出。
STDOUT

將錯誤輸出切換至 stdout 資料流程。如果已重新導向此專案，則已重新導向資料流程的目標會收到錯誤輸出。

：Out <filename> |STDERR |STDOUT

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

:P erftrace <檔案名> |STDERR |STDOUT

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

執行控制命令

：On Error [ exit | ignore ]

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

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

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

[:]QUIT

導致 sqlcmd 結束。

[:]EXIT [ ( 語句 ) ]

可讓您使用語句的結果作為sqlcmd的 SELECT 傳回值。如果為數值，最後一個結果資料列的第一個資料行會轉換成 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)

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

如果在 RAISERRORsqlcmd 腳本中使用，而且引發狀態為 127， sqlcmd 將會結束，並將訊息識別碼傳回給用戶端。例如：

RAISERROR(50001, 10, 127)

此錯誤會導致 sqlcmd 腳本結束，並將訊息識別碼 50001 傳回給用戶端。

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

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

GO [count]

GO 會發出批次結尾和任何快取 Transact-SQL 語句的執行訊號。該批次會作為個別批次執行數次。您無法在單一批次中多次宣告變數。

其他命令

:r <檔案名稱>

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

如果檔案包含未後面接著 GO 的 Transact-SQL 語句，您必須在後面的 :r 行上輸入 GO 。

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

注意

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

:ServerList

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

：Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]]

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

逾時選項：

值	行為
`0`	永遠等候
`n>0`	等候 n 秒

腳本 SQLCMDSERVER 變數會反映目前的使用中連線。

如果未指定逾時，變數的值 SQLCMDLOGINTIMEOUT 是預設值。

如果只指定 user_name (做為選項或環境變數) ，系統會提示使用者輸入密碼。如果已設定或 SQLCMDPASSWORD 環境變數， SQLCMDUSER 則不會提示使用者。如果您未提供選項或環境變數，則會使用 Windows 驗證模式來登入。例如，若要使用整合式安全性連線至 SQL Server myserver 的執行個體 instance1，您將使用下列命令：

:connect myserver\instance1

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

:setvar myusername test
:setvar myservername myserver
:connect $(myservername) $(myusername)

[:]!! command

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

:!! dir

注意

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

：XML [ ON |OFF ]

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

:Help

列出 sqlcmd 命令，以及每個命令的簡短描述。

sqlcmd 檔案名

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

:Error、 :Out 和 :Perftrace 應該使用不同的 檔案名 值。如果使用相同的 filename ，命令所產生的輸入可能會混合在一起。
如果位於遠端伺服器上的輸入檔是從本機電腦上的 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時，會列印下列資訊訊息：「已將資料庫內容變更為 '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 個字元。您可以使用選項或設定 SQLCMDCOLWIDTH 腳本變數來變更 -w 。

XML 輸出格式

子句的結果 FOR XML 為連續資料流程中的輸出、未格式化的 XML 輸出。

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

注意

sqlcmd 會以一般格式傳回錯誤訊息。錯誤訊息也會以 XML 格式的 XML 文字資料流程輸出。如果使用 :XML ON， sqlcmd 就不會顯示參考用訊息。

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

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

XML (資料流) 資料和資料列集資料不能混合。 :XML ON如果在執行輸出 XML 資料流程的 Transact-SQL 語句之前尚未發出命令，輸出就會重編。 :XML ON發出命令之後，您無法執行輸出一般資料列集的 Transact-SQL 語句。

注意

命令 :XML 不支援 SET STATISTICS XML 語句。

JSON 輸出格式

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

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

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

使用 Azure AD 驗證

使用 Azure AD 驗證的範例：

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 最佳做法

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

使用整合式安全性。
在自動化環境中使用 -X[1]。
使用適當的檔案系統許可權來保護輸入和輸出檔案。
為提高效能，請盡可能在單一 sqlcmd 工作階段中執行所有工作，而不要使用一連串的工作階段。
將批次或查詢執行的逾時值，設定成高於您預期執行批次或查詢所需的時間值。

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

使用 -V16 來記錄任何嚴重性 16 層級訊息。嚴重性 16 訊息表示使用者可更正的一般錯誤。
在程式結束之後檢查結束代碼和 DOS ERRORLEVEL 變數。 sqlcmd 會正常傳回 0 ，否則它會設定 ERRORLEVEL 所設定的 -V 。換句話說， ERRORLEVEL 不應該與SQL Server報告的錯誤號碼相同。錯誤號碼是對應至系統函式@@ERROR SQL Server特定值。 ERRORLEVEL 是 sqlcmd特定的值，用來指出 sqlcmd 終止的原因，而且其值會受到指定 -b 命令列引數所影響。

使用 -V16 搭配檢查結束代碼，並可 DOS ERRORLEVEL 協助攔截自動化環境中的錯誤，特別是生產版本之前的品質閘道。

sqlcmd 公用程式

下載並安裝 sqlcmd

Windows

版本資訊

系統需求

Linux 與 macOS

檢查版本

預先安裝

Azure Cloud Shell

Azure Data Studio

SQL Server Management Studio (SSMS)

Syntax

命令列選項

登入相關選項

-A

-c

-d db_name

-d

-l login_timeout

-E

-g

-G

-H workstation_name

-j

-K application_intent

-M multisubnet_failover

-N

-P password

-S [protocol：]server[\instance_name][，port]

-U login_id

-z new_password

-Z new_password

輸入/輸出選項

-f 字碼頁 |i：codepage[，o：codepage] |o：codepage[，i：codepage]

-i input_file[，input_file2...]

-o output_file

-r[0 | 1]

-R

-U

查詢執行選項

-E

-I

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

-Y fixed_length_type_display_width

錯誤報表選項

-b

-m error_level

-V error_severity_level

其他選項

-a packet_size

-c batch_terminator

-L[c]

-p[1]

-X[1]

-?

備註

變數優先順序 (低到高)

sqlcmd 腳本變數

sqlcmd 命令

編輯命令

[:]ED

[:]重 置

:List

變數

：Setvar < var > [ 「value」 ]

:Listvar

輸出命令

：錯誤 <檔名> |STDERR |STDOUT

：Out <filename> |STDERR |STDOUT

[:]重置