Share via

Invoke-Sqlcmd

  • Referência
Módulo:
SQLServer

Executa um script que contém instruções compatíveis com o utilitário SQLCMD SQL Server.

Syntax

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>]
      [<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>]
      [<CommonParameters>]

Description

O cmdlet Invoke-Sqlcmd executa um script que contém os idiomas e comandos compatíveis com o utilitário SQLCMD SQL Server.

Os comandos com suporte são instruções Transact-SQL e o subconjunto da sintaxe XQuery compatível com o mecanismo de banco de dados.

Esse cmdlet também aceita muitos dos comandos com suporte nativo pelo SQLCMD, como GO e QUIT.

Esse cmdlet também aceita as variáveis de script SQLCMD, como SQLCMDUSER. Por padrão, esse cmdlet não define variáveis de script SQLCMD.

Esse cmdlet não dá suporte ao uso de comandos relacionados principalmente à edição interativa de script.

Os comandos que não têm suporte são: :!!, :connect, :error, :out, :ed, :list, :listvar, :reset, :perftrace e :serverlist.

Quando esse cmdlet é executado, o primeiro conjunto de resultados que o script retorna é exibido como uma tabela formatada.

Se os conjuntos de resultados subsequentes contiverem listas de colunas diferentes da primeira, esses conjuntos de resultados não serão exibidos.

Se os conjuntos de resultados subsequentes após o primeiro conjunto tiverem a mesma lista de colunas, suas linhas serão acrescentadas à tabela formatada que contém as linhas retornadas pelo primeiro conjunto de resultados.

Você pode exibir SQL Server saída de mensagem, como aquelas resultantes da instrução SQL PRINT, especificando o parâmetro Verbose.

Exemplos

Exemplo 1: Conectar-se a uma instância nomeada e executar um script

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

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

Esse comando se conecta a uma instância nomeada do Mecanismo de Banco de Dados SQL em um computador e executa um script Transact-SQL básico.

Exemplo 2: invocar comandos em um arquivo de script e salvar a saída em um arquivo de texto

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

Esse comando lê um arquivo que contém instruções Transact-SQL e comandos SQLCMD, executa o arquivo e grava a saída em outro arquivo.

O arquivo de saída pode conter informações proprietárias, portanto, você deve proteger os arquivos de saída com as permissões NTFS apropriadas.

Exemplo 3: Invocar um script e passar valores variáveis de uma cadeia de caracteres

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

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

Esse comando usa uma matriz de cadeias de caracteres como entrada para o parâmetro Variable.

A matriz define várias variáveis SQLCMD.

Os sinais $ na instrução SELECT que identificam as variáveis SQLCMD são escapados usando o caractere de tique de fundo (').

Exemplo 4: Invocar um script e passar variáveis do mecanismo de banco de dados 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

Esse comando usa Set-Location para navegar até o caminho do provedor do SQL ServerWindows PowerShell para uma instância do Mecanismo de Banco de Dados SQL.

Em seguida, ele chama Get-Item para recuperar um objeto SQL Management Object Server para uso como o parâmetro ServerInstance de Invoke-Sqlcmd.

Exemplo 5: Executar uma consulta e exibir uma saída detalhada

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

Esse comando usa o parâmetro Windows PowerShellVerbose para retornar a saída da mensagem do comando SQL PRINT.

Exemplo 6: Invocar um comando usando uma cadeia de caracteres posicional como entrada

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

Esse comando usa uma cadeia de caracteres posicional para fornecer a entrada para o parâmetro Query.

Ele também demonstra como Invoke-Sqlcmd usa o caminho atual para definir o contexto do banco de dados como MyDatabase.

Exemplo 7: Capturar dados em um objeto 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 }

Esse comando usa o parâmetro As DataSet para capturar os dados em um objeto .Net System.Data.DataSet e armazena o resultado na variável '$DS'. O objeto pode ser usado para processamento adicional.

Exemplo 8: Obter conjuntos de colunas específicos

$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

O primeiro comando usa o parâmetro As DataTables para capturar os dados em uma coleção de objetos .Net System.Data.DataTable. O comando obtém duas tabelas com conjuntos de colunas diferentes.

Cada tabela pode ser processada individualmente, com base em seu próprio esquema.

Exemplo 9: Obter controle total de uma conexão

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

