Comparteix a través de

sqlcmd, utilidad

  • Article

Se aplica a: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

La utilidad sqlcmd permite escribir instrucciones Transact-SQL, procedimientos del sistema y archivos de script a través de varios modos:

  • En el símbolo del sistema.
  • En el modo SQLCMD del Editor de consultas.
  • En un archivo de script de Windows.
  • En un paso de trabajo del sistema operativo (cmd.exe) de un trabajo del Agente SQL Server.

Nota:

Aunque Microsoft Entra ID es el nuevo nombre de Azure Active Directory (Azure AD), para evitar interrumpir los entornos existentes, Azure AD sigue estando en algunos elementos codificados de forma rígida como campos de interfaz de usuario, proveedores de conexiones, códigos de error y cmdlets. En este artículo, los dos nombres son intercambiables.

Información sobre qué versión está instalada

Hay dos versiones de sqlcmd:

  • Sqlcmd basado en go-mssqldb, a veces con estilo go-sqlcmd. Esta versión es una herramienta independiente que puede descargar independientemente de SQL Server.

  • Sqlcmd basado en ODBC, disponible con SQL Server o las utilidades de la línea de comandos de Microsoft, y parte del paquete mssql-tools en Linux.

Para determinar la versión que ha instalado, ejecute la siguiente instrucción en la línea de comandos:

sqlcmd "-?"

sqlcmd "-?"

sqlcmd -?

Si usa la nueva versión de sqlcmd (Go), la salida es similar al ejemplo siguiente:

Version: 1.3.1

Comprobación de la versión

Puede usar sqlcmd --version para determinar qué versión está instalada. Debe tener instalada al menos la versión 1.0.0.

Importante

La instalación de sqlcmd (Go) a través de un administrador de paquetes reemplazará sqlcmd (ODBC) por sqlcmd (Go) en la ruta de acceso del entorno. Todas las sesiones de línea de comandos actuales deberán cerrarse y volver a abrirse para que esto surta efecto. sqlcmd (ODBC) no se quitará y se puede usar especificando la ruta de acceso completa al archivo ejecutable. También puede actualizar la variable PATH para indicar qué tendrá prioridad. Para ello, en Windows 11, abra Configuración del sistema y vaya a Acerca de> Configuración avanzada del sistema. Cuando se abra Propiedades del sistema, seleccione el botón Variables de entorno. En la mitad inferior, en Variables del sistema, seleccione Ruta de acceso y, a continuación, seleccione Editar. Si la ubicación sqlcmd (Go) se guarda (C:\Program Files\sqlcmd es el valor predeterminado), aparece antes de C:\Program Files\Microsoft SQL Server\<version>\Tools\Binn y, a continuación, se usa sqlcmd (Go). Puede revertir el orden para volver a convertir sqlcmd (ODBC) en el valor predeterminado.

Descarga e instalación de sqlcmd

sqlcmd (Go) se puede instalar de forma multiplataforma en Microsoft Windows, macOS y Linux. Es posible que las versiones más recientes de la versión 1.6 no estén disponibles en todos los administradores de paquetes. Todavía no hay ninguna fecha estimada para su disponibilidad.

winget (CLI de Administrador de paquetes de Windows)

  1. Instale el cliente del Administrador de paquetes de Windows si aún no lo tiene instalado.

  2. Ejecute el comando siguiente para instalar sqlcmd (Go).

    winget install sqlcmd

Chocolatey

  1. Instale Chocolatey, si aún no la tiene.

  2. Ejecute el comando siguiente para instalar sqlcmd (Go).

    choco install sqlcmd

Descarga directa

  1. Descargue el recurso correspondiente -windows-amd64.zip o -windows-arm.zip de la versión más reciente de sqlcmd (Go) desde el repositorio de código de GitHub.

  2. Extraiga el archivo sqlcmd.exe de la carpeta comprimida descargada.

Preinstalado

Azure Cloud Shell

Puede probar la utilidad sqlcmd desde Azure Cloud Shell, ya que está preinstalada de forma predeterminada:

Azure Data Studio

Para ejecutar instrucciones SQLCMD en Azure Data Studio, seleccione Habilitar SQLCMD desde la barra de herramientas del editor.

SQL Server Management Studio (SSMS)

Para ejecutar instrucciones SQLCMD en SQL Server Management Studio (SSMS), seleccione el modo SQLCMD en el desplegable del menú de consultas situado en la navegación superior.

SSMS usa SqlClient de Microsoft .NET Framework para la ejecución en modo normal y SQLCMD en el Editor de consultas. Cuando sqlcmd se ejecuta desde la línea de comandos, sqlcmd usa el controlador ODBC. Dado que se pueden aplicar diferentes opciones predeterminadas, podría obtener un comportamiento diferente al ejecutar la misma consulta en el modo SQLCMD de SSMS y en la utilidad sqlcmd.

Sintaxis

Usage:
  sqlcmd [flags]
  sqlcmd [command]

Examples:
# Install/Create, Query, Uninstall SQL Server
  sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
  sqlcmd open ads
  sqlcmd query "SELECT @@version"
  sqlcmd delete
# View configuration information and connection strings
  sqlcmd config view
  sqlcmd config cs

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Modify sqlconfig files using subcommands like "sqlcmd config use-context mssql"
  create      Install/Create SQL Server, Azure SQL, and Tools
  delete      Uninstall/Delete the current context
  help        Help about any command
  open        Open tools (e.g ADS) for current context
  query       Run a query against the current context
  start       Start current context
  stop        Stop current context

