Бөлісу құралы:

Команды в служебной программе sqlcmd

Относится к:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsАналитическая платформа (PDW)SQL база данных в Microsoft Fabric

Программа sqlcmd принимает Transact-SQL инструкции , системные процедуры и файлы скриптов.

Note

Чтобы узнать, какой вариант и версия sqlcmd установлены в системе, см. статью "Проверка установленной версии служебной программы sqlcmd". Сведения о том, как получить sqlcmd, см. в разделе "Скачать и установить служебную программу sqlcmd".

Помимо инструкций Transact-SQL в sqlcmd, используйте следующие команды:

  • 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 Не поддерживается в Linux или macOS.

При использовании команд sqlcmd следует учитывать следующие моменты:

  • Все команды sqlcmd , кроме того GO, должны начинаться с двоеточия (:).

    Important

    Для обеспечения обратной совместимости с существующими скриптами osql некоторые команды работают без двоеточия, что указано с помощью [:].

  • sqlcmd распознает команды только в том случае, если они отображаются в начале строки.

  • Во всех командах sqlcmd регистр символов не учитывается.

  • Каждая команда должна находиться на отдельной строке. Вы не можете следовать команде с помощью инструкции Transact-SQL или другой команды.

  • Команды выполняются немедленно. Они не помещаются в буфер выполнения так, как это делается для инструкций Transact-SQL.

Команды редактирования

[:]ED

Производит запуск текстового редактора. Этот редактор используется для изменения текущего пакета Transact-SQL или последнего выполненного пакета. Чтобы изменить последний пакет выполнения, введите ED команду сразу после завершения выполнения последнего пакета.

Переменная SQLCMDEDITOR среды определяет текстовый редактор. Редактор по умолчанию - это Edit. Чтобы изменить редактор, задайте SQLCMDEDITOR переменную среды. Например, чтобы установить Microsoft Notepad в качестве редактора, введите следующую команду:

SET SQLCMDEDITOR=notepad

[:]RESET

Очистка кэша инструкций.

:List

Вывод содержимого кэша инструкций.

Variables

:Setvar <var> [ "value" ]

Определяет переменные скрипта sqlcmd . Переменные скрипта имеют следующий формат: $(VARNAME).

Имена переменных не зависят от регистра символов.

Переменные скрипта могут быть установлены следующими способами.

  • Неявное использование параметра командной строки. Например, параметр -l задает SQLCMDLOGINTIMEOUTпеременную sqlcmd .
  • Явно используя команду :Setvar.
  • Определение переменной среды перед запуском sqlcmd.

Note

Параметр -X предотвращает передаче переменных среды в sqlcmd.

Если переменная, определяемая с помощью и :Setvar переменной среды, имеет то же имя, переменная, определяемая с помощью :Setvar , имеет приоритет.

Имена переменных не должны содержать пробелы.

Имена переменных не могут иметь ту же форму, что и выражение переменной, например $(var).

Если строковое значение переменной скрипта содержит пробелы, то заключите значение в кавычки. Если значение переменной сценариев не указано, переменная скрипта удаляется.

:Listvar

Список переменных скрипта, заданных в настоящее время.

Note

Отображаются только переменные сценариев, заданные sqlcmd, и переменные, заданные с помощью :Setvar команды.

Выходные команды

:Error <filename> | STDERR | STDOUT

Перенаправьте весь вывод ошибок в указанный файл с именем , в или в . Команда :Error может отображаться несколько раз в скрипте. По умолчанию выходные данные ошибок переходят в stderr.

  • filename

    Создает и открывает файл, который получает выходные данные. Существующий файл усечен до нуля байтов. Если файл недоступен из-за разрешений или других причин, выходные данные не переключаются, и последний указанный пункт назначения или пункт назначения по умолчанию получает выходные данные об ошибке.

  • STDERR

    Переключает вывод ошибок на поток stderr. Если выходные данные перенаправляются, целевой объект, в который перенаправляется поток, получает выходные данные об ошибке.

  • STDOUT

    Переключает вывод ошибок на поток stdout. Если выходные данные перенаправляются, целевой объект, в который перенаправляется поток, получает выходные данные об ошибке.

:Out <имя файла> | STDERR | STDOUT

Создает и перенаправляет все результаты запроса в файл, указанный именем файла, в stderrили в stdout. По умолчанию выходные данные отправляются на stdout. Если файл уже существует, он усечен до нуля байтов. Команда :Out может отображаться несколько раз в скрипте.

:Perftrace <имя файла> | STDERR | STDOUT

Создает и перенаправляет всю информацию трассировки производительности в файл, указанный именем файла, в stderr, или в stdout. По умолчанию результаты трассировки производительности переходят к stdout. Существующий файл усечен до нуля байтов. Команда :Perftrace может отображаться несколько раз в скрипте.

Команды управления выполнением

:При ошибке [ выйти | игнорировать ]

Задает действие, выполняемое при возникновении ошибки во время выполнения скрипта или пакетного выполнения.

При использовании exit параметра sqlcmd завершает работу с соответствующим значением ошибки.

