Compartir a través de

Comandos de la utilidad sqlcmd

Aplica a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Analítica (PDW)Base de datos SQL en Microsoft Fabric

La utilidad sqlcmd permite escribir instrucciones Transact-SQL, procedimientos del sistema y archivos de script.

Note

Para averiguar qué variante y versión de sqlcmd está instalada en el sistema, consulte Comprobar la versión instalada de la utilidad sqlcmd. Para obtener información sobre cómo obtener sqlcmd, vea Descargar e instalar la utilidad sqlcmd.

Además de las instrucciones Transact-SQL de sqlcmd, también están disponibles los siguientes comandos:

  • GO [ <count> ]
  • :List
  • [:]RESET
  • :Error
  • [:]ED 1
  • :Out
  • [:]!!
  • :Perftrace
  • [:]QUIT
  • :Connect
  • [:]EXIT
  • :On Error
  • :r
  • :Help
  • :ServerList 1
  • :XML [ ON | OFF ] 1
  • :Setvar
  • :Listvar

1 No compatible con Linux o macOS.

Tenga en cuenta lo siguiente cuando use comandos de sqlcmd :

  • Todos los comandos de sqlcmd , excepto GO, deben ir precedidos de dos puntos (:).

    Important

    Para mantener la compatibilidad con los scripts de osql existentes, algunos de los comandos se reconocen sin los dos puntos, indicado por :.

  • Los comandos desqlcmd se reconocen solo si aparecen al principio de una línea.

  • Los comandos de sqlcmd no distinguen entre mayúsculas y minúsculas.

  • Cada comando debe estar en una línea separada. Un comando no puede ir seguido de una instrucción de Transact-SQL o de otro comando.

  • Los comandos se ejecutan inmediatamente. No se colocan en el búfer de ejecución, como es el caso de las instrucciones Transact-SQL.

Comandos de edición

[:]ED

Inicia el editor de texto. Este editor se puede utilizar para editar el lote actual de Transact-SQL o el último lote ejecutado. Para editar el último lote ejecutado, el comando ED debe escribirse inmediatamente después de que se complete la ejecución del último lote.

El editor de texto se define mediante la variable de entorno SQLCMDEDITOR. El editor predeterminado es Edit. Para cambiar el editor, establezca la variable de entorno SQLCMDEDITOR. Por ejemplo, para establecer el editor en el Bloc de notas de Microsoft, en el símbolo del sistema, escriba:

SET SQLCMDEDITOR=notepad

[:]RESET

Borra la caché de instrucciones.

:List

Imprime el contenido de la caché de sentencias.

Variables

:Setvar <var> [ "value" ]

Define las variables de scripting de sqlcmd. Las variables de scripting tienen el siguiente formato: $(VARNAME).

Los nombres de variables no distinguen entre mayúsculas y minúsculas.

Las variables de scripting pueden establecerse de los siguientes modos:

  • Implícitamente utilizando una opción de línea de comandos. Por ejemplo, la opción -l establece la variable de SQLCMDLOGINTIMEOUTsqlcmd.
  • Explícitamente mediante el comando :Setvar .
  • Definir una variable de entorno antes de ejecutar sqlcmd.

Note

La opción -X impide que las variables de entorno se pasen a sqlcmd.

Si una variable definida mediante :Setvar y una variable de entorno tienen el mismo nombre, la variable definida mediante :Setvar tiene prioridad.

Los nombres de variables no deben contener caracteres de espacio en blanco.

Los nombres de variable no pueden tener el mismo formato que una expresión variable como $(var).

Si el valor de la cadena de la variable de script contiene espacios en blanco, incluya el valor entre comillas. Si un valor para la variable del script no se especifica, la variable de script se elimina.

:Listvar

Muestra una lista de variables de scripting que están establecidas actualmente.

Note

Solo se muestran las variables de scripting establecidas mediante sqlcmd y las variables establecidas con el comando :Setvar.