Flags:
  -?, --?                  help for backwards compatibility flags (-S, -U, -E etc.)
  -h, --help               help for sqlcmd
      --sqlconfig string   configuration file (default "/Users/<currentUser>/.sqlcmd/sqlconfig")
      --verbosity int      log level, error=0, warn=1, info=2, debug=3, trace=4 (default 2)
      --version            print version of sqlcmd

Use "sqlcmd [command] --help" for more information about a command.

Para obtener información más detallada sobre la sintaxis y el uso de sqlcmd, consulte: Sintaxis de sqlcmd de ODBC.

Cambios importantes de sqlcmd (ODBC)

Se han cambiado varios modificadores y comportamientos de la utilidad sqlcmd (Go). Para obtener la lista más actualizada de las marcas que faltan para la compatibilidad con versiones anteriores, visite la explicación de GitHub Priorización de la implementación de marcas back-compat.

  • En versiones anteriores de sqlcmd (Go), el modificador -P se quitó temporalmente y las contraseñas para la autenticación de SQL Server solo se podían proporcionar a través de estos mecanismos:

    • La variable de entorno SQLCMDPASSWORD.
    • El comando :CONNECT
    • Cuando se le solicite, el usuario podría escribir la contraseña para completar una conexión

  • -rrequiere un argumento 0 o 1

  • Se ha quitado el modificador -R.

  • Se ha quitado el modificador -I. Para deshabilitar el comportamiento del identificador entre comillas, agregue SET QUOTED IDENTIFIER OFF a los scripts.

  • -N ahora toma un valor de cadena que puede ser true, false o disable para especificar la opción de cifrado. (default es lo mismo que omitir el parámetro).

    • Si no se proporcionan -N ni -C, sqlcmd negociará la autenticación con el servidor sin validar el certificado de servidor.
    • Si se proporciona -N pero -C no, sqlcmd requerirá la validación del certificado de servidor. Un valor false para el cifrado podría seguir provocando el cifrado del paquete de inicio de sesión.
    • Si se proporcionan -N y -C, sqlcmd usa sus valores para la negociación de cifrado.
    • Encontrará más información sobre la negociación de cifrado de cliente/servidor en MS-TDS PRELOGIN.

  • -u El archivo de salida Unicode generado tendrá escrita la marca de orden de bytes (BOM) UTF16 Little-Endian.

  • Algunos comportamientos que se han conservado para mantener la compatibilidad con OSQL pueden cambiarse, como la alineación de encabezados de columna para algunos tipos de datos.

  • Todos los comandos deben caber en una línea, incluso EXIT. El modo interactivo no buscará paréntesis ni comillas abiertas para los comandos y solicitará líneas sucesivas. Este comportamiento es diferente a la versión de ODBC, lo que permite que la consulta que ejecute EXIT(query) abarque varias líneas.

Las conexiones de sqlcmd (Go) se limitan a las conexiones TCP. Las canalizaciones con nombre no se admiten en este momento en el controlador go-mssqldb.

Mejoras

  • :Connect ahora tiene un parámetro opcional -G para seleccionar uno de los métodos de autenticación para Azure SQL Database: SqlAuthentication, ActiveDirectoryDefault, ActiveDirectoryIntegrated, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity y ActiveDirectoryPassword. Para más información, consulte Autenticación de Microsoft Entra. Si no se proporciona -G, se usa la seguridad integrada o la autenticación SQL Server, en función de la presencia de un parámetro de nombre de usuario -U.

  • El nuevo parámetro de línea de comandos --driver-logging-level le permite ver seguimientos desde el controlador go-mssqldb. Use 64 para ver todos los seguimientos.

  • sqlcmd ahora puede imprimir resultados usando un formato vertical. Use el nuevo modificador de línea de comandos -F vertical para establecerlo. La variable de scripting SQLCMDFORMAT también la controla.

Opciones de línea de comandos

-A

Inicia sesión en SQL Server con una conexión de administrador dedicada (DAC). Este tipo de conexión se utiliza para solucionar problemas de un servidor. Esta conexión solo funciona con equipos servidores que admitan DAC. Si DAC no está disponible, sqlcmd genera un mensaje de error y, después, se cierra. Para obtener más información sobre DAC, vea Conexión de diagnóstico para administradores de bases de datos. La opción -A no se admite con la opción -G. Al conectarse a Azure SQL Database mediante -A, debe ser administrador en el servidor SQL lógico. La DAC no está disponible para un administrador de Microsoft Entra.

C-

Esta opción lo usa el cliente para configurarlo de forma que confíe implícitamente en el certificado de servidor sin validación. Esta opción es equivalente a la opción de ADO.NET TRUSTSERVERCERTIFICATE = true.

Para la utilidad sqlcmd (Go), también se aplican las condiciones siguientes:

  • Si no se proporcionan -N ni -C, sqlcmd negociará la autenticación con el servidor sin validar el certificado de servidor.
  • Si se proporciona -N pero -C no, sqlcmd requerirá la validación del certificado de servidor. Un valor false para el cifrado podría seguir provocando el cifrado del paquete de inicio de sesión.
  • Si se proporcionan -N y -C, sqlcmd usa sus valores para la negociación de cifrado.

-d db_name