При использовании ignore параметра sqlcmd игнорирует ошибку и продолжает выполнять пакет или скрипт. По умолчанию sqlcmd выводит сообщение об ошибке.

[:]QUIT

Вызывает выход из sqlcmd.

[:/]EXIT [ ( инструкция ) ]

Используйте результат инструкции SELECT в качестве возвращаемого значения из sqlcmd. Если числовой, первый столбец последней строки результатов преобразуется в 4-байтовое целое число (long). MS-DOS, Linux и macOS передают младший байт в родительский процесс или уровень ошибки операционной системы. Windows 2000 и более поздние версии передают полностью целое число 4-байтов. Синтаксис :EXIT(query).

Рассмотрим пример.

:EXIT(SELECT @@ROWCOUNT)

Вы также можете включить :EXIT параметр в пакетный файл. Например, в командной строке введите:

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

Служебная программа sqlcmd отправляет все между скобками (()) на сервер. Если хранимая системная процедура выбирает набор и возвращает значение, то возвращается только выбранный набор. Оператор :EXIT() без ничего внутри круглых скобок выполняет все перед ним в пакете, а затем завершается без возвращаемого значения.

При указании неправильного запроса sqlcmd завершает работу без возвращаемого значения.

Ниже приведен список форматов EXIT:

  • :EXIT

    Не запускает пакет, а затем немедленно завершает работу и не возвращает значения.

  • :EXIT( )

    Запускает пакет, а затем завершает работу и не возвращает значения.

  • :EXIT(query)

    Запускает пакет, включающий запрос, а затем завершает работу после возврата результатов запроса.

Если вы используете RAISERROR в скрипте sqlcmd и вызываете состояние 127, sqlcmd завершает работу и возвращает идентификатор сообщения обратно клиенту. Рассмотрим пример.

RAISERROR(50001, 10, 127)

Эта ошибка приводит к завершению скрипта sqlcmd и возврату идентификатора сообщения 50001 клиенту.

Возвращаемые значения с -1 по -99 зарезервированы в SQL Server, а sqlcmd определяет дополнительные к зарезервированным значениям:

Возвращаемое значение Description
-100 Возникла ошибка перед выбором возвращаемого значения.
-101 При выборе возвращаемого значения не найдены строки.
-102 При выборе возвращаемого значения произошла ошибка преобразования.

ВПЕРЕД [count]

GO сигнализирует о завершении пакета и выполнении всех кэшированных инструкций Transact-SQL. Пакет выполняется несколько раз в виде отдельных заданий. Нельзя объявлять переменную несколько раз в одном пакете.

Разные команды

:r <filename>

Анализирует дополнительные инструкции Transact-SQL и команды sqlcmd из файла, указанного именем файла в кэше инструкций. sqlcmd считывает имя файла относительно каталога запуска.

Если файл содержит инструкции Transact-SQL, за которыми не следует GO, необходимо ввести GO на строке, следующей после :r.

sqlcmd считывает и выполняет файл после того, как он сталкивается с завершающим оператором пакета. Вы можете выдавать несколько :r команд. Файл может включать любую команду sqlcmd , включая пакетный терминатор GO.

Note

Число строк, отображающееся в интерактивном режиме, увеличивается на один для каждой :r обнаруженной команды. Команда :r отображается в выходных данных команды list.

:ServerList

Выводит список локально настроенных серверов и имена серверов, осуществляющих трансляцию данных в сети.

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

Соединяется с экземпляром SQL Server. Также закрывает текущее соединение.

Important

Команда :Connect не действует как неявный разделитель пакета. Все инструкции Transact-SQL, буферизированные в текущем пакете, не выполняются до тех пор, пока команда GO не будет выдана. Если вы используете несколько :Connect команд без промежуточных GO операторов, все буферизованные операторы выполняются на последнем подключенном сервере, а не на каждом сервере по отдельности.

  • Параметры шифрования (-N[s|m|o]):

    Используйте этот параметр для запроса зашифрованного подключения. Если вы не включаете -N, -Nm (для mandatory) является значением по умолчанию. Этот параметр представляет собой значительное изменение по сравнению с SQL Server 2022 (16.x) и более ранними версиями, где -No (для optional) является значением по умолчанию.

    Value Description
    -Ns Строгий
    -Nm (по умолчанию) Mandatory
    -No Необязательно

  • Имя узла в сертификате (-F hostname_in_certificate)

    Указывает другое, ожидаемое общее имя (CN) или альтернативное имя субъекта (SAN) в сертификате сервера для использования во время проверки сертификата сервера. Без этого параметра проверка сертификатов гарантирует, что CN или SAN в сертификате совпадает с именем сервера, к которому выполняется подключение. Этот параметр можно заполнить, если имя сервера не совпадает с именем CN или SAN, например при использовании псевдонимов DNS.

  • Параметры времени ожидания:

    Value Behavior
    0 Ждать навсегда
    n>0 Подождите n секунд

    Переменная SQLCMDSERVER скрипта отражает текущее активное подключение.

    Если время ожидания не указано, значение переменной SQLCMDLOGINTIMEOUT по умолчанию.

