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

Применимо к:SQL ServerБаза данных SQL AzureУправляемый экземпляр SQL AzureAzure Synapse AnalyticsСистема платформы аналитики (PDW)База данных SQL в предварительной версии Microsoft Fabric

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

В дополнение к инструкциям Transact-SQL в программе sqlcmd доступны следующие команды:

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

¹ Не поддерживается в Linux или macOS.

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

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

  Important

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

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

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

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

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

Editing commands

[:]ED

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

Текстовый редактор определяется переменной SQLCMDEDITOR среды. Редактор по умолчанию .Edit Чтобы изменить редактор, задайте SQLCMDEDITOR переменную среды. Например, чтобы установить в качестве редактора Блокнот (Майкрософт), в командной строке введите:

SET SQLCMDEDITOR=notepad

[:]RESET

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

:List

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

Variables

:Setvar <var> [ "value" ]

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

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

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

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

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

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

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

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

:Listvar

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

Output commands

:Error <filename> | STDERR | STDOUT

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

• filename

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

• STDERR

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

• STDOUT

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

:Out <filename> | STDERR | STDOUT

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

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

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

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

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

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

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

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

[:]QUIT

Ведет к завершению работы sqlcmd .

[:]EXIT [ ( оператор ) ]

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

For example:

:EXIT(SELECT @@ROWCOUNT)

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

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

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

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

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

• :EXIT

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

• :EXIT( )

  Выполняет пакет, завершает выполнение и не возвращает значения.

• :EXIT(query)

  Выполняет пакет, включая запрос, возвращает результаты запроса и завершает работу.

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

RAISERROR(50001, 10, 127)

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

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

GO [count]

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

Miscellaneous commands

:r <filename>

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

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

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

:ServerList

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

:Подключение server_name[\instance_name] [-l timeout] [-U user_name [-P password]]

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

Timeout options:

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

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

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

:connect myserver\instance1

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

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

[:]!! command

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

:!! dir

:XML [ ON | OFF ]

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

:Help

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

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

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

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

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

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

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

Informational messages

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

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

USE AdventureWorks2022;
GO

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

Changed database context to 'AdventureWorks2022'.

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

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

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

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

USE AdventureWorks2022;

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

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

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

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

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

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

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

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

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

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

Формат выходных данных 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

Related content

• sqlcmd utility
• Проверка установленной версии программы sqlcmd
• Запустите служебную программу sqlcmd
• Выполнение T-SQL из файла скрипта с помощью sqlcmd
• Use sqlcmd