Emite una instrucción USE <db_name> cuando se inicia sqlcmd. Esta opción establece la variable de scripting de sqlcmdSQLCMDDBNAME. Este parámetro especifica la base de datos inicial. El valor predeterminado es la propiedad de base de datos predeterminada del inicio de sesión. Si la base de datos no existe, se genera un mensaje de error y sqlcmd se cierra.

-d

Interpreta el nombre de servidor proporcionado a -S como un DSN en lugar de un nombre de host. Para más información, consulte la sección Compatibilidad con DSN en sqlcmd y bcp de Conexión con sqlcmd.

Nota:

La opción -D solo está disponible en clientes de Linux y macOS. En clientes de Windows, antes hacía referencia a una opción que ahora es obsoleta, se ha quitado y se ha omitido.

-l login_timeout

Especifica el número de segundos que tienen que transcurrir antes de que un inicio de sesión de sqlcmd en el controlador ODBC agote el tiempo de espera cuando se trate de conectar a un servidor. Esta opción establece la variable de scripting de sqlcmdSQLCMDLOGINTIMEOUT. El tiempo de espera predeterminado de inicio de sesión de sqlcmd es de ocho segundos. Cuando se usa la opción -G para conectarse a la base de datos de Azure o a Azure Synapse Analytics y autenticarse con Microsoft Entra ID, se recomienda establecer un valor de tiempo de expiración de al menos 30 segundos. El período de tiempo de espera de inicio de sesión debe ser un número comprendido entre 0 y 65534. Si el valor proporcionado no es numérico o no está dentro de ese rango, sqlcmd genera un mensaje de error. El valor 0 especifica que el tiempo de espera es infinito.

-E

Usa una conexión de confianza en lugar de usar un nombre de usuario y una contraseña para iniciar sesión en SQL Server. Si no se especifica -E , sqlcmd usa de forma predeterminada la opción de conexión de confianza.

La opción -E omite la posible configuración de la variable de entorno de nombre de usuario y contraseña, como SQLCMDPASSWORD. Si se usa la opción -E junto con la opción -U o laopción -P, se genera un mensaje de error.

-g

Establece el valor de cifrado de columnas en Enabled. Para obtener más información, vea Always Encrypted. Solo se admiten claves maestras almacenadas en el almacén de certificados de Windows. La opción -g requiere al menos sqlcmd versión 13.1. Para determinar su versión, ejecute sqlcmd -?.

-G

El cliente usa esta opción al conectarse a Azure SQL Database o a Azure Synapse Analytics para especificar que el usuario se autentica mediante la autenticación de Microsoft Entra. Esta opción establece la variable de scripting de sqlcmdSQLCMDUSEAAD = true. La opción -G requiere al menos sqlcmd versión 13.1. Para determinar su versión, ejecute sqlcmd -?. Para más información, vea Conexión a SQL Database o a Azure Synapse Analytics mediante la autenticación de Microsoft Entra. La opción -A no se admite con la opción -G.

La opción -G solo se aplica a Azure SQL Database y a Azure Synapse Analytics.

La autenticación interactiva de Microsoft Entra no se admite actualmente ni en Linux ni en macOS. La autenticación integrada de Microsoft Entra requiere la versión 17.6.1 o superior de Microsoft ODBC Driver 17 para SQL Server y un entorno de Kerberos configurado correctamente.

Para más información sobre la autenticación de Microsoft Entra, vea Autenticación de Microsoft Entra en sqlcmd.

-H nombre_estaciónDeTrabajo

Un nombre de estación de trabajo. Esta opción establece la variable de scripting de sqlcmdSQLCMDWORKSTATION. El nombre de la estación de trabajo se muestra en la columna hostname de la vista de catálogo sys.sysprocesses y se puede devolver mediante el procedimiento almacenado sp_who. Si no se especifica esta opción, el nombre actual del equipo es el valor predeterminado. Este nombre se puede usar para identificar diferentes sesiones de sqlcmd .

-j

Imprime mensajes de error sin formato en la pantalla.

-K intención_aplicación

Declara el tipo de carga de trabajo de la aplicación al conectarse a un servidor. El único valor admitido actualmente es ReadOnly. Si no se especifica -K, la utilidad sqlcmd no admitirá la conectividad con una réplica secundaria en un grupo de disponibilidad. Para más información, consulte Secundarias activas: réplicas secundarias legibles (grupos de disponibilidad AlwaysOn).

-M conmutaciónPorError_múltiplesSubredes

Especifique siempre -M al conectarse a una escucha de un grupo de disponibilidad de SQL Server o a una instancia de clúster de conmutación por error de SQL Server. -M proporciona una detección más rápida del servidor activo (actualmente) y una conexión al mismo. Si no se especifica -M, -M se desactiva. Para más información sobre Agentes de escucha, conectividad de cliente y conmutación por error de una aplicación, Creación y configuración de grupos de disponibilidad (SQL Server), Clústeres de conmutación por error y grupos de disponibilidad AlwaysOn (SQL Server) y Secundarias activas: réplicas secundarias legibles (grupos de disponibilidad AlwaysOn).

-n

Este modificador lo usa el cliente para solicitar una conexión cifrada.

