Invoke-Sqlcmd

参考

模块:: SQLServer

运行包含 SQL Server SQLCMD 实用工具支持的语句的脚本。

语法

Invoke-Sqlcmd
      [-ServerInstance <PSObject>]
      [-Database <String>]
      [-Encrypt <String>]
      [-EncryptConnection]
      [-Username <String>]
      [-AccessToken <String>]
      [-Password <String>]
      [-Credential <PSCredential>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ConnectionTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DedicatedAdministratorConnection]
      [-DisableVariables]
      [-DisableCommands]
      [-HostName <String>]
      [-ApplicationName <String>]
      [-ApplicationIntent <ApplicationIntent>]
      [-MultiSubnetFailover]
      [-FailoverPartner <String>]
      [-HostNameInCertificate <String>]
      [-TrustServerCertificate]
      [-NewPassword <String>]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-SuppressProviderContextWarning]
      [-IgnoreProviderContext]
      [-OutputAs <OutputType>]
      [-StatisticsVariable <String>]
      [-ProgressAction <ActionPreference>]
      [<CommonParameters>]

Invoke-Sqlcmd
      [-AccessToken <String>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DisableVariables]
      [-DisableCommands]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-OutputAs <OutputType>]
      -ConnectionString <String>
      [-KeyVaultAccessToken <String>]
      [-ManagedHsmAccessToken <String>]
      [-StatisticsVariable <String>]
      [-ProgressAction <ActionPreference>]
      [<CommonParameters>]

说明

Invoke-Sqlcmd cmdlet 运行包含 SQL Server SQLCMD 实用工具支持的语言和命令的脚本。

支持的命令是 Transact-SQL 语句和数据库引擎支持的 XQuery 语法的子集。

此 cmdlet 还接受 SQLCMD 本机支持的许多命令，例如 GO 和 QUIT。

此 cmdlet 还接受 SQLCMD 脚本变量，例如 SQLCMDUSER。默认情况下，此 cmdlet 不设置 SQLCMD 脚本变量。

此 cmdlet 不支持使用主要与交互式脚本编辑相关的命令。

不支持的命令包括：!, ：connect、：error、：out、：ed、：list、：listvar、：reset、:p erftrace 和：serverlist。

运行此 cmdlet 时，脚本返回的第一个结果集显示为格式化表。

如果后续结果集包含的列列表与第一列列表不同，则不会显示这些结果集。

如果第一个集后的后续结果集具有相同的列列表，则其行将追加到包含第一个结果集返回的行的格式化表中。

可以通过指定 Verbose 参数来显示 SQL Server 消息输出，例如 SQL PRINT 语句生成的输出。

示例

示例 1：连接到命名实例并运行脚本

Invoke-Sqlcmd -Query "SELECT GETDATE() AS TimeOfQuery" -ServerInstance "MyComputer\MainInstance"

TimeOfQuery
-----------
9/21/2017 2:48:24 PM

此命令连接到计算机上的 SQL 数据库引擎的命名实例，并运行基本的 Transact-SQL 脚本。

示例 2：调用脚本文件中的命令，并将输出保存在文本文件中

Invoke-Sqlcmd -InputFile "C:\ScriptFolder\TestSqlCmd.sql" | Out-File -FilePath "C:\ScriptFolder\TestSqlCmd.rpt"
Output sent to TestSqlCmd.rpt.

此命令读取包含 Transact-SQL 语句和 SQLCMD 命令的文件，运行该文件，并将输出写入另一个文件。

输出文件可能包含专有信息，因此应使用适当的 NTFS 权限保护输出文件。

示例 3：调用脚本并从字符串传入变量值

$StringArray = "MYVAR1='String1'", "MYVAR2='String2'"
Invoke-Sqlcmd -Query "SELECT `$(MYVAR1) AS Var1, `$(MYVAR2) AS Var2" -Variable $StringArray

Var1     Var2
----     ----
String1  String2