Esse comando usa o parâmetro -ConnectionString para obter controle total da conexão estabelecida por esse cmdlet, em vez do Invoke-Sqlcmd criar o cadeia de conexão com base nos parâmetros passados na linha de comando.

Isso é útil para propriedades menos comuns que talvez você queira usar.

Exemplo 10: Executar um procedimento armazenado e capturar os erros do 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
...

Esse comando usa o parâmetro -OutputSqlErrors para relatar os erros ao usuário. Observe que a mensagem de erro nesse caso fornece informações extras, como o nome do SP e o número de linha em que o erro ocorreu.

Exemplo 11: Conectar-se ao Banco de Dados SQL do Azure (ou Instância Gerenciada) usando um Token de Acesso

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'

Exemplo 12: Conectar-se ao Banco de Dados SQL do Azure (ou Instância Gerenciada) usando uma entidade de serviço

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'

Exemplo 13: Conectar-se ao Banco de Dados SQL do Azure (ou Instância Gerenciada) usando uma SAMI (Identidade Gerenciada Atribuída pelo Sistema)

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'

Exemplo 14: Conectar-se ao Banco de Dados SQL do Azure (ou Instância Gerenciada) usando uma UAMI (identidade gerenciada atribuída pelo usuário)

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'

Exemplo 15: Conectar-se a um grupo de disponibilidade configurado para roteamento de Read-Only usando -ApplicationIntent

# 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

o que mostra que, dependendo do valor do -ApplicationIntent parâmetro, a conexão é roteada para um servidor diferente no AG. Aliás, observe os usos dos -ApplicationName parâmetros e -HostName para diferenciar visualmente os dois resultados: essa é uma técnica comum que pode ser usada para rastrear conexões e suas intenções, além do exemplo -ApplicationIntent ilustrado aqui.

Exemplo 16: Capturar estatísticas de conexão por meio do parâmetro -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

Este exemplo mostra como usar o -StatisticsVariable parâmetro para capturar informações sobre a conexão, as instruções executadas e o tempo de execução ao executar algum T-SQL que cria uma tabela temporária, inserir algum valor e, por fim, emite uma seleção para obter todas as linhas inseridas.

Observação: quando a mesma consulta é executada em vários servidores (por exemplo, canalizando os nomes do servidor por meio do cmdlet), o StatisticsVariable captura uma matriz de estatísticas, uma para cada conexão. Os resultados podem ser agregados usando, por exemplo, ($stats.IduRows | Measure-Object -Sum).Sum.

Consulte Estatísticas do Provedor para SQL Server para obter mais informações sobre as estatísticas disponíveis.

Exemplo 17: execute uma consulta que descriptografa os dados recuperados de colunas criptografadas usando Always Encrypted. Suponha que a coluna master chave seja armazenada em um cofre de chaves no 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

Parâmetros

-AbortOnError

Indica que esse cmdlet interrompe o comando SQL Server e retorna um nível de erro para a variável WINDOWS POWERSHELL ERRORLEVEL se esse cmdlet encontrar um erro.

O nível de erro retornado será 1 se o erro tiver uma severidade maior que 10 e o nível de erro será 0 se o erro tiver uma severidade de 10 ou menos.

Se o parâmetro ErrorLevel também for especificado, esse cmdlet retornará 1 somente se a severidade da mensagem de erro também for igual ou maior do que o valor especificado para ErrorLevel.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AccessToken

O token de acesso usado para autenticar para SQL Server, como uma alternativa ao usuário/senha ou à Autenticação do Windows.

Isso pode ser usado, por exemplo, para se conectar SQL Azure DB e SQL Azure Managed Instance usar um Service Principal ou um Managed Identity (consulte referências na parte inferior desta página)