Para la utilidad sqlcmd (Go), -N ahora toma un valor de cadena que puede ser true, false o disable para especificar la opción de cifrado. (default es lo mismo que omitir el parámetro):

  • Si no se proporcionan -N ni -C, sqlcmd negociará la autenticación con el servidor sin validar el certificado de servidor.
  • Si se proporciona -N pero -C no, sqlcmd requerirá la validación del certificado de servidor. Un valor false para el cifrado podría seguir provocando el cifrado del paquete de inicio de sesión.
  • Si se proporcionan -N y -C, sqlcmd usa sus valores para la negociación de cifrado.

-P password

Contraseña especificada por el usuario. En las contraseñas se distingue entre mayúsculas y minúsculas. Si se usa la opción -U y no la opción -P y, además, no se ha establecido la variable de entorno SQLCMDPASSWORD, sqlcmd solicita al usuario una contraseña. No se recomienda usar la contraseña nula, pero puede especificarla usando un par de comillas dobles contiguas en el valor del parámetro ("").

Importante

El uso de -P debe considerarse inseguro. No dé la contraseña en la línea de comandos. Como alternativa, use la variable de entorno SQLCMDPASSWORD o escriba la contraseña de forma interactiva omitiendo la opción -P.

Se recomienda usara una contraseña segura.

El mensaje de contraseña se muestra en la consola de la siguiente manera: Password:

La entrada del usuario queda oculta. Esto significa que no se muestra nada y que el cursor permanece en su posición.

La variable de entorno SQLCMDPASSWORD permite establecer una contraseña predeterminada para la sesión actual. Por lo tanto, las contraseñas no tienen que estar codificadas de forma rígida en los archivos por lotes. En el siguiente ejemplo primero se establece la variable SQLCMDPASSWORD en el símbolo del sistema y, después, se obtiene acceso a la utilidad sqlcmd.

En el símbolo del sistema, escriba:

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

Si la combinación de nombre de usuario y contraseña no es correcta, se genera un mensaje de error.

Nota:

La variable de entorno OSQLPASSWORD se ha conservado por motivos de compatibilidad. La variable de entorno SQLCMDPASSWORD tiene prioridad sobre la variable de entorno OSQLPASSWORD. Esto significa que sqlcmd y osql se pueden usar una junto a la otra sin interferencias. Los scripts antiguos seguirán funcionando.

Si se usa la opción -P junto con la opción -E, se genera un mensaje de error.

Si la opción -P va seguida de más de un argumento, se genera un mensaje de error y el programa se cierra.

Una contraseña que contiene caracteres especiales puede generar un mensaje de error. Debe escapar caracteres especiales al usar -P o usar la variable de entorno SQLCMDPASSWORD en su lugar.

-S [protocolo:]servidor[\nombre_instancia][,puerto]

Especifica la instancia de SQL Server a la que hay que conectarse. Establece la variable de scripting de sqlcmdSQLCMDSERVER.

Especifique nombre_de_servidor para conectar con la instancia predeterminada de SQL Server en ese equipo servidor. Especifique nombre_de_servidor[\nombre_instancia] para conectar con una instancia con nombre de SQL Server en ese equipo servidor. Si no se especifica ningún equipo servidor, sqlcmd se conecta a la instancia predeterminada de SQL Server en el equipo local. Esta opción es necesaria si sqlcmd se ejecuta desde un equipo remoto conectado a la red.

protocolo puede ser tcp (TCP/IP), lpc (memoria compartida) o np (canalizaciones con nombre).

Si no especifica nombre_de_servidor[\nombre_de_instancia] al iniciar sqlcmd, SQL Server comprueba si existe la variable de entorno SQLCMDSERVER y la usa.

Nota:

La variable de entorno OSQLSERVER se ha conservado por motivos de compatibilidad. La variable de entorno SQLCMDSERVER tiene prioridad sobre la variable de entorno OSQLSERVER. Esto significa que sqlcmd y osql se pueden usar una junto a la otra sin interferencias. Los scripts antiguos seguirán funcionando.

-U login_id

Es el nombre de inicio de sesión o el nombre de usuario de base de datos independiente. Debe proporcionar la opción de nombre de base de datos para los usuarios de la base de datos independiente (-d).

Nota:

La variable de entorno OSQLUSER se ha conservado por motivos de compatibilidad. La variable de entorno SQLCMDUSER tiene prioridad sobre la variable de entorno OSQLUSER. Esto significa que sqlcmd y osql se pueden usar una junto a la otra sin interferencias. Los scripts antiguos seguirán funcionando.

Si no se especifica la opción -U o la opción -P, sqlcmd intenta conectarse mediante el modo de autenticación de Microsoft Windows. La autenticación se basa en la cuenta de Windows del usuario que está ejecutando sqlcmd.

Si se usa la opción -U junto con la opción -E (descrita más adelante en este artículo), se genera un mensaje de error. Si la opción -U va seguida de más de un argumento, se genera un mensaje de error y el programa se cierra.

-z nueva_contraseña

Cambie la contraseña:

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

-Z nueva_contraseña

Cambie la contraseña y salga:

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

Opciones de entrada o salida

-f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]

Especifica las páginas de códigos de entrada y de salida. El número de página de códigos es un valor numérico que especifica una página de códigos instalada en Windows.

