sqlcmd: uso de la utilidad

  • Artículo

Se aplica a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

La utilidad sqlcmd es una herramienta de línea de comandos para la ejecución ad hoc e interactiva de instrucciones y scripts de Transact-SQL (T-SQL) y para la automatización de tareas de creación de scripts de T-SQL. Para usar sqlcmd de manera interactiva o compilar archivos de script que se ejecutan mediante sqlcmd, los usuarios deben estar familiarizados con T-SQL. La utilidad sqlcmd se usa normalmente de las formas siguientes:

  • Los usuarios escriben instrucciones T-SQL de una manera similar al modo en que trabajan con el símbolo del sistema. Los resultados se muestran en el símbolo del sistema. Para abrir una ventana del símbolo del sistema, escriba cmd en el cuadro de búsqueda de Windows y seleccione Símbolo del sistema para abrirla. En el símbolo del sistema, escriba sqlcmd seguido de una lista de opciones que quiera. Para obtener una lista completa de las opciones admitidas por sqlcmd, vea Utilidad sqlcmd.

  • Los usuarios envían un trabajo sqlcmd especificando la ejecución de una instrucción T-SQL individual o dirigiendo la utilidad hacia un archivo de texto que contiene las instrucciones T-SQL que se van a ejecutar. El resultado se dirige hacia un archivo de texto, aunque también se puede mostrar en el símbolo del sistema.

  • Modo SQLCMD en el Editor de consultas de SQL Server Management Studio (SSMS).

  • Objetos de administración de SQL Server (SMO).

  • Trabajos CmdExec del Agente SQL Server.

Opciones de sqlcmd que se suelen usar

  • La opción del servidor (-S) que identifica la instancia de SQL Server a la que se conecta sqlcmd.

  • Las opciones de autenticación (-E, -U y -P) que especifican las credenciales que usa sqlcmd para conectarse a la instancia de SQL Server.

    Nota:

    La opción -E es la predeterminada, por lo que no es necesario especificarla.

  • Las opciones de entrada (-Q, -q e -i) que identifican la ubicación de la entrada a sqlcmd.

  • La opción de salida (-o) que especifica el archivo en el que se guardará la salida de sqlcmd.

Conectarse a la utilidad sqlcmd

  • Conectarse a la instancia predeterminada mediante la Autenticación de Windows para ejecutar de manera interactiva instrucciones T-SQL:

    sqlcmd -S <ComputerName>

    Nota:

    En el ejemplo anterior, -E no se especifica porque es el valor predeterminado y sqlcmd se conecta a la instancia predeterminada mediante Autenticación de Windows.

  • Conectarse a la instancia con nombre mediante la Autenticación de Windows para ejecutar de manera interactiva instrucciones T-SQL:

    sqlcmd -S <ComputerName>\<InstanceName>

    o

    sqlcmd -S .\<InstanceName>

  • Conectarse a una instancia con nombre mediante la Autenticación de Windows y especificar los archivos de entrada y salida:

    sqlcmd -S <ComputerName>\<InstanceName> -i <MyScript.sql> -o <MyOutput.rpt>

  • Conectarse a la instancia predeterminada del equipo local mediante la Autenticación de Windows, ejecutar una consulta y mantener la ejecución de sqlcmd después de la finalización de la consulta:

    sqlcmd -q "SELECT * FROM AdventureWorks2022.Person.Person"

  • Conectarse a la instancia predeterminada del equipo local mediante la Autenticación de Windows, ejecutar una consulta, dirigir la salida a un archivo y cerrar sqlcmd después de la finalización de la consulta:

    sqlcmd -Q "SELECT * FROM AdventureWorks2022.Person.Person" -o MyOutput.txt

  • Conectarse a una instancia con nombre mediante la Autenticación de SQL Server para ejecutar de manera interactiva instrucciones T-SQL y hacer que sqlcmd solicite una contraseña:

    sqlcmd -U MyLogin -S <ComputerName>\<InstanceName>

    Sugerencia

    Para ver una lista de opciones admitidas por la utilidad sqlcmd , ejecute: sqlcmd -?.

Ejecutar instrucciones Transact-SQL de forma interactiva mediante sqlcmd