Comandos de salida

:Error <nombre de archivo> | STDERR | STDOUT

Redirija toda la salida de error al archivo especificado por nombre de archivo, a stderr o a stdout. El comando :Error puede aparecer varias veces en un script. De forma predeterminada, los resultados de error se envían a stderr.

  • filename

    Crea y abre un archivo que recibirá la salida. Si el archivo ya existe, se trunca en cero bytes. Si el archivo no está disponible debido a permisos u otros motivos, la salida no se cambia y se envía al último destino especificado o predeterminado.

  • STDERR

    Cambia la salida de error a la secuencia de stderr. Si se ha redirigido la salida, el destino al cual se redirige el flujo recibe la salida del error.

  • STDOUT

    Cambia la salida de error a la secuencia de stdout. Si se ha redirigido la salida, el destino al cual se redirige el flujo recibe la salida del error.

:Out <nombreDeArchivo> | STDERR | STDOUT

Crea y redirige todos los resultados de consulta al archivo especificado por file name, a stderr o a stdout. De forma predeterminada, la salida se envía a stdout. Si el archivo ya existe, se trunca en cero bytes. El comando :Out puede aparecer varias veces en un script.

:Perftrace <nombreDeArchivo> | STDERR | STDOUT

Crea y redirige toda la información de seguimiento de rendimiento al archivo especificado por nombre_de_archivo, a stderr o a stdout. De forma predeterminada, la salida de seguimiento de rendimiento se envía a stdout. Si el archivo ya existe, se trunca en cero bytes. El comando :Perftrace puede aparecer varias veces en un script.

Comandos de control de ejecución

:Al producirse un error [ salir | ignorar ]

Establece la acción que se llevará a cabo cuando se produzca un error durante la ejecución del script o del lote.

Cuando se usa la opción exit, sqlcmd se cierra con el valor de error correspondiente.

Cuando se usa la opción ignore, sqlcmd pasa por alto el error y continúa con la ejecución del lote o del script. De forma predeterminada, se imprime un mensaje de error.

[:]QUIT

Hace que sqlcmd se cierre.

[:]EXIT [ ( instrucción ) ]

Permite utilizar el resultado de una instrucción SELECT como valor devuelto de sqlcmd. Si es numérica, la primera columna de la última fila del resultado se convierte en un entero de 4 bytes (long). MS-DOS, Linux y macOS pasan el byte inferior al proceso primario o al nivel de errores del sistema operativo. Windows 2000 y versiones posteriores pasan el entero de 4 bytes. La sintaxis es :EXIT(query).

Por ejemplo:

:EXIT(SELECT @@ROWCOUNT)

También se puede incluir el parámetro :EXIT como parte de un archivo por lotes. Por ejemplo, en el símbolo del sistema, escriba:

sqlcmd -Q ":EXIT(SELECT COUNT(*) FROM '%1')"

La utilidad sqlcmd envía todo lo que está entre paréntesis (()) al servidor. Si un procedimiento almacenado del sistema selecciona un conjunto y devuelve un valor, solo se devuelve la selección. La instrucción :EXIT() sin nada entre los paréntesis ejecuta todo lo que precede a estos en el lote y, después, termina sin devolver ningún valor.

Cuando se especifica una consulta incorrecta, sqlcmd se cierra sin devolver ningún valor.

Aquí tienes una lista de formatos EXIT:

  • :EXIT

    No ejecuta el lote y, después, sale de forma inmediata y no devuelve ningún valor.

  • :EXIT( )

    Ejecuta el lote y, a continuación, sale sin devolver ningún valor.

  • :EXIT(query)

    Ejecuta el lote que incluye la consulta y, a continuación, se cierra tras devolver el resultado de la consulta.

Si se usa RAISERROR en un script de sqlcmd y se genera el estado 127, sqlcmd se cierra y devuelve un identificador de mensaje al cliente. Por ejemplo:

RAISERROR(50001, 10, 127)

Este error hará que el script de sqlcmd finalice y devuelva el identificador de mensaje 50001 al cliente.

Los valores devueltos -1 a -99 están reservados para SQL Server; y sqlcmd define los siguientes valores devueltos adicionales:

Valor devuelto Description
-100 Error encontrado antes de seleccionar el valor devuelto.
-101 No se encontró ninguna fila al seleccionar el valor devuelto.
-102 Error de conversión al seleccionar el valor devuelto.

GO [count]

GO marca tanto el final de un lote como la ejecución de cualquier instrucción de Transact-SQL almacenada en caché. El lote se ejecuta varias veces como lotes independientes. No se puede declarar una variable más de una vez en un único lote.

Comandos varios

:r <nombre de archivo>

Analiza instrucciones Transact-SQL y comandos sqlcmd adicionales desde el archivo especificado por filename en la memoria caché de instrucciones. filename se lee de forma relativa al directorio de inicio en el que se ha ejecutado sqlcmd.

Si el archivo contiene instrucciones Transact-SQL que no van seguidas de GO, debe escribir GO en la línea que sigue a :r.

El archivo se leerá y se ejecutará después de que se encuentre un terminador de lote. Puede emitir varios comandos :r. El archivo puede incluir cualquier comando sqlcmd , incluido el terminador por lotes GO.

Note

El recuento de líneas que se muestra en el modo interactivo aumenta en uno por cada comando :r que se encuentra. El comando :r aparece en la salida del comando list.

:ServerList

Enumera los servidores configurados localmente y los nombres de los servidores que difunden en la red.

:Connect nombre_servidor[\nombre_instancia] [-l timeout] [-U nombre_usuario [-P contraseña]]

Conecta con una instancia de SQL Server. También cierra la conexión actual.

Opciones de tiempo de espera:

Value Behavior
0 Espera para siempre
n>0 Espera durante n segundos

La variable de scripting SQLCMDSERVER refleja la conexión activa actual.

Si no se especifica timeout, el valor de la variable SQLCMDLOGINTIMEOUT es el predeterminado.

Si solo se especifica nombre_usuario (como opción o como variable de entorno), se solicitará al usuario que especifique una contraseña. No se solicita a los usuarios si se establecen las variables de entorno SQLCMDUSER o SQLCMDPASSWORD . Si no se proporcionan opciones ni variables de entorno, se iniciará sesión en modo Autenticación de Windows. Por ejemplo, para conectar con una instancia, instance1, de SQL Server, myserver, mediante seguridad integrada, se necesitaría el siguiente comando:

:connect myserver\instance1

Para conectar con la instancia predeterminada de myserver con variables de script, utilizaría la siguiente configuración:

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

[:]!! command

Ejecuta comandos del sistema operativo. Para ejecutar un comando del sistema operativo, inicie una línea con dos signos de exclamación ( !! ) seguidos por el comando del sistema operativo. Por ejemplo:

:!! dir

Note

El comando se ejecuta en el equipo en el que se ejecuta sqlcmd .

:XML [ ON | OFF ]

Para más información, consulte Formato de salida XML y Formato de salida de JSON más adelante en este artículo

:Help

Muestra los comandos de sqlcmd junto con una breve descripción de cada comando.

Nombres de archivo de sqlcmd

Los archivos de entrada desqlcmd se pueden especificar con la opción -i o con el comando :r . Los archivos de entrada se pueden especificar con la opción -o o con los comandos :Error, :Out y :Perftrace. A continuación se incluyen algunas directrices para trabajar con estos archivos:

  • :Error, :Out y :Perftrace deben usar valores de filename separados. Si se usa el mismo nombre de archivo, es posible que las entradas de los comandos se intermezclen.

  • Si un archivo de entrada ubicado en un servidor remoto se llama desde sqlcmd en un equipo local y el archivo contiene una ruta de acceso de archivo del tipo :Out c:\OutputFile.txt, el archivo de salida se creará en el equipo local y no en el servidor remoto.

  • Entre las rutas de archivo válidas se incluyen: C:\<filename>, \\<Server>\<Share$>\<filename> y "C:\Some Folder\<file name>". Si hay un espacio en la ruta de acceso, use comillas.

  • Cada nueva sesión de sqlcmd sobrescribirá los archivos existentes que tengan el mismo nombre.