Reglas de conversión de páginas de códigos:

  • Si no se especifica ninguna página de códigos, sqlcmd usa la página de códigos actual para los archivos de entrada y salida, a menos que el archivo de entrada sea un archivo Unicode, en cuyo caso no es necesaria la conversión.

  • sqlcmd reconoce automáticamente los archivos de entrada Unicode "big endian" y "little endian". Si se ha especificado la opción -u, la salida siempre será Unicode "little endian".

  • Si no se especifica ningún archivo de salida, la página de códigos de salida es la página de códigos de la consola. Este enfoque permite que la salida se muestre correctamente en la consola.

  • Si hay varios archivos de entrada, se considera que pertenecen a la misma página de códigos. Los archivos de entrada Unicode y no Unicode pueden ser mixtos.

Escriba chcp en el símbolo del sistema para comprobar la página de códigos de cmd.exe.

-i archivo_entrada[,archivo_entrada2...]

Identifica el archivo que contiene un lote de instrucciones Transact-SQL o procedimientos almacenados. Se pueden especificar varios archivos que se leen y se procesan en orden. No use ningún espacio entre los nombres de archivo. sqlcmd comprueba primero si todos los archivos especificados existen. Si uno o más archivos no existen, sqlcmd se cerrará. Las opciones -i y -Q/-q son mutuamente excluyentes.

Ejemplos de rutas de acceso:

-i C:\<filename>
-i \\<Server>\<Share$>\<filename>
-i "C:\Some Folder\<file name>"

Las rutas de acceso a archivos que contengan espacios deben escribirse entre comillas.

Esta opción se puede usar más de una vez:

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

-o output_file

Identifica el archivo que recibe la salida de sqlcmd.

Si se especifica -u , archivo_de_salida se almacena en formato Unicode. Si el nombre de archivo no es válido, se genera un mensaje de error y sqlcmd se cierra. sqlcmd no admite la escritura simultánea de varios procesos de sqlcmd en el mismo archivo. El archivo de salida está dañado o es incorrecto. La opción -f también es relevante para los formatos de archivo. Este archivo se creará si no existe. Se sobrescribirá cualquier archivo con el mismo nombre que pertenezca a una sesión de sqlcmd anterior. El archivo que se especifica aquí no es el archivo stdout. Si se especifica un archivo stdout, este archivo no se usa.

Ejemplos de rutas de acceso:

-o C:< filename>
-o \\<Server>\<Share$>\<filename>
-o "C:\Some Folder\<file name>"

Las rutas de acceso a archivos que contengan espacios deben escribirse entre comillas.

-r[0 | 1]

Redirige la salida del mensaje de error a la pantalla (stderr). Si no especifica ningún parámetro o si especifica 0, solo se redirigirán los mensajes de error con un nivel de gravedad 11 o superior. Si especifica 1, toda salida de mensaje, incluida PRINT, se redirigirá. Esta opción no tiene ningún efecto si usa -o. De forma predeterminada, los mensajes se envían a stdout.

Nota:

Para la utilidad sqlcmd (Go), -r requiere un argumento 0 o 1.

-R

Se aplica solo a: sqlcmd ODBC.

Hace que sqlcmd localice las columnas numéricas, de moneda, fecha y hora recuperadas de SQL Server según la configuración regional del cliente. De forma predeterminada, estas columnas se muestran con la configuración regional del servidor.

-U

Especifica que archivo_de_salida se almacena en formato Unicode, independientemente del formato de archivo_de_entrada.

Nota:

Para la utilidad sqlcmd (Go), el archivo de salida Unicode generado tendrá escrita la marca de orden de bytes (BOM) UTF-16 Little-Endian.

Opciones de ejecución de consultas

-E

Escribe scripts de entrada en el dispositivo de salida estándar (stdout).

-I

Se aplica solo a: sqlcmd ODBC.

Establece la opción de conexión de SET QUOTED_IDENTIFIER en ON. De forma predeterminada, se establece en OFF. Para obtener más información, vea SET QUOTED_IDENTIFIER (Transact-SQL).

Nota:

Para deshabilitar el comportamiento del identificador entre comillas en la utilidad sqlcmd (Go), agregue SET QUOTED IDENTIFIER OFF a los scripts.

-q "cmdline query"

Ejecuta una consulta cuando sqlcmd se inicia, pero no cierra sqlcmd cuando la consulta finaliza. Se pueden ejecutar varias consultas delimitadas por punto y coma. Utilice las comillas alrededor de la consulta, como se muestra en el siguiente ejemplo.

En el símbolo del sistema, escriba:

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Importante

No use el terminador GO en la consulta.

Si se especifica -b junto con esta opción, sqlcmd se cierra en caso de error. -b se describe en algún lugar de este artículo

-Q "cmdline query"

Ejecuta una consulta cuando se inicia sqlcmd e inmediatamente después cierra sqlcmd. Se pueden ejecutar varias consultas delimitadas por punto y coma.

Utilice las comillas alrededor de la consulta, como se muestra en el siguiente ejemplo.

En el símbolo del sistema, escriba:

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Importante

No use el terminador GO en la consulta.

Si se especifica -b junto con esta opción, sqlcmd se cierra en caso de error. -b se describe en algún lugar de este artículo

-t query_timeout

Especifica el número de segundos que tienen que transcurrir antes de que un comando (o la instrucción de Transact-SQL) exceda el tiempo de espera. Esta opción establece la variable de scripting de sqlcmdSQLCMDSTATTIMEOUT. Si no se especifica un valor de query_timeout, el comando no agota el tiempo de espera. El query_timeout debe ser un número entre 1 y 65534. Si el valor proporcionado no es numérico o no está dentro de ese rango, sqlcmd genera un mensaje de error.

