Compartilhar via

Invoke-Sqlcmd

  • Referência
Módulo:
SQLServer

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

Sintaxe

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

Description

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

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 compatíveis nativamente 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 sem suporte incluem :!, :connect, :error, :out, :ed, :list, :listvar, :reset, :p erftrace 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 das primeiras, 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 a saída da mensagem do SQL Server, 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 de 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 back-tick (').

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 a saída detalhada

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

Este 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 para criar a 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 neste caso fornece informações extras, como o nome 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 ao 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 parâmetro -ApplicationIntent, a conexão é roteada para um servidor diferente no AG. A propósito, observe os usos dos parâmetros -ApplicationName 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 de -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 parâmetro -StatisticsVariable 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 Provider Statistics for SQL Server para obter mais informações sobre as estatísticas disponíveis.

Exemplo 17: execute uma consulta que descriptografa dados recuperados de colunas criptografadas usando o Always Encrypted. Suponha que a chave mestra de coluna esteja 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 do SQL Server e retorna um nível de erro para a variável ERRORLEVEL do Windows PowerShell 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 for 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 superior ao valor especificado para ErrorLevel.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-AccessToken

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

Isso pode ser usado, por exemplo, para se conectar a SQL Azure DB e SQL Azure Managed Instance usando 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, de senha ou de credencial de ao usar esse parâmetro.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationIntent

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

Os valores permitidos são: ReadOnly e ReadWrite.

Tipo:ApplicationIntent
Valores aceitos:ReadWrite, ReadOnly
Cargo:Named
Valor padrão:ReadWrite
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationName

O nome do aplicativo associado à conexão.

Tipo:String
Cargo:Named
Valor padrão:.NET SqlClient Data Provider
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ConnectionString

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

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 chegarão ao tempo limite.

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Credential

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

Tipo:PSCredential
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 banco de dados não for especificado, o banco de dados usado dependerá se o caminho atual especifica 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 se 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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-DedicatedAdministratorConnection

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

O DAC é usado pelos administradores do sistema para ações como a solução de problemas de instâncias que não aceitarão novas conexões padrão.

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

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 variáveis do Windows PowerShell sejam passadas para o script Invoke-Sqlcmd.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-DisableVariables

Indica que esse cmdlet ignora variáveis de script sqlcmd. Isso é útil quando um script contém muitas instruções INSERT que podem conter cadeias de caracteres que têm o mesmo formato que variáveis, como $(variable_name).

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Encrypt

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

Esse valor é mapeado para a propriedade EncryptSqlConnectionEncryptOption 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.

Tipo:String
Valores aceitos:Mandatory, Optional, Strict
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-EncryptConnection

Indica que esse cmdlet usa 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. As conexões são criptografadas por padrão. Em vez disso, considere usar o novo parâmetro -Encrypt. Para obter mais detalhes, consulte Strict Connection Encryption em Links Relacionados.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ErrorLevel

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

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FailoverPartner

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

Tipo:String
Cargo:Named
Valor padrão:""
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-HostName

Especifica um nome de estação de trabalho. O nome da estação de trabalho é relatado pelo procedimento armazenado do sistema sp_who e na coluna nome do host da exibição do 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.

Tipo:String
Aliases:WorkstationID
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 a instância do 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 do 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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-IgnoreProviderContext

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InputFile

Especifica um arquivo a ser usado como a entrada de consulta para este 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. 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 são protegidos com as permissões NTFS apropriadas.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-KeyVaultAccessToken

Especifica um token de acesso para cofres de chaves no Azure Key Vault. Use esse parâmetro se qualquer coluna a ser consultada estiver protegida com o Always Encrypted usando uma chave mestra de coluna 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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 o Always Encrypted usando uma chave mestra de coluna armazenada em um HSM gerenciado no Azure Key Vault. Como alternativa, você pode autenticar no Azure com Add-SqlAzureAuthenticationContext antes de chamar esse cmdlet.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MaxBinaryLength

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

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MaxCharLength

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

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MultiSubnetFailover

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

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-NewPassword

Especifica uma nova senha para uma ID de logon da 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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:OutputType
Aliases:As
Valores aceitos:DataSet, DataTables, DataRows
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-OutputSqlErrors

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

Tipo:Boolean
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Password

Especifica a senha da ID de logon da Autenticação do SQL Server 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 Senha seguido de sua senha, a senha ficará visível para qualquer pessoa que possa ver o monitor.

Se você codificar senha seguida de sua senha em um script de .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 possam ler o arquivo.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ProgressAction

Determina como o PowerShell responde às atualizações de progresso geradas por um script, cmdlet ou provedor, como as barras de progresso geradas pelo cmdlet Write-Progress. O cmdlet Write-Progress cria barras de progresso que mostram o status de um comando.

Tipo:ActionPreference
Aliases:proga
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Query

Especifica uma ou mais consultas que este 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 GO sqlcmd. Escape de todas aspas duplas incluídas na cadeia de caracteres. Considere usar identificadores entre colchetes, como [MyTable] em vez de identificadores entre aspas, como "MyTable".

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 perderão tempo limite. O tempo limite deve ser um valor inteiro entre 1 e 65535.

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:PSObject
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-SeverityLevel

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

Esse cmdlet retorna o nível de severidade mais alto das mensagens de erro geradas pelas consultas executadas, desde que a gravidade seja igual ou superior à especificada no parâmetro SeverityLevel.

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

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

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

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-StatisticsVariable

Especifique o nome de uma variável do PowerShell que receberá as estatísticas de tempo de execução do SQL Server 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 Provider Statistics for SQL Server.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SuppressProviderContextWarning

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Username

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

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

Se o nome de usuário e a 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 do Windows PowerShell. Quando possível, use a Autenticação do Windows.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Variable

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

Use uma matriz do 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.

Tipo:PSObject
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

System.Management.Automation.PSObject

Saídas

System.Object