Invoke-Sqlcmd

Referencia

Módulo:: SQLServer

Ejecuta un script que contiene instrucciones compatibles con la utilidad SQL SERVER SQLCMD.

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

El cmdlet Invoke-Sqlcmd ejecuta un script que contiene los idiomas y comandos admitidos por la utilidad SQLCMD de SQL Server.

Los comandos admitidos son instrucciones Transact-SQL y el subconjunto de la sintaxis XQuery compatible con el motor de base de datos.

Este cmdlet también acepta muchos de los comandos admitidos de forma nativa por SQLCMD, como GO y QUIT.

Este cmdlet también acepta las variables de scripting de SQLCMD, como SQLCMDUSER. De forma predeterminada, este cmdlet no establece variables de scripting de SQLCMD.

Este cmdlet no admite el uso de comandos relacionados principalmente con la edición interactiva de scripts.

Entre los comandos no admitidos se incluyen :!!, :connect, :error, :out, :ed, :list, :listvar, :reset, :perftrace y :serverlist.

Cuando se ejecuta este cmdlet, el primer conjunto de resultados que devuelve el script se muestra como una tabla con formato.

Si los conjuntos de resultados posteriores contienen listas de columnas diferentes a las primeras, no se muestran esos conjuntos de resultados.

Si los conjuntos de resultados posteriores después del primer conjunto tienen la misma lista de columnas, sus filas se anexan a la tabla con formato que contiene las filas devueltas por el primer conjunto de resultados.

Puede mostrar SQL Server salida del mensaje, como las resultantes de la instrucción PRINT de SQL, especificando el parámetro Verbose.

Ejemplos

Ejemplo 1: Conexión a una instancia con nombre y ejecución de un script

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

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

Este comando se conecta a una instancia con nombre del motor de SQL Database en un equipo y ejecuta un script básico de Transact-SQL.

Ejemplo 2: Invocar comandos en un archivo de script y guardar la salida en un archivo de texto

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

Este comando lee un archivo que contiene instrucciones Transact-SQL y comandos SQLCMD, ejecuta el archivo y escribe la salida en otro archivo.

El archivo de salida puede contener información propietaria, por lo que debe proteger los archivos de salida con los permisos NTFS adecuados.

Ejemplo 3: Invocar un script y pasar valores de variable desde una cadena

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

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

Este comando usa una matriz de cadenas de caracteres como entrada para el parámetro Variable.

La matriz define varias variables SQLCMD.

$inicia sesión en la instrucción SELECT que identifica las variables SQLCMD se escapan mediante el carácter back-tick (').

Ejemplo 4: Invocar un script y pasar variables desde el motor de base de datos 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

Este comando usa Set-Location para navegar a la ruta de acceso del proveedor sql ServerWindows de PowerShell para una instancia del motor de SQL Database.

A continuación, llama a Get-Item para recuperar un objeto sql Management Object Server para usarlo como parámetro ServerInstance de Invoke-Sqlcmd.

Ejemplo 5: Ejecución de una consulta y visualización de la salida detallada

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

Este comando usa el parámetro Windows PowerShellVerbose para devolver la salida del mensaje del comando SQL PRINT.

Ejemplo 6: Invocación de un comando mediante una cadena 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

Este comando usa una cadena posicional para proporcionar la entrada al parámetro Query.

También muestra cómo Invoke-Sqlcmd usa la ruta de acceso actual para establecer el contexto de la base de datos en MyDatabase.

Ejemplo 7: Capturar datos en un 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 }

Este comando usa el parámetro As DataSet para capturar los datos en un objeto System.Data.DataSet de .Net y almacena el resultado en la variable "$DS". El objeto se puede usar para su posterior procesamiento.

Ejemplo 8: Obtener conjuntos de columnas 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

El primer comando usa el parámetro As DataTables para capturar los datos en una colección de objetos System.Data.DataTable de .Net. El comando obtiene dos tablas con conjuntos de columnas diferentes.