Se puede usar la utilidad sqlcmd de manera interactiva para ejecutar instrucciones T-SQL en una ventana del símbolo del sistema. Para ejecutar de manera interactiva instrucciones T-SQL mediante sqlcmd, ejecute la utilidad sin usar las opciones -Q, -q, -Z o -i a fin de especificar consultas o archivos de entrada. Por ejemplo:

sqlcmd -S <ComputerName>\<InstanceName>

Cuando se ejecuta el comando sin archivos de entrada ni consultas, sqlcmd se conecta a la instancia especificada de SQL Server y, después, muestra una nueva línea con 1> seguido de un carácter de subrayado intermitente, denominado símbolo del sistema sqlcmd. El 1 significa que se trata de la primera línea de una instrucción T-SQL y el símbolo del sistema sqlcmd es el punto en el que empieza la instrucción T-SQL cuando la escriba.

En el símbolo de sistema sqlcmd, puede escribir instrucciones T-SQL y comandos de sqlcmd, como GO y EXIT. Cada instrucción T-SQL se coloca en un búfer denominado "caché de instrucciones". Estas instrucciones se enviarán a SQL Server cuando escriba el comando GO y pulse Entrar. Para salir de sqlcmd, escriba EXIT o QUIT al principio de una línea nueva.

Para borrar la memoria caché de instrucciones, escriba :RESET. Si escribe Ctrl+C, sqlcmd se cerrará. Ctrl+C se puede usar también para detener la ejecución de la memoria caché de instrucciones después de emitir un comando GO.

Las instrucciones T-SQL que se escriben en una sesión interactiva se pueden editar si se escribe el comando :ED y el símbolo de sistema sqlcmd. Se abrirá el editor y, después de editar la instrucción T-SQL y cerrar el editor, la instrucción T-SQL revisada aparecerá en la ventana de comandos. Escriba GO para ejecutar la instrucción de T-SQL revisada.

Cadenas entre comillas

Los caracteres que están entre comillas se usan sin ningún procesamiento previo adicional, con la excepción de que las comillas se pueden insertar en una cadena especificando dos comillas consecutivas. SQL Server trata esta secuencia de caracteres como una comilla. (Sin embargo, la traducción se lleva a cabo en el servidor). Las variables de scripting no se expanden si aparecen en una cadena.

Por ejemplo:

sqlcmd
PRINT "Length: 5"" 7'";
GO

El conjunto de resultados es el siguiente:

Length: 5" 7'

Cadenas que abarcan varias líneas

sqlcmd admite scripts con cadenas que abarcan varias líneas. Por ejemplo, la siguiente instrucción SELECT abarca varias líneas, pero es una única cadena que se ejecuta cuando se presiona la tecla Entrar después de escribir GO.

SELECT <First line>
FROM <Second line>
WHERE <Third line>;
GO

Ejemplo de sqlcmd interactivo

Este es un ejemplo de lo que se ve cuando se ejecuta sqlcmd de forma interactiva.

Cuando se abre una ventana del símbolo del sistema, solo hay una línea similar a:

C:\Temp\>

Esto significa que la carpeta C:\Temp\ es la carpeta actual y, si se especifica un nombre de archivo, Windows busca ese archivo en esa carpeta.

Escriba sqlcmd para conectarse a la instancia predeterminada de SQL Server en el equipo local; de esta forma, el contenido de la ventana del símbolo del sistema es:

C:\Temp>sqlcmd
1>

Esto significa que se ha conectado a una instancia de SQL Server y sqlcmd ya está listo para aceptar instrucciones T-SQL y comandos de sqlcmd. El carácter de subrayado intermitente después de 1> es el símbolo del sistema sqlcmd que marca la ubicación donde se muestran las instrucciones y los comandos que se escriban. Ahora, escriba USE AdventureWorks2022 y presione Entrar, y, a continuación, escriba GO y presione Entrar. El contenido de la ventana del símbolo del sistema es:

sqlcmd
USE AdventureWorks2022;
GO

El conjunto de resultados es el siguiente:

Changed database context to 'AdventureWorks2022'.
1>