此命令使用字符串数组作为变量参数的输入。

该数组定义多个 SQLCMD 变量。

SELECT 语句中标识 SQLCMD 变量的 $ 符号是使用后刻度（'）字符进行转义的。

示例 4：调用脚本并从 SQL 数据库引擎传入变量

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd -Query "SELECT SERVERPROPERTY('MachineName') AS ComputerName" -ServerInstance (Get-Item .)

ComputerName
------------
MyComputer

此命令使用 Set-Location 导航到 SQL 数据库引擎实例的 SQL ServerWindows PowerShell 提供程序路径。

然后，它调用 Get-Item 检索 SQL Management Object Server 对象，以用作 Invoke-Sqlcmd 的 ServerInstance 参数。

示例 5：运行查询并显示详细输出

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
Invoke-SqlCmd -Query "PRINT N'abc'" -Verbose
VERBOSE: abc

此命令使用 Windows PowerShellVerbose 参数返回 SQL PRINT 命令的消息输出。

示例 6：使用位置字符串作为输入调用命令

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance\Databases\MyDatabase"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd "SELECT DB_NAME() AS DatabaseName"
WARNING: Using provider context. Server = MyComputer\MainInstance, Database = MyDatabase.

DatabaseName
------------
MyDatabase

此命令使用位置字符串向 Query 参数提供输入。

它还演示了 Invoke-Sqlcmd 如何使用当前路径将数据库上下文设置为 MyDatabase。

示例 7：将数据捕获到 DataSet 对象中

$DS = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  ID, Item FROM MyDB.dbo.MyTable" -As DataSet
$DS.Tables[0].Rows | %{ echo "{ $($_['ID']), $($_['Item']) }" }

{ 10, AAA }
{ 20, BBB }
{ 30, CCC }

此命令使用 As DataSet 参数将数据捕获到 .Net System.Data.DataSet 对象中，并将结果存储在变量“$DS”。该对象可用于进一步处理。

示例 8：获取特定列集

$Tables = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  Item, id FROM MyDatabase.dbo.MyTable; SELECT GETDATE() AS T" -As DataTables
$Tables[0].Rows | %{ echo $_.ID }
$Tables[1].Rows | %{ echo $_.T.DayOfWeek }

10
20
30

Monday

第一个命令使用 As DataTables 参数将数据捕获到 .Net System.Data.DataTable 对象的集合中。该命令获取两个具有不同列集的表。

每个表可以单独处理，具体取决于自己的架构。

示例 9：完全控制连接

Invoke-Sqlcmd -Query "SELECT COUNT(*) AS Count FROM MyTable" -ConnectionString "Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly"
Count
-----
127432

此命令用户 -ConnectionString 参数，以完全控制此 cmdlet 建立的连接，而不是 Invoke-Sqlcmd 基于命令行传递的参数生成连接字符串。

这对于你可能想要使用的不太常见的属性非常有用。

示例 10：执行存储过程并捕获 SQL 错误

$script_sp_with_errors = @'
CREATE PROCEDURE [dbo].[TestProcedure3]
AS 
BEGIN 
  CREATE TABLE [dbo].[TestTable] (col INT NOT NULL);
  INSERT INTO [dbo].[TestTable] VALUES (NULL); -- will cause an error
END
GO
'@

# Create a test database
Invoke-SqlCmd -ServerInstance MyServer -Query 'CREATE DATABASE TestDB'
# ... adds a stored procedure that has errors in it...
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query $script_sp_with_errors
# ... executes the SP and collected the errors
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query 'EXEC TestProcedure3' -OutputSqlErrors $true

Here's the output:
Invoke-SqlCmd : Cannot insert the value NULL into column 'col', table 'TestDB.dbo.TestTable'; column does not allow nulls. INSERT fails.
The statement has been terminated.
 Msg 515, Level 16, State 2, Procedure TestProcedure3, Line 5.
At line:1 char:1
...