Mensajes informativos

sqlcmd imprime los mensajes informativos enviados por el servidor. En el siguiente ejemplo, tras ejecutar las instrucciones de Transact-SQL, se imprime un mensaje informativo.

Inicie sqlcmd. En el símbolo del sistema de sqlcmd, escriba lo siguiente:

USE AdventureWorks2022;
GO

Al presionar ENTRAR, se imprime el siguiente mensaje informativo:

Changed database context to 'AdventureWorks2022'.

Formato de salida de consultas de Transact-SQL

sqlcmd primero imprime un encabezado de columna que contiene los nombres de columna especificados en la lista de selección. Los nombres de columna se separan mediante el carácter SQLCMDCOLSEP. De forma predeterminada, este separador de columnas es un espacio. Si el nombre de la columna es más corto que el ancho de la columna, la salida se rellena con espacios hasta la siguiente columna.

Esta línea irá seguida de una línea separadora, que es una serie de caracteres de guión. La siguiente salida muestra un ejemplo.

Inicie sqlcmd. En el símbolo del sistema de sqlcmd, escriba lo siguiente:

USE AdventureWorks2022;

SELECT TOP (2) BusinessEntityID,
               FirstName,
               LastName
FROM Person.Person;
GO

Cuando presione ENTRAR, se devolverá el siguiente conjunto de resultados.

BusinessEntityID FirstName    LastName
---------------- ------------ ----------
285              Syed         Abbas
293              Catherine    Abel
(2 row(s) affected)

Aunque la columna BusinessEntityID tiene solo cuatro caracteres de ancho, se expande para acomodar el nombre de columna más largo. De forma predeterminada, la salida finaliza a los 80 caracteres. Este ancho se puede cambiar mediante la opción -w o al establecer la variable de scripting SQLCMDCOLWIDTH.

formato de salida XML

La salida XML de una cláusula FOR XML se ofrece sin formato en un flujo continuo.

Cuando espere una salida XML, use el siguiente comando: :XML ON.

Note

sqlcmd devuelve mensajes de error en el formato habitual. Tenga en cuenta que los mensajes de error también salen en el flujo de texto XML en formato XML. Al usar :XML ON, sqlcmd no muestra mensajes informativos.

Para desactivar el modo XML, use el siguiente comando: :XML OFF.

El comando GO no debe aparecer antes de que se emita el comando :XML OFF, ya que el comando :XML OFF vuelve a cambiar sqlcmd a la salida orientada a filas.

Los datos XML (de flujo) y los datos del conjunto de filas no se pueden mezclar. Si el comando :XML ON no se emitió antes de que se ejecutara una instrucción Transact-SQL que genera secuencias XML, la salida es ilegible. Una vez emitido el comando :XML ON, no se pueden ejecutar instrucciones Transact-SQL que generen conjuntos de filas normales.

Note

El comando :XML no admite la instrucción SET STATISTICS XML.

Formato de salida JSON

Cuando espere una salida de JSON, use el siguiente comando: :XML ON. De lo contrario, la salida incluye el nombre de columna y el texto JSON, Esta salida no es JSON válido.

Para desactivar el modo XML, use el siguiente comando: :XML OFF.

Para más información, consulte Formato de salida XML en este artículo.

Uso de la autenticación de Microsoft Entra

Ejemplo mediante la autenticación de Microsoft Entra:

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

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

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

Contenido relacionado

  • Last updated on