Al presionar Entrar, indica a sqlcmd que inicie una nueva línea. Al presionar Entrar, después de escribir GO, se indica que sqlcmd envíe la instrucción USE AdventureWorks2022 a la instancia de SQL Server. sqlcmd devuelve un mensaje para indicar que la instrucción USE se completó correctamente y muestra un nuevo símbolo del sistema 1> como señal de que el usuario puede escribir una instrucción o un comando nuevos.

En el ejemplo siguiente se muestra qué contiene la ventana del símbolo del sistema si escribe una instrucción SELECT, GO para ejecutar SELECT y EXIT para finalizar sqlcmd:

USE AdventureWorks2022;
GO
SELECT TOP (3) BusinessEntityID, FirstName, LastName
FROM Person.Person;
GO

El conjunto de resultados es el siguiente:

BusinessEntityID  FirstName  LastName
----------------- ---------- ------------
1                 Syed       Abbas
2                 Catherine  Abel
3                 Kim        Abercrombie

Para generar una salida, sqlcmd restablece el símbolo de sistema sqlcmd y muestra 1>. Para finalizar la sesión, escriba EXIT en el símbolo del sistema de 1>. Ahora ya puede cerrar la ventana del símbolo del sistema escribiendo otro comando EXIT .

Creación y consulta de un contenedor de SQL Server

Puede usar sqlcmd (Go) para crear una nueva instancia de SQL Server en un contenedor. sqlcmd (Go) expone una instrucción create que permite especificar una imagen de contenedor y una copia de seguridad de SQL Server, para crear rápidamente una instancia de SQL Server con fines de desarrollo, depuración y análisis.

Importante

Necesita un entorno de ejecución de contenedor instalado, como Docker o Podman.

El siguiente comando muestra cómo ver todas las opciones disponibles para crear un nuevo contenedor de SQL Server:

sqlcmd create mssql --help

El comando siguiente crea una nueva instancia de SQL Server con la versión más reciente de SQL Server 2022 (16.x) y, a continuación, restaura la base de datos de ejemplo Wide World Importers:

sqlcmd create mssql --accept-eula --tag 2022-latest --using https://github.com/Microsoft/sql-server-samples/releases/download/wide-world-importers-v1.0/WideWorldImporters-Full.bak

Una vez creada la instancia de SQL Server, puede usar sqlcmd (Go) para administrarla y consultarla.

El comando siguiente confirma la versión de la instancia que se creó:

sqlcmd query "SELECT @@version"

El comando siguiente inicia una sesión interactiva con la instancia que se creó:

sqlcmd query

El comando siguiente abre Azure Data Studio y se conecta automáticamente a la base de datos que se restauró durante el proceso de creación:

sqlcmd open ads

El siguiente comando enumera las cadenas de conexión que se usarán para conectarse a la instancia que se creó:

sqlcmd config connection-strings

El siguiente comando se usa para eliminar el contenedor de Docker cuando ya no se necesite:

sqlcmd delete

Ejecución de archivos de scripts Transact-SQL mediante sqlcmd

Puede usar sqlcmd para ejecutar los archivos de script de base de datos. Los archivos de script son archivos de texto que contienen una combinación de instrucciones T-SQL, comandos de sqlcmd y variables de scripting. Para obtener más información sobre cómo incluir variables en scripts, vea Usar sqlcmd con variables de script. sqlcmd funciona con las instrucciones, los comandos y las variables de scripting en un archivo de script de una forma parecida a como opera con instrucciones y comandos indicados de forma interactiva. La diferencia principal es que sqlcmd lee el archivo de entrada sin pausas, en lugar de esperar a que un usuario indique las instrucciones, los comandos y las variables de scripting.

Hay distintas maneras de crear archivos de script de base de datos:

  • Puede compilar y depurar de manera interactiva un conjunto de instrucciones T-SQL en SQL Server Management Studio y, luego, guardar el contenido de la ventana Consulta como archivo de script.

  • Puede crear un archivo de texto que contenga instrucciones T-SQL con un editor de texto, como el Bloc de notas.

Ejemplos

A. Ejecución de un script con sqlcmd

Inicie el Bloc de notas y escriba las instrucciones T-SQL siguientes:

USE AdventureWorks2022;
GO
SELECT TOP (3) BusinessEntityID, FirstName, LastName
FROM Person.Person;
GO