此命令用户 -OutputSqlErrors 参数向用户报告错误。请注意，在这种情况下，错误消息提供了额外的信息，如 SP 名称和发生错误的行号。

示例 11：使用访问令牌连接到 Azure SQL 数据库（或托管实例）

Import-Module SQLServer
Import-Module Az.Accounts -MinimumVersion 2.2.0

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

### Obtain the Access Token: this will bring up the login dialog
Connect-AzAccount
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

示例 12：使用服务主体连接到 Azure SQL 数据库（或托管实例）

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

$clientid = "enter application id that corresponds to the Service Principal" # Do not confuse with its display name
$tenantid = "enter the tenant ID of the Service Principal"
$secret = "enter the secret associated with the Service Principal"

$request = Invoke-RestMethod -Method POST `
           -Uri "https://login.microsoftonline.com/$tenantid/oauth2/token"`
           -Body @{ resource="https://database.windows.net/"; grant_type="client_credentials"; client_id=$clientid; client_secret=$secret }`
           -ContentType "application/x-www-form-urlencoded"
$access_token = $request.access_token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

示例 13：使用系统分配的托管标识（SAMI）连接到 Azure SQL 数据库（或托管实例）

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that VM Identity you are running on and has granted it access to the database (in this 
#       example at least the SELECT permission).

Connect-AzAccount -Identity
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token `
              -query 'select * from Table1'