Nota:

El tiempo de espera real puede variar unos segundos con respecto al valor de query_timeout especificado.

-v var = valor [ var = valor... ]

Crea una variable de scripting de sqlcmd que puede usarse en un script de sqlcmd. Si el valor contiene espacios en blanco, especifíquelo entre comillas. Se pueden especificar varios valores <var>="<value>". Si hay errores en alguno de los valores especificados, sqlcmd genera un mensaje de error y después se cierra.

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

-X

Hace que sqlcmd omita las variables de scripting. Este parámetro 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>).

Opciones de formato

-h headers

Especifica el número de filas que se van a imprimir entre los encabezados de las columnas. La opción predeterminada es imprimir los encabezados una vez para cada conjunto de resultados de la consulta. Esta opción establece la variable de scripting de sqlcmdSQLCMDHEADERS. Use -1 para especificar que no se impriman los encabezados. Cualquier valor no válido hará que sqlcmd genere un mensaje de error y se cierre.

-k [1 | 2]

Quita todos los caracteres de control, como tabulaciones y nuevos caracteres de línea de la salida. Este parámetro conserva el formato de las columnas cuando se devuelven datos.

  • -k quita los caracteres de control.
  • -k1 reemplaza cada carácter de control por un espacio.
  • -k2 reemplaza los caracteres de control consecutivos por un solo espacio.

-s col_separator