Em cenários comuns, esse parâmetro é obtido com algo como (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token (requer o módulo Az.Account)

Não especifique UserName, Password ou Credential ao usar esse parâmetro.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationIntent

O tipo de carga de trabalho do aplicativo ao se conectar a um banco de dados em um grupo de disponibilidade SQL Server.

Os valores permitidos são: ReadOnly e ReadWrite.

Type:ApplicationIntent
Accepted values:ReadWrite, ReadOnly
Position:Named
Default value:ReadWrite
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationName

O nome do aplicativo associado à conexão.

Type:String
Position:Named
Default value:.NET SqlClient Data Provider
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ConnectionString

Especifica um cadeia de conexão para se conectar ao servidor.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ConnectionTimeout

Especifica o número de segundos em que esse cmdlet atinge o tempo limite se não puder se conectar com êxito a uma instância do Mecanismo de Banco de Dados. O valor de tempo limite deve ser um valor inteiro entre 0 e 65534. Se 0 for especificado, as tentativas de conexão não atingirão o tempo limite.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

O objeto PSCredential cujos campos Nome de usuário e senha serão usados para se conectar à instância do SQL.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Database

Especifica o nome de um banco de dados. Esse cmdlet se conecta a esse banco de dados na instância especificada no parâmetro ServerInstance.

Se o parâmetro Database não for especificado, o banco de dados usado dependerá se o caminho atual especificará a pasta SQLSERVER:\SQL e um nome de banco de dados. Se o caminho especificar a pasta SQL e um nome de banco de dados, esse cmdlet se conectará ao banco de dados especificado no caminho. Se o caminho não for baseado na pasta SQL ou o caminho não contiver um nome de banco de dados, esse cmdlet se conectará ao banco de dados padrão para a ID de logon atual. Se você especificar a opção de parâmetro IgnoreProviderContext, esse cmdlet não considerará nenhum banco de dados especificado no caminho atual e se conectará ao banco de dados definido como o padrão para a ID de logon atual.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DedicatedAdministratorConnection

Indica que esse cmdlet usa uma DAC (Conexão de Administrador Dedicada) para se conectar a uma instância do Mecanismo de Banco de Dados.

A DAC é usada por administradores de sistema para ações como instâncias de solução de problemas que não aceitarão novas conexões padrão.

A instância deve ser configurada para dar suporte a DAC.

Se o DAC não estiver habilitado, esse cmdlet relatará um erro e não será executado.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisableCommands

Indica que esse cmdlet desativa alguns recursos sqlcmd que podem comprometer a segurança quando executados em arquivos em lote.

Ele impede que Windows PowerShell variáveis sejam passadas para o script Invoke-Sqlcmd.

O script de inicialização especificado na variável de script SQLCMDINI não é executado.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisableVariables

Indica que esse cmdlet ignora variáveis de script sqlcmd. Isso é útil quando um script tiver muitas instruções INSERT que podem conter cadeias de caracteres com o mesmo formato de variáveis, como, por exemplo, $(nome_da_variável).

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Encrypt

O tipo de criptografia a ser usado ao se conectar a SQL Server.

Esse valor é mapeado para a Encrypt propriedade SqlConnectionEncryptOption no objeto SqlConnection do driver Microsoft.Data.SqlClient.

Quando não especificado, o valor padrão é Mandatory.

Esse parâmetro é novo na v22 do módulo. Para obter mais detalhes, consulte Strict Connection Encryption em Links Relacionados.

Type:String
Accepted values:Mandatory, Optional, Strict
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptConnection

Indica que esse cmdlet usa a criptografia SSL/TLS (Secure Sockets Layer) para a conexão com a instância do Mecanismo de Banco de Dados especificada no parâmetro ServerInstance.

A partir da v22 do módulo, esse parâmetro é preterido. Connections são criptografados por padrão. Em vez disso, considere usar o novo parâmetro -Encrypt. Para obter mais detalhes, consulte Strict Connection Encryption em Links Relacionados.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ErrorLevel

Especifica que esse cmdlet exibe apenas mensagens de erro cujo nível de severidade é igual ou maior do que o valor especificado. Todas as mensagens de erro serão exibidas se esse parâmetro não for especificado ou definido como 0. A severidade dos erros do Mecanismo de Banco de Dados varia de 1 a 24.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FailoverPartner

O nome ou endereço do servidor parceiro ao qual se conectar se o servidor primário estiver inativo.

Type:String
Position:Named
Default value:""
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HostName

Especifica um nome da estação de trabalho. O nome da estação de trabalho é reportado pelo procedimento armazenado do sistema sp_who e na coluna hostname da exibição de catálogo sys.processes. Se esse parâmetro não for especificado, o padrão será o nome do computador no qual Invoke-Sqlcmd é executado. Esse parâmetro pode ser usado para identificar diferentes sessões de Invoke-Sqlcmd.

Type:String
Aliases:WorkstationID
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HostNameInCertificate

O nome do host a ser usado na validação do certificado TLS/SSL do SQL Server. Você deve passar esse parâmetro se sua instância de SQL Server estiver habilitada para o Force Encryption e quiser se conectar a uma instância usando nome de host/nome curto. Se esse parâmetro for omitido, passar o FQDN (Nome de Domínio Totalmente Qualificado) para -ServerInstance será necessário para se conectar a uma instância de SQL Server habilitada para o Force Encryption.

Esse parâmetro é novo na v22 do módulo. Para obter mais detalhes, consulte Strict Connection Encryption em Links Relacionados.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IgnoreProviderContext

Indica que esse cmdlet ignora o contexto de banco de dados estabelecido pelo caminho SQLSERVER:\SQL atual. Se o parâmetro Database não for especificado, esse cmdlet usará o banco de dados padrão para a ID de logon atual ou a conta do Windows.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludeSqlUserErrors

Indica que esse cmdlet retorna erros de script de usuário do SQL que, de outra forma, são ignorados por padrão. Se esse parâmetro for especificado, esse cmdlet corresponderá ao comportamento padrão do utilitário sqlcmd.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputFile

Especifica um arquivo a ser usado como a entrada de consulta para esse cmdlet. O arquivo pode conter instruções Transact-SQL, instruções XQuery e comandos sqlcmd e variáveis de script. Especifique o caminho completo para o arquivo. Não são permitidos espaços no caminho do arquivo ou no nome do arquivo. Espera-se que o arquivo seja codificado usando UTF-8.

Você só deve executar scripts de fontes confiáveis. Verifique se todos os scripts de entrada estão seguros com as permissões NTFS apropriadas.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-KeyVaultAccessToken

Especifica um token de acesso para cofres de chaves no Key Vault do Azure. Use esse parâmetro se qualquer coluna a ser consultada estiver protegida com Always Encrypted usando uma coluna master chave armazenada em um cofre de chaves no Azure Key Vault. Como alternativa, você pode autenticar no Azure com Add-SqlAzureAuthenticationContext antes de chamar esse cmdlet.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ManagedHsmAccessToken

Especifica um token de acesso para HSMs gerenciados no Azure Key Vault. Use esse parâmetro se qualquer coluna a ser consultada estiver protegida com Always Encrypted usando uma coluna master chave armazenada em um HSM gerenciado no Azure Key Vault. Como alternativa, você pode autenticar no Azure com Add-SqlAzureAuthenticationContext antes de chamar esse cmdlet.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxBinaryLength

Especifica o número máximo de bytes retornados para colunas com tipos de dados de cadeia de caracteres binários, como binary e varbinary. O valor padrão é 1.024 bytes.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxCharLength

Especifica o número máximo de caracteres retornados para colunas com tipos de dados de caracteres ou Unicode como char, nchar, varchar e nvarchar. O valor padrão é 4.000 caracteres.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MultiSubnetFailover

Se o aplicativo estiver se conectando a um AG (Grupo de Disponibilidade AlwaysOn) em sub-redes diferentes, passar esse parâmetro fornecerá detecção e conexão mais rápidas com o servidor ativo (atualmente).

Observação: passar -MultiSubnetFailover não é necessário com .NET Framework 4.6.1 ou versões posteriores.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NewPassword

Especifica uma nova senha para a ID de logon de autenticação do SQL Server. Esse cmdlet altera a senha e, em seguida, é encerrado. Você também deve especificar os parâmetros Nome de usuário e Senha, com Senha que especifica a senha atual para o logon.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputAs

Especifica o tipo de resultados que este cmdlet obtém.

Se você não especificar um valor para esse parâmetro, o cmdlet definirá o valor como DataRows.

Type:OutputType
Aliases:As
Accepted values:DataSet, DataTables, DataRows
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputSqlErrors

Indica que esse cmdlet exibe mensagens de erro na saída Invoke-Sqlcmd.

Type:Boolean
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Password

Especifica a senha do SQL Server ID de logon de autenticação especificada no parâmetro Username. As senhas diferenciam maiúsculas de minúsculas. Quando possível, use a Autenticação do Windows. Não use uma senha em branco. Quando possível, use uma senha forte.

Se você especificar o parâmetro Password seguido de sua senha, a senha ficará visível para qualquer pessoa que possa ver o monitor.

Se você codificar Senha seguido de sua senha em um script .ps1, qualquer pessoa que ler o arquivo de script verá sua senha.

Atribua as permissões NTFS apropriadas ao arquivo para impedir que outros usuários sejam capazes de ler o arquivo.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Query

Especifica uma ou mais consultas que esse cmdlet executa. As consultas podem ser instruções Transact-SQL ou XQuery, ou comandos sqlcmd. Várias consultas separadas por um ponto e vírgula podem ser especificadas. Não especifique o separador sqlcmd GO. Use caracteres de escape nas aspas duplas incluídas na cadeia de caracteres. Use identificadores entre colchetes, como [MyTable], em vez de identificadores entre aspas, como "MyTable".

Type:String
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-QueryTimeout

Especifica o número de segundos antes do tempo limite das consultas. Se um valor de tempo limite não for especificado, as consultas não atingirão o tempo limite. O tempo limite deve ser um valor inteiro entre 1 e 65535.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ServerInstance

Especifica uma cadeia de caracteres ou um objeto SMO (SQL Server Management Objects) que especifica o nome de uma instância do Mecanismo de Banco de Dados. Para instâncias padrão, especifique apenas o nome do computador: MyComputer. Para instâncias nomeadas, use o formato ComputerName\InstanceName.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-SeverityLevel

Especifica o limite inferior para o nível de severidade da mensagem de erro que esse cmdlet retorna à variável ERRORLEVEL Windows PowerShell.

Esse cmdlet retorna o nível de severidade mais alto das mensagens de erro geradas pelas consultas que ele executa, desde que a gravidade seja igual ou maior do que o especificado no parâmetro SeverityLevel.

Se SeverityLevel não for especificado ou definido como 0, esse cmdlet retornará 0 para ERRORLEVEL.

Os níveis de severidade das mensagens de erro do Mecanismo de Banco de Dados variam de 1 a 24.

Este cmdlet não relata severidades para mensagens informativas que têm uma gravidade de 10

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StatisticsVariable

Especifique o nome de uma variável do PowerShell que será atribuída ao SQL Server estatísticas em tempo de execução quando o cmdlet for executado.

O uso comum para esse parâmetro é capturar o ExecutionTime (a quantidade cumulativa de tempo (em milissegundos) que o provedor gastou processando o cmdlet) ou IduRows (o número total de linhas afetadas pelas instruções INSERT, DELETE e UPDATE).

Para obter mais detalhes, consulte Estatísticas do provedor para SQL Server.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SuppressProviderContextWarning

Indica que esse cmdlet suprime o aviso que esse cmdlet usou no contexto do banco de dados da configuração de caminho SQLSERVER:\SQL atual para estabelecer o contexto do banco de dados para o cmdlet.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TrustServerCertificate

Indica se o canal será criptografado ao ignorar a cadeia de certificados para validar a confiança.

Esse parâmetro é novo na v22 do módulo. Para obter mais detalhes, consulte Strict Connection Encryption em Links Relacionados.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Username

Especifica a ID de logon para fazer uma conexão de Autenticação do SQL Server para uma instância do Mecanismo de Banco de Dados.

A senha deve ser especificada por meio do parâmetro Password.

Se Nome de usuário e senha não forem especificados, esse cmdlet tentará uma conexão de Autenticação do Windows usando a conta do Windows que executa a sessão Windows PowerShell. Quando possível, use a Autenticação do Windows.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Variable

Especifica um conjunto de variáveis de script sqlcmd para uso no script sqlcmd e define um valor para as variáveis.

Use uma matriz Windows PowerShell para especificar várias variáveis e seus valores; como alternativa, use um Hashtable em que a chave represente o nome da variável e o valor do valor da variável.

Ao usar uma matriz, os valores de parâmetro são cortados. Esse comportamento foi mantido na v22 do módulo para compatibilidade com versões anteriores com v21. É recomendável não confiar nesse comportamento, o que pode mudar em uma versão principal futura do módulo.

O parâmetro do tipo Hashtable só está disponível na v22+ do módulo.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

System.Management.Automation.PSObject

Saídas

System.Object