示例 14：使用用户分配的托管标识（UAMI）连接到 Azure SQL 数据库（或托管实例）

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that VM Identity you are running on and has granted it access to the database (in this 
#       example at least the SELECT permission).

Connect-AzAccount -Identity -AccountId '<your-user-assigned-managed-identity-client-id>'
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token `
              -query 'select * from Table1'

示例 15：使用 -ApplicationIntent 连接到配置为 Read-Only 路由的可用性组

# In the following example:
# - MT_2009250511 is a listener for an AG configured for Read-Only Routing (port 5555)
# - AGDB_2_1 is the DB in the AG
# - VLM00226138 is the primary replica configured to only allow ReadWrite connections 
# - VLM00226137 is the secondary replica
# 
Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox1" -ApplicationName "ReadWrite" -ApplicationIntent ReadWrite `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"

Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox2" -ApplicationName "ReadOnly" -ApplicationIntent ReadOnly `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"  

# When you run the 2 cmdlets above, the output is going to be something like this:  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox1 ReadWrite         VLM00226138  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox2 ReadOnly          VLM00226137

这显示，根据 -ApplicationIntent 参数的值，连接将路由到 AG 中的其他服务器。顺便说一句，观察 -ApplicationName 和 -HostName 参数的使用，直观地区分这两个结果：这是一种常见的技术，可用于跟踪连接及其意图，而不是此处所述的 -ApplicationIntent 示例。

示例 16：通过 -StatisticsVariable 参数捕获连接统计信息

Import-Module SQLServer
Invoke-Sqlcmd -ServerInstance localhost -StatisticsVariable stats `
              -Query 'CREATE TABLE #Table (ID int); INSERT INTO #Table VALUES(1), (2); INSERT INTO #Table VALUES(3); SELECT * FROM #Table'

Write-Host "Number of rows affected......: $($stats.IduRows)"
Write-Host "Number of insert statements..: $($stats.IduCount)"
Write-Host "Number of select statements..: $($stats.SelectCount)"
Write-Host "Total execution time.........: $($stats.ExecutionTime)ms"

# When you run the code fragment above, is going to be something like this:  
#
# Number of rows affected......: 3
# Number of insert statements..: 2
# Number of select statements..: 1
# Total execution time.........: 5ms

此示例演示如何使用 -StatisticsVariable 参数捕获有关连接的信息、执行的语句以及运行创建临时表的一些 T-SQL 时执行时间，插入一些值，最后发出一个选择来获取所有插入的行。

注意：当对多个服务器执行同一查询（例如，通过管道服务器名称到 cmdlet）时，StatisticsVariable 会捕获统计信息数组，每个连接一个。然后，可以使用 ($stats.IduRows | Measure-Object -Sum).Sum来聚合结果。

有关可用统计信息的详细信息，请参阅 SQL Server 的提供程序统计信息。

示例 17：运行一个查询，用于解密使用 Always Encrypted 加密的列检索到的数据。假设列主密钥存储在 Azure Key Vault 中的密钥保管库中。

# Connect to Azure account.
Import-Module Az.Accounts -MinimumVersion 2.2.0
Connect-AzAccount

# Obtain an access token for key vaults. 
$keyVaultAccessToken = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token

# Pass the token to the cmdlet, so that it can use it to authenticate to Azure when decrypting data protected with Always Encrypted.
$connString = 'Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly;Column Encryption Setting=Enabled'
Invoke-Sqlcmd -Query 'SELECT COUNT(*) AS Count FROM MyTable' -ConnectionString $connString -KeyVaultAccessToken $keyVaultAccessToken

参数

-AbortOnError

指示此 cmdlet 停止 SQL Server 命令，如果此 cmdlet 遇到错误，则向 Windows PowerShell ERRORLEVEL 变量返回错误级别。

如果错误严重性高于 10，则返回的错误级别为 1，如果错误严重性为 10 或更少，则错误级别为 0。

如果还指定了 ErrorLevel 参数，则仅当错误消息严重性也等于或高于为 ErrorLevel 指定的值时，此 cmdlet 才会返回 1。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-AccessToken

用于向 SQL Server 进行身份验证的访问令牌，作为用户/密码或 Windows 身份验证的替代方法。

例如，这可用于使用 Service Principal 或 Managed Identity 连接到 SQL Azure DB 和 SQL Azure Managed Instance（请参阅此页面底部的引用）

在常见情况下，使用类似于 (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token（需要 Az.Account 模块）获取此参数

使用此参数时，请勿指定 UserName、Password或 Credential。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ApplicationIntent

连接到 SQL Server 可用性组中的数据库时的应用程序工作负荷类型。

允许的值为：ReadOnly 和 ReadWrite。

类型:	ApplicationIntent
接受的值:	ReadWrite, ReadOnly
Position:	Named
默认值:	ReadWrite
必需:	False
接受管道输入:	False
接受通配符:	False

-ApplicationName

与连接关联的应用程序的名称。

类型:	String
Position:	Named
默认值:	.NET SqlClient Data Provider
必需:	False
接受管道输入:	False
接受通配符:	False

-ConnectionString

指定要连接到服务器的连接字符串。

类型:	String
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-ConnectionTimeout

指定当此 cmdlet 无法成功连接到数据库引擎实例时超时的秒数。超时值必须是介于 0 和 65534 之间的整数值。如果指定了 0，则连接尝试不会超时。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Credential

用于连接到 SQL 实例的用户名和密码字段的 PSCredential 对象。

类型:	PSCredential
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Database

指定数据库的名称。此 cmdlet 连接到 ServerInstance 参数中指定的实例中的此数据库。

如果未指定 Database 参数，则使用的数据库取决于当前路径是否同时指定 SQLSERVER：\SQL 文件夹和数据库名称。如果路径同时指定 SQL 文件夹和数据库名称，则此 cmdlet 将连接到路径中指定的数据库。如果路径不基于 SQL 文件夹，或者路径不包含数据库名称，则此 cmdlet 将连接到当前登录 ID 的默认数据库。如果指定 IgnoreProviderContext 参数开关，则此 cmdlet 不会考虑当前路径中指定的任何数据库，并连接到定义为当前登录 ID 的默认值的数据库。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-DedicatedAdministratorConnection

指示此 cmdlet 使用专用管理员连接（DAC）连接到数据库引擎的实例。

DAC 由系统管理员用于无法接受新标准连接的操作，例如故障排除实例。

必须将实例配置为支持 DAC。

如果未启用 DAC，此 cmdlet 将报告错误，并且不会运行。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-DisableCommands

指示此 cmdlet 关闭某些 sqlcmd 功能，这些功能可能会在批处理文件中运行时危及安全性。

它阻止 Windows PowerShell 变量传入 Invoke-Sqlcmd 脚本。

SQLCMDINI 脚本变量中指定的启动脚本未运行。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-DisableVariables

指示此 cmdlet 忽略 sqlcmd 脚本变量。当脚本包含许多可能包含与变量具有相同格式的字符串（如 $（variable_name）的字符串时，这非常有用。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Encrypt

连接到 SQL Server 时要使用的加密类型。

此值映射到 Microsoft.Data.SqlClient 驱动程序的 SqlConnection 对象的 Encrypt 属性 SqlConnectionEncryptOption。

如果未指定，则默认值为 Mandatory。

此参数是模块 v22 中的新增参数。有关详细信息，请参阅相关链接下的 Strict Connection Encryption。

类型:	String
接受的值:	Mandatory, Optional, Strict
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-EncryptConnection

指示此 cmdlet 使用安全套接字层（SSL/TLS）加密连接到 ServerInstance 参数中指定的数据库引擎实例。

从模块 v22 开始，此参数已弃用。连接默认加密。请考虑改用新的 -Encrypt 参数。有关详细信息，请参阅相关链接下的 Strict Connection Encryption。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ErrorLevel

指定此 cmdlet 仅显示严重性级别等于或高于指定值的错误消息。如果未指定此参数或设置为 0，则会显示所有错误消息。数据库引擎错误严重性范围为 1 到 24。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-FailoverPartner

如果主服务器关闭，则要连接到的伙伴服务器的名称或地址。

类型:	String
Position:	Named
默认值:	""
必需:	False
接受管道输入:	False
接受通配符:	False

-HostName

指定工作站名称。工作站名称由sp_who系统存储过程和 sys.process 目录视图的主机名列中报告。如果未指定此参数，则默认值为运行 Invoke-Sqlcmd 的计算机的名称。此参数可用于标识不同的 Invoke-Sqlcmd 会话。

类型:	String
别名:	WorkstationID
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-HostNameInCertificate

用于验证 SQL Server TLS/SSL 证书的主机名。如果为强制加密启用了 SQL Server 实例，并且想要使用主机名/shortname 连接到实例，则必须传递此参数。如果省略此参数，则必须将完全限定域名（FQDN）传递给 -ServerInstance 才能连接到为强制加密启用的 SQL Server 实例。

此参数是模块 v22 中的新增参数。有关详细信息，请参阅相关链接下的 Strict Connection Encryption。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-IgnoreProviderContext

指示此 cmdlet 忽略由当前 SQLSERVER：\SQL 路径建立的数据库上下文。如果未指定 Database 参数，则此 cmdlet 将默认数据库用于当前登录 ID 或 Windows 帐户。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-IncludeSqlUserErrors

指示此 cmdlet 返回默认忽略的 SQL 用户脚本错误。如果指定此参数，则此 cmdlet 与 sqlcmd 实用工具的默认行为匹配。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-InputFile

指定要用作此 cmdlet 的查询输入的文件。该文件可以包含 Transact-SQL 语句、XQuery 语句和 sqlcmd 命令和脚本变量。指定文件的完整路径。该文件应使用 UTF-8 进行编码。

应仅从受信任的源运行脚本。确保所有输入脚本都使用适当的 NTFS 权限进行保护。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-KeyVaultAccessToken

指定 Azure Key Vault 中密钥保管库的访问令牌。如果使用 Azure Key Vault 中密钥保管库中存储的列主密钥通过 Always Encrypted 保护要查询的任何列，请使用此参数。或者，在调用此 cmdlet 之前，可以使用 Add-SqlAzureAuthenticationContext 向 Azure 进行身份验证。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ManagedHsmAccessToken

指定 Azure Key Vault 中托管 HSM 的访问令牌。如果使用 Azure Key Vault 中托管 HSM 中存储的列主密钥保护要查询的任何列，请使用此参数。或者，在调用此 cmdlet 之前，可以使用 Add-SqlAzureAuthenticationContext 向 Azure 进行身份验证。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaxBinaryLength

指定为具有二进制字符串数据类型的列返回的最大字节数，例如二进制和 varbinary。默认值为 1,024 字节。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaxCharLength

指定为具有字符或 Unicode 数据类型的列返回的最大字符数，例如 char、nchar、varchar 和 nvarchar。默认值为 4,000 个字符。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MultiSubnetFailover

如果应用程序连接到不同子网上的 AlwaysOn 可用性组（AG），则传递此参数可以更快地检测和连接到活动服务器（当前）活动服务器。

注意：.NET Framework 4.6.1 或更高版本不需要传递 -MultiSubnetFailover。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-NewPassword

指定 SQL Server 身份验证登录 ID 的新密码。此 cmdlet 更改密码，然后退出。还必须指定用户名和密码参数，并使用密码指定登录名的当前密码。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-OutputAs

指定此 cmdlet 获取的结果的类型。

如果未为此参数指定值，则 cmdlet 会将该值设置为 DataRows。

类型:	OutputType
别名:	As
接受的值:	DataSet, DataTables, DataRows
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-OutputSqlErrors

指示此 cmdlet 在 Invoke-Sqlcmd 输出中显示错误消息。

类型:	Boolean
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Password

指定在 Username 参数中指定的 SQL Server 身份验证登录 ID 的密码。密码区分大小写。如果可能，请使用 Windows 身份验证。如果可能使用强密码，请勿使用空白密码。

如果指定密码参数后跟密码，则任何可以看到监视器的用户都可以看到密码。

如果在 .ps1 脚本中编码密码后跟密码，则读取脚本文件的任何人都可以看到密码。

将适当的 NTFS 权限分配给该文件，以防止其他用户能够读取该文件。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ProgressAction

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的进度更新，例如由 Write-Progress cmdlet 生成的进度栏。 Write-Progress cmdlet 创建显示命令状态的进度栏。

类型:	ActionPreference
别名:	proga
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Query

指定此 cmdlet 运行的一个或多个查询。查询可以是 Transact-SQL 或 XQuery 语句，也可以是 sqlcmd 命令。可以指定以分号分隔的多个查询。请勿指定 sqlcmd GO 分隔符。转义字符串中包含的任何双引号。请考虑使用括号标识符（如 [MyTable]），而不是带引号的标识符，例如“MyTable”。

类型:	String
Position:	0
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-QueryTimeout

指定查询超时前的秒数。如果未指定超时值，则查询不会超时。超时必须是介于 1 和 65535 之间的整数值。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ServerInstance

指定一个字符串或 SQL Server 管理对象（SMO）对象，该对象指定数据库引擎实例的名称。对于默认实例，仅指定计算机名称：MyComputer。对于命名实例，请使用 ComputerName\InstanceName 格式。

类型:	PSObject
Position:	Named
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-SeverityLevel

指定此 cmdlet 返回 ERRORLEVEL Windows PowerShell 变量的错误消息严重性级别的下限。

如果严重性等于或高于 SeverityLevel 参数中指定的严重性，此 cmdlet 会从其运行的查询生成的错误消息中返回最高严重级别。

如果未指定 SeverityLevel 或设置为 0，则此 cmdlet 将返回 0 到 ERRORLEVEL。

数据库引擎错误消息的严重性级别范围为 1 到 24。

此 cmdlet 不会报告严重性为 10 的信息性消息的严重性

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StatisticsVariable

指定在执行 cmdlet 时将为其分配 SQL Server 运行时统计信息的 PowerShell 变量的名称。

此参数的常见用途是捕获提供程序处理 cmdlet 所花费的 ExecutionTime（以毫秒为单位）或 IduRows（INSERT、DELETE 和 UPDATE 语句影响的行总数）。

有关详细信息，请参阅 SQL Server的提供程序统计信息。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-SuppressProviderContextWarning

指示此 cmdlet 禁止显示此 cmdlet 在当前 SQLSERVER：\SQL 路径设置中使用的数据库上下文中用于为 cmdlet 建立数据库上下文的警告。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TrustServerCertificate

指示通道是否在绕过证书链以验证信任的同时进行加密。

此参数是模块 v22 中的新增参数。有关详细信息，请参阅相关链接下的 Strict Connection Encryption。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Username

指定用于与数据库引擎实例建立 SQL Server 身份验证连接的登录 ID。

密码必须通过 Password 参数指定。

如果未指定用户名和密码，则此 cmdlet 会尝试使用运行 Windows PowerShell 会话的 Windows 帐户进行 Windows 身份验证连接。如果可能，请使用 Windows 身份验证。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Variable

指定一组用于 sqlcmd 脚本的 sqlcmd 脚本变量，并设置变量的值。

使用 Windows PowerShell 数组指定多个变量及其值;或者，使用 Hashtable，其中键表示变量名称和变量值的值。

使用数组时，将剪裁参数值。此行为保留在模块的 v22 中，以实现与 v21 的向后兼容性。建议不要依赖此行为，这可能会在模块的未来主版本中发生更改。

Hashtable 类型的参数仅在模块的 v22+ 中可用。

类型:	PSObject
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

System.Management.Automation.PSObject

输出

System.Object

通过

Invoke-Sqlcmd

语法

说明

示例

示例 1：连接到命名实例并运行脚本

示例 2：调用脚本文件中的命令，并将输出保存在文本文件中

示例 3：调用脚本并从字符串传入变量值

示例 4：调用脚本并从 SQL 数据库引擎传入变量

示例 5：运行查询并显示详细输出

示例 6：使用位置字符串作为输入调用命令

示例 7：将数据捕获到 DataSet 对象中

示例 8：获取特定列集

示例 9：完全控制连接

示例 10：执行存储过程并捕获 SQL 错误

示例 11：使用访问令牌连接到 Azure SQL 数据库（或托管实例）

示例 12：使用服务主体连接到 Azure SQL 数据库（或托管实例）

示例 13：使用系统分配的托管标识（SAMI）连接到 Azure SQL 数据库（或托管实例）

示例 14：使用用户分配的托管标识（UAMI）连接到 Azure SQL 数据库（或托管实例）

示例 15：使用 -ApplicationIntent 连接到配置为 Read-Only 路由的可用性组

示例 16：通过 -StatisticsVariable 参数捕获连接统计信息

示例 17：运行一个查询，用于解密使用 Always Encrypted 加密的列检索到的数据。 假设列主密钥存储在 Azure Key Vault 中的密钥保管库中。

参数

-AbortOnError

-AccessToken

-ApplicationIntent

-ApplicationName

-ConnectionString

-ConnectionTimeout

-Credential

-Database

-DedicatedAdministratorConnection

-DisableCommands

-DisableVariables

-Encrypt

-EncryptConnection

-ErrorLevel

-FailoverPartner

-HostName

-HostNameInCertificate

-IgnoreProviderContext

-IncludeSqlUserErrors

-InputFile

-KeyVaultAccessToken

-ManagedHsmAccessToken

-MaxBinaryLength

-MaxCharLength

-MultiSubnetFailover

-NewPassword

-OutputAs

-OutputSqlErrors

-Password

-ProgressAction

-Query

-QueryTimeout

-ServerInstance

-SeverityLevel

-StatisticsVariable

-SuppressProviderContextWarning

-TrustServerCertificate

-Username

-Variable

输入

输出

相关链接

反馈

反馈

其他资源

示例 17：运行一个查询，用于解密使用 Always Encrypted 加密的列检索到的数据。假设列主密钥存储在 Azure Key Vault 中的密钥保管库中。