Cada tabla se puede procesar individualmente, en función de su propio esquema.

Ejemplo 9: Obtener control total de una conexión

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

Este comando usuarios del parámetro -ConnectionString para obtener el control total de la conexión que establece este cmdlet, en lugar del Invoke-Sqlcmd para compilar el cadena de conexión en función de los parámetros pasados en la línea de comandos.

Esto es útil para las propiedades menos comunes que es posible que quiera usar.

Ejemplo 10: Ejecutar un procedimiento almacenado y capturar los errores de 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
...

Este comando usuarios el parámetro -OutputSqlErrors para notificar los errores al usuario. Tenga en cuenta que el mensaje de error en este caso proporciona información adicional, como el nombre del SP y el número de línea donde se produjo el error.

Ejemplo 11: Conexión a Azure SQL Database (o Instancia administrada) mediante un token de acceso

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'

Ejemplo 12: Conexión a Azure SQL Database (o Instancia administrada) mediante una entidad de servicio

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'

Ejemplo 13: Conexión a Azure SQL Database (o Instancia administrada) mediante una identidad administrada

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).

## Obtain access token from the machine
if (Get-Command -All az -ErrorAction SilentlyContinue -CommandType Application) {
  # Obtain the Access Token from the Azure provider for database resources (using az az cli)
  az login
  $access_token = az account get-access-token --resource https://database.windows.net/ --query accessToken -o tsv
} else {
  # az cli not around: fall back and assume this is a VM in Azure
  $response = Invoke-WebRequest `
    -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fdatabase.windows.net'`
    -Method GET`
    -Headers @{Metadata="true"}
  $access_token = ($response.Content | ConvertFrom-Json).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'

Este ejemplo es similar al anterior. Solo muestra la flexibilidad del parámetro AccessToken .

Ejemplo 14: Conexión a un grupo de disponibilidad configurado para Read-Only Enrutamiento mediante -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

que muestra que, en función del valor del -ApplicationIntent parámetro, la conexión se enruta a un servidor diferente del grupo de disponibilidad. Por cierto, observe los usos de los -ApplicationName parámetros y -HostName para diferenciar visualmente los dos resultados: se trata de una técnica común que se puede usar para realizar un seguimiento de las conexiones y sus intenciones, más allá del ejemplo -ApplicationIntent que se muestra aquí.

Ejemplo 15: Capturar estadísticas de conexión mediante el 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

En este ejemplo se muestra cómo usar el -StatisticsVariable parámetro para capturar información sobre la conexión, las instrucciones ejecutadas y el tiempo de ejecución al ejecutar un T-SQL que crea una tabla temporal, insertar algún valor y, por último, emite una selección para obtener todas las filas insertadas.

Nota: cuando se ejecuta la misma consulta en varios servidores (por ejemplo, mediante la canalización de los nombres de servidor a través del cmdlet ), captura StatisticsVariable una matriz de estadísticas, una para cada conexión. A continuación, los resultados se pueden agregar mediante, por ejemplo, ($stats.IduRows | Measure-Object -Sum).Sum.

Consulte Estadísticas del proveedor para obtener SQL Server para obtener más información sobre las estadísticas disponibles.

Ejemplo 16: Ejecute una consulta que descifre los datos recuperados de las columnas cifradas mediante Always Encrypted. Supongamos que la clave maestra de columna se almacena en un almacén de claves en 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 este cmdlet detiene el comando SQL Server y devuelve un nivel de error a la variable ERRORLEVEL de Windows PowerShell si este cmdlet encuentra un error.

El nivel de error devuelto es 1 si el error tiene una gravedad mayor que 10 y el nivel de error es 0 si el error tiene una gravedad de 10 o menos.

Si también se especifica el parámetro ErrorLevel, este cmdlet devuelve 1 solo si la gravedad del mensaje de error también es igual o mayor que el valor especificado para ErrorLevel.

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

-AccessToken

Token de acceso que se usa para autenticarse en SQL Server, como alternativa a la autenticación de usuario o contraseña de Windows.

Esto se puede usar, por ejemplo, para conectarse a SQL Azure DB y SQL Azure Managed Instance usar o Service Principal ( Managed Identity vea referencias en la parte inferior de esta página).

En escenarios comunes, este parámetro se obtiene con algo parecido (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token a (requiere el módulo Az.Account).

No especifique UserName, Password o Credential al usar este parámetro.

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

-ApplicationIntent

Tipo de carga de trabajo de aplicación al conectarse a una base de datos de un grupo de disponibilidad SQL Server.

Los valores permitidos son: ReadOnly y ReadWrite.

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

-ApplicationName

Nombre de la aplicación asociada a la conexión.

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

-ConnectionString

Especifica un cadena de conexión para conectarse al servidor.

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

-ConnectionTimeout

Especifica el número de segundos en que se agota el tiempo de espera de este cmdlet si no se puede conectar correctamente a una instancia del motor de base de datos. El valor de tiempo de espera debe ser un valor entero entre 0 y 65534. Si se especifica 0, los intentos de conexión no tienen tiempo de espera.

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

-Credential

Objeto PSCredential cuyos campos Nombre de usuario y Contraseña se usarán para conectarse a la instancia de SQL.

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

-Database

Especifica el nombre de una base de datos. Este cmdlet se conecta a esta base de datos en la instancia especificada en el parámetro ServerInstance.

Si no se especifica el parámetro Database, la base de datos que se usa depende de si la ruta de acceso actual especifica la carpeta SQLSERVER:\SQL y un nombre de base de datos. Si la ruta de acceso especifica la carpeta SQL y un nombre de base de datos, este cmdlet se conecta a la base de datos especificada en la ruta de acceso. Si la ruta de acceso no se basa en la carpeta SQL o la ruta de acceso no contiene un nombre de base de datos, este cmdlet se conecta a la base de datos predeterminada para el identificador de inicio de sesión actual. Si especifica el modificador de parámetro IgnoreProviderContext, este cmdlet no tiene en cuenta ninguna base de datos especificada en la ruta de acceso actual y se conecta a la base de datos definida como valor predeterminado para el identificador de inicio de sesión actual.

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

-DedicatedAdministratorConnection

Indica que este cmdlet usa una conexión de administrador dedicada (DAC) para conectarse a una instancia del motor de base de datos.

Los administradores de sistemas usan la DAC para acciones como la solución de problemas de instancias que no aceptarán nuevas conexiones estándar.

La instancia debe configurarse para ser compatible con la DAC.

Si la DAC no está habilitada, este cmdlet notifica un error y no se ejecutará.

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

-DisableCommands

Indica que este cmdlet desactiva algunas características de sqlcmd que podrían poner en peligro la seguridad al ejecutarse en archivos por lotes.

Evita que Windows PowerShell variables se pasen al script de Invoke-Sqlcmd.

El script de inicio especificado en las variables de scripting SQLCMDINI no se ejecuta.

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

-DisableVariables

Indica que este cmdlet omite las variables de scripting de sqlcmd. Es útil cuando un script contiene muchas instrucciones INSERT que pueden contener cadenas con el mismo formato que las variables normales, por ejemplo, $(variable_name).

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

-Encrypt

Tipo de cifrado que se va a usar al conectarse a SQL Server.

Este valor se asigna a la Encrypt propiedad SqlConnectionEncryptOption del objeto SqlConnection del controlador Microsoft.Data.SqlClient.

Si no se especifica, el valor predeterminado es Mandatory.

Este parámetro es nuevo en la versión 22 del módulo. Para obtener más información, consulte Strict Connection Encryption en Vínculos 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 este cmdlet usa el cifrado capa de sockets seguros (SSL/TLS) para la conexión a la instancia del motor de base de datos especificado en el parámetro ServerInstance.

A partir de la versión 22 del módulo, este parámetro está en desuso. Connections se cifran de forma predeterminada. Considere la posibilidad de usar el nuevo parámetro -Encrypt en su lugar. Para obtener más información, consulte Strict Connection Encryptionen Vínculos relacionados.

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

-ErrorLevel

Especifica que este cmdlet solo muestra mensajes de error cuyo nivel de gravedad es igual o superior al valor especificado. Todos los mensajes de error se muestran si no se especifica este parámetro o se establece en 0. La gravedad de los errores del Motor de base de datos va de 1 a 24.

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

-FailoverPartner

Nombre o dirección del servidor asociado al que se va a conectar si el servidor principal está inactivo.

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

-HostName

Especifica un nombre de estación de trabajo. El nombre de la estación de trabajo se notifica mediante el procedimiento almacenado sp_who system y la columna hostname de la vista de catálogo sys.processes. Si no se especifica este parámetro, el valor predeterminado es el nombre del equipo en el que se ejecuta Invoke-Sqlcmd. Este parámetro se puede usar para identificar diferentes sesiones de Invoke-Sqlcmd.

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

-HostNameInCertificate

Nombre de host que se va a usar al validar el certificado TLS/SSL de SQL Server. Debe pasar este parámetro si la instancia de SQL Server está habilitada para Forzar cifrado y desea conectarse a una instancia mediante el nombre de host o el nombre corto. Si se omite este parámetro, es necesario pasar el nombre de dominio completo (FQDN) a -ServerInstance para conectarse a una instancia de SQL Server habilitada para forzar el cifrado.

Este parámetro es nuevo en la versión 22 del módulo. Para obtener más información, consulte Strict Connection Encryptionen Vínculos relacionados.

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

-IgnoreProviderContext

Indica que este cmdlet omite el contexto de la base de datos establecido por la ruta de acceso SQLSERVER:\SQL actual. Si no se especifica el parámetro Database, este cmdlet usa la base de datos predeterminada para el identificador de inicio de sesión actual o la cuenta de Windows.

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

-IncludeSqlUserErrors

Indica que este cmdlet devuelve errores de script de usuario de SQL que, de lo contrario, se omiten de forma predeterminada. Si se especifica este parámetro, este cmdlet coincide con el comportamiento predeterminado de la utilidad sqlcmd.

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

-InputFile

Especifica un archivo que se va a usar como entrada de consulta para este cmdlet. El archivo puede contener instrucciones de Transact-SQL y XQuery, comandos de sqlcmd y variables de scripting. Especifique la ruta de acceso completa al archivo. No se permiten los espacios en la ruta de acceso de archivo o el nombre de archivo. Se espera que el archivo se codifique mediante UTF-8.

Solo debe ejecutar scripts de orígenes de confianza. Asegúrese de que todos los scripts de entrada están protegidos con los permisos NTFS apropiados.

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

-KeyVaultAccessToken

Especifica un token de acceso para almacenes de claves en Azure Key Vault. Use este parámetro si alguna columna que se va a consultar está protegida con Always Encrypted mediante una clave maestra de columna almacenada en un almacén de claves de Azure Key Vault. Como alternativa, puede autenticarse en Azure con Add-SqlAzureAuthenticationContext antes de llamar a este cmdlet.

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

-ManagedHsmAccessToken

Especifica un token de acceso para los HSM administrados en Azure Key Vault. Use este parámetro si alguna columna que se va a consultar está protegida con Always Encrypted mediante una clave maestra de columna almacenada en un HSM administrado en Azure Key Vault. Como alternativa, puede autenticarse en Azure con Add-SqlAzureAuthenticationContext antes de llamar a este cmdlet.

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

-MaxBinaryLength

Especifica el número máximo de bytes devueltos para las columnas con los tipos de datos de cadena binaria, como binary y varbinary. El valor predeterminado es de 1024 bytes.

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

-MaxCharLength

Especifica el número máximo de caracteres devueltos para las columnas con los tipos de datos de carácter o Unicode como char, nchar, varchar y nvarchar. El valor predeterminado es de 4000 caracteres.

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

-MultiSubnetFailover

Si la aplicación se conecta a un grupo de disponibilidad AlwaysOn (AG) en subredes diferentes, pasar este parámetro proporciona una detección más rápida de y la conexión al servidor activo (actualmente).

Nota: No se requiere pasar -MultiSubnetFailover con .NET Framework 4.6.1 o versiones posteriores.

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

-NewPassword

Especifica una nueva contraseña para el identificador de inicio de sesión de la autenticación de SQL Server. Este cmdlet cambia la contraseña y, a continuación, sale. También debe especificar los parámetros Username y Password, con Password que especifica la contraseña actual para el inicio de sesión.

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

-OutputAs

Especifica el tipo de los resultados que obtiene este cmdlet.

Si no especifica un valor para este parámetro, el cmdlet establece el valor en 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 este cmdlet muestra mensajes de error en la salida del Invoke-Sqlcmd.

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

-Password

Especifica la contraseña del identificador de inicio de sesión de autenticación de SQL Server que se especificó en el parámetro Username. En las contraseñas se distingue entre mayúsculas y minúsculas. Siempre que sea posible, utilice la autenticación de Windows. No use una contraseña en blanco, siempre que se pueda usar una contraseña segura.

Si especifica el parámetro Password seguido de la contraseña, la contraseña es visible para cualquier persona que pueda ver el monitor.

Si codifica la contraseña seguida de la contraseña en un script de .ps1, cualquier persona que lea el archivo de script verá la contraseña.

Asigne los permisos NTFS apropiados al archivo para impedir que otros usuarios puedan leer el archivo.

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

-Query

Especifica una o varias consultas que ejecuta este cmdlet. Las consultas pueden ser instrucciones de Transact-SQL o XQuery, o comandos de sqlcmd. Se pueden especificar varias consultas separadas por un punto y coma. No especifique el separador GO de sqlcmd. Eluda las comillas dobles incluidas en la cadena. Considere la posibilidad de usar identificadores entre corchetes como [MiTabla] en lugar de identificadores entrecomillados como "MiTabla".

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

-QueryTimeout

Especifica el número de segundos antes de que se agote el tiempo de espera de las consultas. Si no se especifica un valor de tiempo de espera, las consultas no agota el tiempo de espera. El tiempo de espera debe ser un valor entero entre 1 y 65535.

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

-ServerInstance

Especifica una cadena de caracteres o un objeto SQL Server Objetos de administración (SMO) que especifica el nombre de una instancia del motor de base de datos. Para las instancias predeterminadas, especifique solo el nombre del equipo: MyComputer. Para las instancias con nombre, use el formato NombreDeEquipo\NombreDeInstancia.

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

-SeverityLevel

Especifica el límite inferior para el nivel de gravedad del mensaje de error que devuelve este cmdlet a la variable ERRORLEVEL Windows PowerShell.

Este cmdlet devuelve el nivel de gravedad más alto de los mensajes de error generados por las consultas que ejecuta, siempre que la gravedad sea igual o superior a la especificada en el parámetro SeverityLevel.

Si No se especifica SeverityLevel o se establece en 0, este cmdlet devuelve 0 a ERRORLEVEL.

Los niveles de gravedad de los mensajes de error del Motor de base de datos van de 1 a 24.

Este cmdlet no notifica gravedades para los mensajes informativos que tienen una gravedad de 10

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

-StatisticsVariable

Especifique el nombre de una variable de PowerShell que se asignará al SQL Server estadísticas en tiempo de ejecución cuando se ejecute el cmdlet.

El uso común de este parámetro es capturar ExecutionTime (la cantidad acumulativa de tiempo (en milisegundos) que el proveedor ha dedicado a procesar el cmdlet) o IduRows (el número total de filas afectadas por instrucciones INSERT, DELETE y UPDATE).

Para obtener más información, consulte Estadísticas del proveedor para SQL Server.

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

-SuppressProviderContextWarning

Indica que este cmdlet suprime la advertencia de que este cmdlet ha usado en el contexto de base de datos de la configuración actual de la ruta de acceso SQLSERVER:\SQL para establecer el contexto de la base de datos para el cmdlet.

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

-TrustServerCertificate

Indica si el canal se cifrará al pasar la cadena de certificados para validar la confianza.

Este parámetro es nuevo en la versión 22 del módulo. Para obtener más información, consulte Strict Connection Encryptionen Vínculos relacionados.

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

-Username

Especifica el identificador de inicio de sesión para establecer una conexión de la autenticación de SQL Server con una instancia del Motor de base de datos.

La contraseña debe especificarse a través del parámetro Password.

Si no se especifica el nombre de usuario y la contraseña, este cmdlet intenta una conexión de autenticación de Windows mediante la cuenta de Windows que ejecuta la sesión de Windows PowerShell. Siempre que sea posible, utilice la autenticación de Windows.

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

-Variable

Especifica un conjunto de variables de scripting sqlcmd para su uso en el script sqlcmd y establece un valor para las variables.

Use una matriz de Windows PowerShell para especificar varias variables y sus valores; como alternativa, use un Hashtable donde la clave represente el nombre de la variable y el valor de la variable.

Cuando se usa una matriz, se recortan los valores de parámetro. Este comportamiento se mantuvo en la versión 22 del módulo para la compatibilidad con versiones anteriores con v21. Se recomienda no confiar en este comportamiento, lo que puede cambiar en una versión principal futura del módulo.

El parámetro de tipo Hashtable solo está disponible en la versión 22+ del módulo.

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

Entradas

System.Management.Automation.PSObject

Salidas

System.Object

Invoke-Sqlcmd

Syntax

Description

Ejemplos

Ejemplo 1: Conexión a una instancia con nombre y ejecución de un script

Ejemplo 2: Invocar comandos en un archivo de script y guardar la salida en un archivo de texto

Ejemplo 3: Invocar un script y pasar valores de variable desde una cadena

Ejemplo 4: Invocar un script y pasar variables desde el motor de base de datos SQL

Ejemplo 5: Ejecución de una consulta y visualización de la salida detallada

Ejemplo 6: Invocación de un comando mediante una cadena posicional como entrada

Ejemplo 7: Capturar datos en un objeto DataSet

Ejemplo 8: Obtener conjuntos de columnas específicos

Ejemplo 9: Obtener control total de una conexión

Ejemplo 10: Ejecutar un procedimiento almacenado y capturar los errores de SQL

Ejemplo 11: Conexión a Azure SQL Database (o Instancia administrada) mediante un token de acceso

Ejemplo 12: Conexión a Azure SQL Database (o Instancia administrada) mediante una entidad de servicio

Ejemplo 13: Conexión a Azure SQL Database (o Instancia administrada) mediante una identidad administrada

Ejemplo 14: Conexión a un grupo de disponibilidad configurado para Read-Only Enrutamiento mediante -ApplicationIntent

Ejemplo 15: Capturar estadísticas de conexión mediante el parámetro -StatisticsVariable

Ejemplo 16: Ejecute una consulta que descifre los datos recuperados de las columnas cifradas mediante Always Encrypted. Supongamos que la clave maestra de columna se almacena en un almacén de claves en Azure Key Vault.

Parámetros

-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

-Query

-QueryTimeout

-ServerInstance

-SeverityLevel

-StatisticsVariable

-SuppressProviderContextWarning

-TrustServerCertificate

-Username

-Variable

Entradas

Salidas

Vínculos relacionados

Recursos adicionales