Если указать только user_name (в качестве параметра или в качестве переменной среды), sqlcmd предложит ввести пароль. Пользователи не получают запрос, если заданы переменные среды SQLCMDUSER или SQLCMDPASSWORD. Если вы не предоставляете параметры или переменные среды, для входа используется режим проверки подлинности Windows. Например, чтобы подключиться к экземпляру instance1 SQL Server, myserver с помощью интегрированной безопасности, вы будете использовать следующую команду:

:connect myserver\instance1

Чтобы подключиться к экземпляру myserver по умолчанию с помощью переменных скриптов, используйте следующие параметры:

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

[:]!! command

Выполняет команды операционной системы. Чтобы выполнить команду операционной системы, запустите строку с двумя восклицательными знаками (!!), а затем командой операционной системы. Рассмотрим пример.

:!! dir

Note

Команда выполняется на компьютере, на котором выполняется sqlcmd .

:XML [ ON | OFF ]

Дополнительные сведения см. в разделе "Формат выходных данных XML" и "Формат выходных данных JSON" в этой статье.

:Help

Перечисляет команды sqlcmd , а также краткое описание каждой команды.

Имена файлов sqlcmd

Укажите входные файлы sqlcmd с помощью -i параметра или :r команды. Укажите выходные файлы, используя параметр -o или команды :Error, :Out и :Perftrace. При работе с этими файлами используйте следующие рекомендации.

  • Используйте отдельные значения имени файла для :Error, :Outи :Perftrace. При использовании того же имени файла команды могут пересекать входные данные.

  • При вызове входного файла, расположенного на удаленном сервере из sqlcmd на локальном компьютере, и файл содержит путь к файлу диска, например :Out c:\OutputFile.txtsqlcmd, создает выходной файл на локальном компьютере, а не на удаленном сервере.

  • Допустимы следующие пути: C:\<filename>, \\<Server>\<Share$>\<filename> и "C:\Some Folder\<file name>". Если в пути есть пробел, используйте кавычки.

  • Каждый новый сеанс sqlcmd перезаписывает существующие файлы с одинаковыми именами.

Информационные сообщения

sqlcmd выводит любое информационное сообщение, которое отправляет сервер. В следующем примере после выполнения инструкций Transact-SQL sqlcmd он выводит информационное сообщение.

Запустите sqlcmd. Введите в командную строку sqlcmd следующий запрос.

USE AdventureWorks2025;
GO

При нажатии клавиши ВВОД, sqlcmd выводит следующее информационное сообщение:

Changed database context to 'AdventureWorks2025'.

Формат выходных данных из запросов Transact-SQL

Сначала программаsqlcmd выводит заголовок с именами столбцов, перечисленными в списке выборки, Имена столбцов разделяются символом SQLCMDCOLSEP . По умолчанию этот разделитель столбцов является пробелом. Если имя столбца меньше ширины столбца, sqlcmd заполняет выходные данные пробелами до следующего столбца.

sqlcmd выводит строку разделителя, которая представляет собой ряд символов дефиса. Далее представлен пример вывода.

Запустите sqlcmd. Введите в командную строку sqlcmd следующий запрос.

USE AdventureWorks2025;

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

При нажатии клавиши ВВОД, sqlcmd возвращает следующий результирующий набор.

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

BusinessEntityID Хотя столбец имеет ширину только четыре символа, он расширяется для размещения более длинного имени столбца. По умолчанию sqlcmd ограничивает вывод до 80 символов. Эту ширину можно изменить с помощью -w параметра или задания переменной SQLCMDCOLWIDTH скриптов.

Формат выходных данных XML

Выходные данные XML, которые являются результатом FOR XML предложения, выводятся неформатированными в непрерывном потоке.

Если вы ожидаете вывод XML-данных, воспользуйтесь следующей командой: :XML ON.

Note

Программаsqlcmd выводит сообщения об ошибках в обычном формате. Сообщения об ошибках также выводятся в текстовом потоке XML в формате XML. При использовании :XML ONsqlcmd не отображаются информационные сообщения.

Чтобы отключить режим XML, введите следующую команду: :XML OFF.

Команда GO не должна отображаться перед :XML OFF выполнением команды, так как :XML OFF команда переключает sqlcmd обратно на выходные данные, ориентированные на строки.

Смешивание XML-данных (потоковых) и данных набора строк не допускается. :XML ON Если команда не была выдана перед запуском инструкции Transact-SQL, выводящей XML-потоки, то вывод будет искажен. :XML ON После выдачи команды невозможно выполнять инструкции Transact-SQL, которые выводят обычные наборы строк.

Note

Команда :XML не поддерживает инструкцию SET STATISTICS XML.

Формат выходных данных JSON.

Если ожидается вывод данных JSON, воспользуйтесь следующей командой: :XML ON. В противном случае выходные данные включают имя столбца и текст JSON. Выходные данные не являются допустимым JSON.

Чтобы отключить режим XML, введите следующую команду: :XML OFF.

Дополнительные сведения см. в разделе Формат вывода XML этой статьи.

Используйте проверку подлинности Microsoft Entra

Примеры, использующие проверку подлинности 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

Связанный контент

  • Last updated on