Especifica el carácter separador de columnas. El valor predeterminado es un espacio en blanco. Esta opción establece la variable de scripting de sqlcmdSQLCMDCOLSEP. Para usar caracteres que tienen un significado especial para el sistema operativo, como la y comercial (&) o el punto y coma (;), incluya el carácter entre comillas ("). El separador de columnas puede ser cualquier carácter de 8 bits.

-w ancho_de_pantalla

Especifica el ancho de pantalla para la salida. Esta opción establece la variable de scripting de sqlcmdSQLCMDCOLWIDTH. El ancho de columna debe ser un número mayor que 8 y menor que 65536. Si el ancho de columna especificado no está en ese intervalo, sqlcmd generará un mensaje de error. El ancho predeterminado es 80 caracteres. Cuando la línea de salida supera el ancho de columna especificado, se ajusta a la siguiente línea.

-w

Esta opción quita los espacios finales de una columna. Use esta opción junto con la opción -s cuando prepare datos que se vayan a exportar a otra aplicación. No se puede usar con las opciones -y o -Y.

-y variable_length_type_display_width

Establece la variable de scripting de sqlcmdSQLCMDMAXVARTYPEWIDTH. El valor predeterminado es 256. Limita el número de caracteres que se devuelve para tipos de datos de longitud variable y gran tamaño:

  • ntext
  • nvarchar(max)
  • varbinary(max)
  • xml
  • tipos de datos definidos por el usuario (UDT)
  • text
  • ntext
  • image

Los UDT pueden ser de longitud fija, en función de la implementación. Si esta longitud de un UDT de longitud fija es más corta que anchura_de_visualización, el valor del UDT devuelto no se ve afectado. No obstante, si la longitud es mayor que anchura_de_visualización, la salida queda truncada.

Precaución

Use la opción -y 0 con mucha precaución, ya que puede causar problemas de rendimiento significativos en el servidor y en la red, según el tamaño de los datos devueltos.

-Y fixed_length_type_display_width

Establece la variable de scripting de sqlcmdSQLCMDMAXFIXEDTYPEWIDTH. El valor predeterminado es 0 (ilimitado). Limita el número de caracteres que se devuelve para los siguientes tipos de datos:

  • char(n), donde 1 <= n<= 8000
  • nchar(n), donde 1 <= n<= 4000
  • varchar(n), donde 1 <= n<= 8000
  • nvarchar(n), donde 1 <= n<= 4000
  • varbinary(n), donde 1 <= n<= 4000
  • sql_variant

Opciones de informes de errores

-b

Especifica que sqlcmd se cierre y devuelva un valor de DOS ERRORLEVEL cuando se produce un error. El valor que se devuelve a la variable ERRORLEVEL es 1 cuando el mensaje de error de SQL Server tiene un nivel de gravedad superior a 10; de lo contrario, el valor devuelto es 0. Si se ha establecido la opción -V además de -b, sqlcmd no notifica un error si el nivel de gravedad es inferior a los valores establecidos mediante -V. Los archivos por lotes del símbolo del sistema pueden probar el valor de ERRORLEVEL y controlar el error apropiadamente. sqlcmd no notifica los mensajes de error con un nivel de gravedad de 10 (mensajes informativos).

Si el script de sqlcmd contiene un comentario incorrecto, un error de sintaxis o carece de una variable de scripting, el valor de ERRORLEVEL devuelto es 1.

-m error_level

Controla qué mensajes de error se envían a stdout. Se envían los mensajes que tienen un nivel de gravedad mayor o igual que este nivel. Cuando este valor se establece en -1, se envían todos los mensajes, incluidos los informativos. No se permiten espacios entre -m y -1. Por ejemplo, -m-1 es válido, pero -m -1 no lo es.

Esta opción también establece la variable de scripting de sqlcmdSQLCMDERRORLEVEL. El valor predeterminado de esta variable es 0.

-V error_severity_level

Controla el nivel de gravedad que se usa para establecer la variable ERRORLEVEL. Los mensajes de error que tienen niveles de gravedad mayores o iguales que este valor establecen ERRORLEVEL. Los valores menores que 0 se notifican como 0. Los archivos CMD y por lotes se pueden usar para probar el valor de la variable ERRORLEVEL.

Otras opciones

-a packet_size

Solicita un paquete de un tamaño diferente. Esta opción establece la variable de scripting de sqlcmdSQLCMDPACKETSIZE. tamaño_paquete debe ser un valor entre 512 y 32767. El valor predeterminado es 4096. Un tamaño de paquete mayor puede mejorar el rendimiento de la ejecución de scripts que comprenden gran cantidad de instrucciones de Transact-SQL entre los comandos GO. Puede solicitar un tamaño de paquete mayor. No obstante, si se deniega la solicitud, sqlcmd usa el valor predeterminado de servidor para el tamaño de paquete.

-c batch_terminator

Especifica el terminador del lote. De forma predeterminada, los comandos se terminan y se envían a SQL Server escribiendo la palabra GO en una línea aparte. Cuando restablezca el terminador del lote, no use palabras claves reservadas de Transact-SQL ni caracteres que tengan un significado especial para el sistema operativo, incluso aunque vayan precedidos de una barra diagonal invertida.

-L[c]

Enumera los equipos servidores configurados localmente y los nombres de los equipos servidores que difunden en la red. Este parámetro no se puede usar en combinación con otros parámetros. El número máximo de equipos de servidor que se puede enumerar es 3000. Si la lista de servidor se trunca debido al tamaño del búfer, aparece un mensaje de advertencia.

Nota

Debido a la naturaleza de las difusiones en las redes, sqlcmd podría no recibir una respuesta de todos los servidores a tiempo. Por lo tanto, la lista de servidores devuelta puede variar en cada invocación de esta opción.

Si se especifica el parámetro opcional c, la salida aparece sin la línea de encabezado Servers: y cada línea de servidor se muestra sin espacios iniciales. Esta presentación se conoce como salida limpia. La salida limpia mejora el rendimiento del procesamiento de los lenguajes de scripting.

-p[1]

Imprime estadísticas de rendimiento para cada conjunto de resultados. La siguiente pantalla muestra un ejemplo del formato para las estadísticas de rendimiento:

Network packet size (bytes): n

x xact[s]:

Clock Time (ms.): total       t1  avg       t2 (t3 xacts per sec.)

Donde:

  • x = número de transacciones que procesa SQL Server.
  • t1 indica el tiempo total de todas las transacciones.
  • t2 = tiempo medio de una única transacción.
  • t3 = número medio de transacciones por segundo.

Todos los tiempos se indican en milisegundos.

Si se especifica el parámetro opcional 1 , el formato de salida de las estadísticas es el separado por dos puntos, que se puede importar fácilmente en una hoja de cálculo o se puede procesar en un script.

Si el parámetro opcional tiene cualquier valor distinto de 1, se genera un error y sqlcmd se cierra.

-X[1]

Deshabilita los comandos que pueden poner en peligro la seguridad del sistema cuando se ejecuta sqlcmd desde un archivo por lotes. Los comandos deshabilitados se siguen reconociendo; sqlcmd emite un mensaje de advertencia y sigue ejecutándose. Si se especifica el parámetro opcional 1 , sqlcmd genera un mensaje de error y después se cierra. Los siguientes comandos se deshabilitan cuando se usa la opción -X:

  • ED
  • !! comando

Si se especifica la opción -X, se evita que se pasen variables de entorno a sqlcmd. También impide que el script de inicio especificada mediante la variable de scripting SQLCMDINI se ejecute. Para más información sobre variables de scripting sqlcmd, consulte sqlcmd - Usar con variables de script.

-?

Muestra la versión de sqlcmd y un resumen de la sintaxis de las opciones de sqlcmd .

Nota:

En macOS, ejecute sqlcmd '-?' (con comillas) en su lugar.

Comentarios

Las opciones no tienen que utilizarse forzosamente en el orden mostrado en la sección de sintaxis.

Cuando se devuelven varios resultados, sqlcmd imprime una línea en blanco entre cada conjunto de resultados de un lote. Además, el mensaje <x> rows affected no aparece cuando no se aplica a la instrucción ejecutada.

Para usar sqlcmd de forma interactiva, escriba sqlcmd en el símbolo del sistema con una o varias de las opciones descritas anteriormente en este artículo. Para más información, vea Usar la utilidad sqlcmd.

Nota

Las opciones -l, -Q, -Z o -i hacen que sqlcmd se cierre después de la ejecución.

La longitud total de la línea de comandos de sqlcmd en el entorno de comandos (por ejemplo cmd.exe o bash), incluidos todos los argumentos y las variables expandidas, es la que determina el sistema operativo subyacente.

Precedencia de variables (menor a mayor)

  1. Variables de entorno de nivel de sistema.
  2. Variables de entorno de nivel de usuario.
  3. El shell de comandos (SET X=Y) se establece en el símbolo del sistema antes de ejecutar sqlcmd.
  4. sqlcmd -v X=Y
  5. :Setvar X Y

Nota

Para ver las variables de entorno, en el Panel de control, abra Sistema y seleccione la pestaña Opciones avanzadas.

Variables de scripting sqlcmd

Variable Opción relacionada L/E Valor predeterminado
SQLCMDUSER -U R ""
SQLCMDPASSWORD -P -- ""
SQLCMDSERVER -S R "DefaultLocalInstance"
SQLCMDWORKSTATION -H R "ComputerName"
SQLCMDDBNAME -d R ""
SQLCMDLOGINTIMEOUT -l L/E "8" (segundos)
SQLCMDSTATTIMEOUT -T L/E "0" = esperar indefinidamente
SQLCMDHEADERS -H L/E "0"
SQLCMDCOLSEP -S L/E " "
SQLCMDCOLWIDTH -w L/E "0"
SQLCMDPACKETSIZE -a R "4096"
SQLCMDERRORLEVEL -M L/E 0
SQLCMDMAXVARTYPEWIDTH -y L/E "256"
SQLCMDMAXFIXEDTYPEWIDTH -y L/E "0" = ilimitado
SQLCMDEDITOR L/E "edit.com"
SQLCMDINI R ""
SQLCMDUSEAAD -G L/E ""

SQLCMDUSER, SQLCMDPASSWORDy SQLCMDSERVER se establecen cuando :Connect se usa.

R indica que el valor solo puede establecerse una vez durante la inicialización del programa.

R/W indica que el valor puede modificarse mediante el comando :setvar y que los comandos siguientes se ven influidos por el nuevo valor.

sqlcmd, comandos

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

GO [ count ]

:List

[:]RESET

:Error

[:]ED

:Out

[:]!!

:Perftrace

[:]QUIT

:Connect

[:]EXIT

:On Error

:r

:Help

:ServerList

:XML [ ON | OFF ]

:Setvar

:Listvar

Tenga en cuenta lo siguiente cuando use comandos de sqlcmd :

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

    Importante

    Para mantener la compatibilidad con los scripts de osql existentes, algunos de los comandos se reconocerán 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.

Edición de comandos

[:]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 memoria caché de instrucciones.

variables

:Setvar <var> [ "value" ]

Define 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 mediante una opción de línea de comandos. Por ejemplo, la opción -l establece la variable de SQLCMDLOGINTIMEOUT sqlcmd.

  • Explícitamente mediante el comando :Setvar .

  • Al definir una variable de entorno antes de ejecutar sqlcmd.

Nota

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.

Nota

Solo se mostrarán las variables de scripting establecidas mediante sqlcmdy las variables establecidas con el comando :Setvar .

Comandos de salida

:Error <nombreDeArchivo> | STDERR | STDOUT

Redirija todos los resultados de error al archivo especificado por nombreDeArchivo 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 a causa de los permisos u otros motivos, la salida no se cambia y se envía al último destino especificado o al predeterminado.

  • STDERR

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

  • STDOUT

    Cambia la salida del error al flujo stdout . Si se ha redirigido, 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

:On Error [ exit | ignore ]

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, se cierra sin ningún valor devuelto.

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

Aquí se muestra una lista de formatos de 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 Descripción
-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 <filename>

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 de lotes GO.

Nota:

El recuento de líneas que se muestra en el modo interactivo aumentará en uno por cada comando :r que se encuentre. El comando :r aparecerá en la salida del comando de lista.

: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 Comportamiento
0 Espera indefinidamente
n>0 Espera durante n segundos

La variable de scripting SQLCMDSERVER reflejará 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 avisa a los usuarios si se han establecido 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

Nota

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

  • 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 algún espacio en blanco 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, es un espacio en blanco. 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 ha expandido 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.

Nota

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. Con :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 ha emitido antes de ejecutar una instrucción Transact-SQL que genera flujos XML, la salida será confusa. Cuando se ha emitido el comando :XML ON, no se pueden ejecutar instrucciones Transact-SQL que den como resultado conjuntos de filas normales.

Nota:

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

Prácticas recomendadas para sqlcmd

Use las siguientes prácticas para maximizar la seguridad y la eficacia.

  • Use seguridad integrada.

  • Use -X[1] en los entornos automatizados.

  • Proteja los archivos de entrada y salida mediante los permisos del sistema de archivos adecuados.

  • Para aumentar el rendimiento, haga tanto como pueda en una sola sesión de sqlcmd en vez de emplear varias.

  • Establezca valores de tiempo de espera para la ejecución de lotes y consultas superiores a los que prevea para la ejecución de cada lote o consulta.

Use los procedimientos siguientes para ayudar a maximizar la exactitud:

  • Use -V16 para registrar los mensajes con una gravedad de nivel 16. Los mensajes de gravedad 16 indican errores generales que el usuario puede corregir.

  • Una vez finalizado el proceso, compruebe el código de salida y la variable DOS ERRORLEVEL. sqlcmd devuelve normalmente 0; de lo contrario, establecerá el valor de ERRORLEVEL configurado en -V. En otras palabras, no cabe esperar que ERRORLEVEL tenga el mismo valor que el número de error que se ha comunicado desde SQL Server. El número de error es un valor específico de SQL Server correspondiente a la función del sistema @@ERROR. ERRORLEVEL es un valor específico de sqlcmd que indica por qué sqlcmd ha finalizado y la especificación del argumento de la línea de comandos -b influye en su valor.

El uso de -V16 en combinación con la comprobación del código de salida y DOS ERRORLEVEL puede ayudar a detectar errores en entornos automatizados, especialmente en las pruebas de calidad antes de una versión de producción.

Contenido relacionado