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 acepta instrucciones Transact-SQL, procedimientos del sistema y archivos de script.

Además de Transact-SQL instrucciones dentro de sqlcmd, use los siguientes comandos:

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

¹ No compatible con Linux o macOS.

Tenga en cuenta los siguientes puntos al usar comandos sqlcmd :

• Todos los comandos sqlcmd , excepto GO, deben comenzar con dos puntos (:).

  Important

  Para mantener la compatibilidad con versiones anteriores de los scripts existentes osql, algunos comandos funcionan sin dos puntos, como se señala mediante [:].

• sqlcmd reconoce comandos 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. No puede seguir un comando con una instrucción Transact-SQL u 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. Use este editor para editar el lote de Transact-SQL actual o el último lote de ejecución. Para editar el último lote de ejecución, escriba el ED comando inmediatamente después de que finalice la ejecución del último lote.

La SQLCMDEDITOR variable de entorno define el editor de texto. 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, escriba el siguiente comando:

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.

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.

Comandos de salida

:Error <nombre de archivo> | STDERR | STDOUT

Redirigir 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, la salida de error va a stderr.

• filename

  Crea y abre un archivo que recibirá la salida. Un archivo existente se trunca en cero bytes. Si el archivo no está disponible debido a permisos u otros motivos, la salida no se cambia y el último destino especificado o predeterminado recibe la salida de error.

• STDERR

  Cambia la salida de error a la secuencia de stderr. Si se redirige la salida, el destino al que se redirige la secuencia recibe la salida de error.

• STDOUT

  Cambia la salida de error a la secuencia de stdout. Si se redirige la salida, el destino al que se redirige la secuencia recibe la salida de error.

:Out <nombreDeArchivo> | STDERR | STDOUT

Crea y redirige todos los resultados de la consulta al archivo especificado por nombre de archivo, a stderro a .stdout De forma predeterminada, la salida va 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 stderro a .stdout De forma predeterminada, la salida del seguimiento de rendimiento va a stdout. Un archivo existente 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 va a realizar cuando se produce un error durante la ejecución por lotes o script.

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

Cuando se usa la ignore opción , sqlcmd omite el error y continúa ejecutando el lote o el script. De forma predeterminada, sqlcmd imprime un mensaje de error.

[:]QUIT

Hace que sqlcmd se cierre.

[:]EXIT [ ( instrucción ) ]

Use el resultado de una SELECT instrucción 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 completo 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() con paréntesis vacíos ejecuta todo antes en el lote y, a continuación, sale sin devolver un valor.

Cuando se especifica una consulta incorrecta, sqlcmd sale sin un valor devuelto.

Aquí tienes una lista de formatos EXIT:

• :EXIT

  No ejecuta el lote y, a continuación, se cierra inmediatamente y no devuelve ningún valor.

• :EXIT( )

  Ejecuta el lote y, a continuación, se cierra y no devuelve ningún valor.

• :EXIT(query)

  Ejecuta el lote que incluye la consulta y, a continuación, se cierra después de devolver los resultados de la consulta.

Si usa RAISERROR dentro de un script sqlcmd y genera un estado de 127, sqlcmd se cierra y devuelve el 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.

SQL Server reserva los valores devueltos de -1 a -99, y sqlcmd define valores devueltos adicionales:

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 de Transact-SQL adicionales y comandos sqlcmd del archivo especificado por nombre de archivo en la memoria caché de instrucciones. sqlcmd lee el nombre de archivo en relación con el directorio de inicio.

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

sqlcmd lee y ejecuta el archivo después de encontrar un terminador por lotes. Puede emitir varios comandos :r. El archivo puede incluir cualquier comando sqlcmd , incluido el terminador por lotes GO.

:ServerList

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

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

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

• Opciones de cifrado (-N[s|m|o]):

  Use esta opción para solicitar una conexión cifrada. Si no incluye -N, -Nm (para mandatory) es el valor predeterminado. Esta opción es un cambio importante de SQL Server 2022 (16.x) y versiones anteriores, donde -No (para optional) es el valor predeterminado.

  Value	Description
  -Ns	Estricto
  -Nm (valor predeterminado)	Mandatory
  -No	Opcional

• Nombre de host en el certificado (-F hostname_in_certificate)

  Especifica un nombre común (CN) o nombre alternativo del sujeto (SAN) diferente y esperado en el certificado del servidor que se va a usar durante la validación del certificado del servidor. Sin esta opción, la validación de certificados garantiza que el Nombre Común (CN) o Nombre Alternativo del Sujeto (SAN) del certificado coincida con el nombre del servidor al que te conectas. Este parámetro se puede rellenar cuando el nombre del servidor no coincide con el CN o SAN, por ejemplo, cuando se usan alias DNS.

• 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 especifica solo user_name (ya sea como una opción o como una variable de entorno), sqlcmd le pedirá que escriba 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 conectarse a la instancia predeterminada de myserver mediante variables de scripting, use la siguiente configuración:

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

[:]!! command

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

:!! dir

:XML [ ENCENDIDO | APAGADO ]

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

:Help

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

Nombres de archivo de sqlcmd

Especifique los archivos de entrada sqlcmd mediante la -i opción o el :r comando . Especifique los archivos de salida mediante la -o opción o los :Errorcomandos , :Outy :Perftrace . Al trabajar con estos archivos, use las instrucciones siguientes:

• Use valores de nombre de archivo independientes para :Error, :Outy :Perftrace. Si usa el mismo nombre de archivo, los comandos podrían mezclar entradas.

• Si invoca un archivo de entrada ubicado en un servidor remoto utilizando sqlcmd desde un equipo local, y el archivo contiene una ruta de acceso de archivo de unidad como :Out c:\OutputFile.txt, sqlcmd crea el archivo de salida 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 cualquier mensaje informativo que envíe el servidor. En el ejemplo siguiente, después de que sqlcmd ejecute las instrucciones Transact-SQL, imprime un mensaje informativo.

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

USE AdventureWorks2025;
GO

Al presionar Entrar, sqlcmd imprime el siguiente mensaje informativo:

Changed database context to 'AdventureWorks2025'.

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 menor que el ancho de columna, sqlcmd rellena la salida con espacios hasta la columna siguiente.

sqlcmd imprime una línea separadora que es una serie de caracteres de guion. La siguiente salida muestra un ejemplo.

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

USE AdventureWorks2025;

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

Al presionar Entrar, sqlcmd devuelve 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, sqlcmd finaliza la salida en 80 caracteres. Puede cambiar este ancho mediante la -w opción o estableciendo la SQLCMDCOLWIDTH variable de scripting.

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.

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 ejecute una instrucción Transact-SQL que genera secuencias XML, la salida se desordena. Una vez emitido el :XML ON comando, no se pueden ejecutar Transact-SQL instrucciones que generan conjuntos de filas normales.

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

Ejemplos que usan 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

• Utilidad sqlcmd
• Comprobación de la versión instalada de la utilidad sqlcmd
• Iniciar la utilidad sqlcmd
• Ejecución de T-SQL desde un archivo de script con sqlcmd
• Uso de sqlcmd