Cree una carpeta llamada MyFolder y guarde el script como el archivo MyScript.sql en la carpeta C:\MyFolder. Escriba el siguiente comando en el símbolo del sistema para ejecutar el script y coloque la salida en MyOutput.txt de MyFolder:

sqlcmd -i C:\MyFolder\MyScript.sql -o C:\MyFolder\MyOutput.txt

El conjunto de resultados es el siguiente:

Changed database context to 'AdventureWorks2022'.
BusinessEntityID  FirstName  LastName
----------------- ---------- ------------
1                 Syed       Abbas
2                 Catherine  Abel
3                 Kim        Abercrombie
(3 rows affected)

B. Uso de sqlcmd con una conexión administrativa dedicada

En el siguiente ejemplo, se utiliza sqlcmd para conectarse a un servidor que tiene un problema de bloqueo mediante la conexión de administrador dedicada (DAC).

C:\Temp\>sqlcmd -S ServerName -A
1> SELECT session_id, blocking_session_id FROM `sys.dm_exec_requests` WHERE blocking_session_id <> 0;
2> GO

El conjunto de resultados es el siguiente:

session_id   blocking_session_id
-----------  --------------------`
62           64
(1 rows affected)

Utilice sqlcmd para finalizar el proceso de bloqueo.

1> KILL 64;
2> GO

C. Uso de sqlcmd para ejecutar un procedimiento almacenado

En el ejemplo siguiente se muestra cómo ejecutar un procedimiento almacenado con sqlcmd. Cree el siguiente procedimiento almacenado.

USE AdventureWorks2022;
GO

IF OBJECT_ID('dbo.ContactEmailAddress', 'P') IS NOT NULL
    DROP PROCEDURE dbo.ContactEmailAddress;
GO

CREATE PROCEDURE dbo.ContactEmailAddress (
    @FirstName NVARCHAR(50),
    @LastName NVARCHAR(50)
)
AS
SET NOCOUNT ON;

SELECT EmailAddress
FROM Person.Person
WHERE FirstName = @FirstName
    AND LastName = @LastName;

SET NOCOUNT OFF;
GO

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

C:\Temp\sqlcmd
1> :Setvar FirstName Gustavo
1> :Setvar LastName Achong
1> EXEC dbo.ContactEmailAddress $(FirstName),$(LastName)
2> GO
EmailAddress
-----------------------------
gustavo0@adventure-works.com

D. Uso de sqlcmd para mantenimiento de la base de datos

El siguiente ejemplo muestra cómo utilizar sqlcmd para una tarea de mantenimiento de base de datos. Cree C:\Temp\BackupTemplate.sql con el siguiente código.

USE master;
BACKUP DATABASE [$(db)] TO DISK='$(bakfile)';

En el símbolo del sistema sqlcmd, escriba este código:

C:\Temp\>sqlcmd
1> :connect <server>
Sqlcmd: Successfully connected to server <server>.
1> :setvar db msdb
1> :setvar bakfile C:\Temp\msdb.bak
1> :r C:\Temp\BackupTemplate.sql
2> GO
Changed database context to 'master'.
Processed 688 pages for database 'msdb', file 'MSDBData' on file 2.
Processed 5 pages for database 'msdb', file 'MSDBLog' on file 2.
BACKUP DATABASE successfully processed 693 pages in 0.725 seconds (7.830 MB/sec)

E. Uso de sqlcmd para ejecutar código en varias instancias

El siguiente código en un archivo muestra un script que se conecta a dos instancias. Observe el comando GO antes de la conexión a la segunda instancia.

:CONNECT <server>\,<instance1>
EXEC dbo.SomeProcedure
GO
:CONNECT <server>\,<instance2>
EXEC dbo.SomeProcedure
GO

E. Devolución de la salida XML

El siguiente ejemplo muestra cómo se devuelve la salida XML sin formato, en un flujo continuo.

C:\Temp\>sqlcmd -d AdventureWorks2022
1> :XML ON
1> SELECT TOP 3 FirstName + ' ' + LastName + ', '
2> FROM Person.Person
3> GO
Syed Abbas, Catherine Abel, Kim Abercrombie,

F. Uso de sqlcmd en un archivo de script de Windows

Un comando sqlcmd como sqlcmd -i C:\Temp\InputFile.txt -o C:\Temp\OutputFile.txt, se puede ejecutar en un archivo .bat junto con VBScript. En este caso, no se deben usar opciones interactivas. sqlcmd se debe instalar en el equipo que ejecuta el archivo .bat.

Primero, cree los siguientes cuatro archivos en C:\Temp:

  • C:\Temp\badscript.sql

    SELECT batch_1_this_is_an_error
GO
SELECT 'batch #2'
GO

  • C:\Temp\goodscript.sql

    SELECT 'batch #1';
GO
SELECT 'batch #2';
GO

  • C:\Temp\returnvalue.sql

    :exit(select 100)

  • C:\Temp\windowsscript.bat

    @echo off

echo Running badscript.sql
sqlcmd -i badscript.sql -b -o out.log
if not errorlevel 1 goto next1
echo == An error occurred

:next1

echo Running goodscript.sql
sqlcmd -i goodscript.sql -b -o out.log
if not errorlevel 1 goto next2
echo == An error occurred

:next2
echo Running returnvalue.sql
sqlcmd -i returnvalue.sql -o out.log
echo SQLCMD returned %errorlevel% to the command shell

:exit

Después, en el símbolo del sistema, ejecute C:\Temp\windowsscript.bat:

C:\Temp\>windowsscript.bat
Running badscript.sql
== An error occurred
Running goodscript.sql
Running returnvalue.sql

SQLCMD returned 100 to the command shell

G. Uso de sqlcmd para establecer el cifrado en Azure SQL Database

Se puede ejecutar un comando sqlcmd en una conexión con datos de SQL Database para especificar el cifrado y la confianza del certificado. Hay dos opciones sqlcmd disponibles:

  • El modificador -N lo usa el cliente para solicitar una conexión cifrada. Esta opción es equivalente a ADO.net ENCRYPT = true.

  • El modificador -C lo emplea el cliente para configurarlo implícitamente para el certificado de servidor confiable y no validarlo. Esta opción es equivalente a ADO.net TRUSTSERVERCERTIFICATE = true.

El servicio SQL Database no admite todas las opciones SET disponibles en una instancia de SQL Server. Las siguientes opciones producen un error cuando la opción SET correspondiente está establecida en ON u OFF:

  • SET ANSI_DEFAULTS
  • SET ANSI_NULLS
  • SET REMOTE_PROC_TRANSACTIONS
  • SET ANSI_NULL_DEFAULT

Las siguientes opciones de SET no producen excepciones pero no se pueden usar. Están en desuso:

  • SET CONCAT_NULL_YIELDS_NULL
  • SET ANSI_PADDING
  • SET QUERY_GOVERNOR_COST_LIMIT

Sintaxis

En los siguientes ejemplos se hace referencia a los casos donde la configuración del proveedor Native Client SQL Server incluye:

  • ForceProtocolEncryption = False
  • Trust Server Certificate = No

Conecte usando las credenciales de Windows y cifre la comunicación:

sqlcmd -E -N

Conecte usando las credenciales de Windows y el certificado de servidor de confianza:

sqlcmd -E -C

Conecte usando las credenciales de Windows, comunicación cifrada y el certificado de servidor de confianza:

sqlcmd -E -N -C

En los siguientes ejemplos se hace referencia a los casos donde la configuración del proveedor Native Client SQL Server incluye:

  • ForceProtocolEncryption = True
  • TrustServerCertificate = Yes

Conecte usando las credenciales de Windows, comunicación cifrada y el certificado de servidor de confianza:

sqlcmd -E

Conecte usando las credenciales de Windows, comunicación cifrada y el certificado de servidor de confianza:

sqlcmd -E -N

Conecte usando las credenciales de Windows, comunicación cifrada y el certificado de servidor de confianza:

sqlcmd -E -C

Conecte usando las credenciales de Windows, comunicación cifrada y el certificado de servidor de confianza:

sqlcmd -E -N -C

Si el proveedor especifica ForceProtocolEncryption = True se habilita el cifrado aun cuando Encrypt=No en la cadena de conexión.

Pasos siguientes