Служебная программа sqlcmd

  • Статья

Служебная sqlcmd программа позволяет вводить инструкции Transact-SQL, системные процедуры и файлы скриптов в командной строке, в Редактор запросов в режиме SQLCMD, в файл скрипта Windows или на шаге задания операционной системы (Cmd.exe) задания агент SQL Server. Эта программа использует ODBC для выполнения пакетов Transact-SQL.

Важно!

SQL Server Management Studio использует Microsoft.NET FrameworkSqlClient для выполнения в обычном режиме и режиме SQLCMD в Редактор запросов. При вызове программы sqlcmd из командной строки sqlcmd использует драйвер ODBC. Так как могут применяться разные параметры по умолчанию, при выполнении одного и того же запроса в SQL Server Management Studio в режиме SQLCMD и в служебной программе может наблюдаться другое sqlcmd поведение.

В настоящее время в программе sqlcmd не требуется указывать пробел между параметром командной строки и значением. Но в будущих выпусках пробел между параметром командной строки и значением может потребоваться.

Синтаксис

  
   sqlcmd  
   -a  
   packet_size  
   -A (dedicated administrator connection)  
-b (terminate batch job if there is an error)  
-cbatch_terminator-C (trust the server certificate)  
-ddb_name-e (echo input)  
-E (use trusted connection)  
-fcodepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]  
-hrows_per_header-Hworkstation_name-iinput_file-I (enable quoted identifiers)  
-k[1 | 2] (remove or replace control characters)  
-Kapplication_intent-llogin_timeout-L[c] (list servers, optional clean output)  
-merror_level-Mmultisubnet_failover-N (encrypt connection)  
-ooutput_file-p[1] (print statistics, optional colon format)  
-Ppassword-q "cmdline query"-Q "cmdline query" (and exit)  
-r[0 | 1] (msgs to stderr)  
-R (use client regional settings)  
-scol_separator-S [protocol:]server[\instance_name][,port]  
-tquery_timeout-u (unicode output file)  
-Ulogin_id-vvar = "value"-Verror_severity_level-wcolumn_width-W (remove trailing spaces)  
-x (disable variable substitution)  
-X[1] (disable commands, startup script, environment variables and optional exit)  
-yvariable_length_type_display_width-Yfixed_length_type_display_width-znew_password -Znew_password (and exit)  
  
-? (usage)

Параметры командной строки

Параметры, связанные с именем для входа
-A
Вход в SQL Server с помощью выделенного административного подключения (DAC). Этот вид соединения предназначен для устранения неполадок на сервере. Параметр будет работать только с теми серверами, которые поддерживают выделенные административные соединения. Если соединение DAC недоступно, программа sqlcmd выдает сообщение об ошибке и завершает свою работу. Дополнительные сведения о DAC см. в статье Диагностическое соединение для администраторов баз данных.

-C
С помощью этого переключателя клиент настраивает неявное доверие к сертификату сервера без проверки. Этот параметр аналогичен параметру ADO.NET TRUSTSERVERCERTIFICATE = true.

-dимя_базы данных
USE Выдает оператор db_name при запуске sqlcmd. Этот параметр устанавливает переменную скрипта SQLCMDDBNAME программы sqlcmd. Она задает начальную базу данных. По умолчанию свойство default-database имени входа. Если база данных не существует, выдается сообщение об ошибке и программа sqlcmd завершает свою работу.

-llogin_timeout
Задает время ожидания (в секундах) при подключении программы sqlcmd через драйвер ODBC при попытке соединения с сервером. Этот параметр устанавливает переменную скрипта SQLCMDLOGINTIMEOUT программы sqlcmd. По умолчанию время ожидания входа для программы sqlcmd составляет 8 секунд. Время ожидания входа должно быть числом в диапазоне от 0 до 65 534. Если указанное значение не является числом или выходит за пределы указанного диапазона, программа sqlcmd выдает сообщение об ошибке. Значение 0 задает неограниченное время ожидания.

-E
Использует доверенное подключение вместо имени пользователя и пароля для входа в SQL Server. По умолчанию, если параметр -E не указан, программа sqlcmd использует доверительное соединение.

Параметр -E не использует имя пользователя и пароль, указанные в переменных среды, например SQLCMDPASSWORD. Если параметр -E используется в сочетании с параметром -U или -P , выдается сообщение об ошибке.

-Hимя_рабочей_станции
Имя рабочей станции. Этот параметр устанавливает переменную скрипта SQLCMDWORKSTATION программы sqlcmd. Имя рабочей станции заносится в столбец hostname представления каталога sys.processes и может быть возвращено с помощью хранимой процедуры sp_who. Если этот параметр не указан, используется текущее имя компьютера. Это имя может использоваться для идентификации сеансов работы программы sqlcmd.

-Kapplication_intent
Объявляет тип рабочей нагрузки приложения при соединении с сервером. Единственным поддерживаемым в данное время значением является ReadOnly. Если параметр -K не указан, то программа sqlcmd не будет поддерживать возможность подключения к вторичной реплике в группе доступности AlwaysOn. Дополнительные сведения см. в разделе Активные вторичные реплики: доступные для чтения вторичные реплики.

-Mmultisubnet_failover
Всегда указывайте -M при подключении к прослушивателю группы доступности SQL Server группы доступности или экземпляра отказоустойчивого кластера SQL Server. -M обеспечивает более быстрое обнаружение активного (в данный момент) сервера и соединение с ним. Если параметр -M не указан, то режим -M отключен. Дополнительные сведения о группах доступности Always On см. в разделах Прослушиватели групп доступности, подключение клиентов и отработка отказа приложений (SQL Server),Создание и настройка групп доступности (SQL Server),Отказоустойчивая кластеризация и Группы доступности AlwaysOn (SQL Server) и Активные вторичные реплики: доступные для чтения вторичные реплики.

-N
С помощью этого переключателя клиент запрашивает шифрованное соединение.

-Pпароль
Пароль, задаваемый пользователем. Пароли учитывают регистр. Если используется параметр -U, а параметр -P не используется, а переменная среды SQLCMDPASSWORD не задана, sqlcmd пользователь запрашивает пароль. Если параметр -P используется в конце командной строки без пароля sqlcmd , используется пароль по умолчанию (NULL).

Важно!

Не используйте пустые пароли. Выбирайте надежные пароли. Дополнительные сведения см. в разделе Strong Passwords.

Запрос на ввод пароля выводится на консоль следующим образом: Password:.

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

Переменная среды SQLCMDPASSWORD позволяет задать значение пароля по умолчанию для текущего сеанса. Таким образом, нет необходимости указывать пароль в пакетных файлах.

В следующем примере сначала из командной строки устанавливается переменная SQLCMDPASSWORD, а затем производится вызов программы sqlcmd. В командной строке введите:

SET SQLCMDPASSWORD= p@a$$w0rd

Важно!

Пароль будет отображаться на мониторе компьютера.

В командной строке введите:

sqlcmd

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

Примечание

Переменная среды OSQLPASSWORD была сохранена в целях обратной совместимости. Переменная среды SQLCMDPASSWORD имеет приоритет над переменной среды OSQLPASSWORD; это означает, что sqlcmd и osql можно использовать рядом друг с другом без вмешательства, и что старые скрипты будут продолжать работать.

Если параметр -P указан одновременно с параметром -E , выдается сообщение об ошибке.

Если после параметра -P указано более одного аргумента, выдается сообщение об ошибке, и программа завершает работу.

-S [протокол:]сервер[\имя_экземпляра][,порт]
Указывает экземпляр SQL Server, к которому выполняется подключение. Устанавливает переменную скрипта SQLCMDSERVER программы sqlcmd.

Укажите значение имя_сервера, чтобы подключиться к экземпляру SQL Server по умолчанию на этом сервере. Укажите имя_сервера [ \имя_экземпляра ], чтобы подключиться к именованному экземпляру SQL Server на этом сервере. Если сервер не указан, sqlcmd подключается к экземпляру SQL Server по умолчанию на локальном компьютере. Этот параметр обязателен при запуске программы sqlcmd с удаленного компьютера в сети.

протокол может быть tcp (TCP/IP), lpc (общая память) или np (именованные каналы).

Если при запуске sqlcmdне указать server_name [ \instance_name ] , SQL Server проверяет и использует переменную среды SQLCMDSERVER.

Примечание

Переменная среды OSQLSERVER была сохранена в целях обратной совместимости. Переменная среды SQLCMDSERVER имеет приоритет над переменной среды OSQLSERVER; это означает, что sqlcmd и osql можно использовать рядом друг с другом без вмешательства, и что старые скрипты будут продолжать работать.

-Uидентификатор_входа
Идентификатор входа пользователя.

Примечание

В целях обратной совместимости доступна переменная среды OSQLUSER. Переменная среды SQLCMDUSER имеет больший приоритет, чем OSQLUSER. Это означает, что sqlcmd и osql можно использовать рядом друг с другом без помех. Кроме того, это означает, что существующие скрипты osql не перестанут работать.

Если ни параметр -U , ни параметр -P не указаны, sqlcmd пытается подключиться с помощью режима проверки подлинности Microsoft Windows. При этом используется учетная запись пользователя Windows, который запустил программу sqlcmd.

Если параметры -U и -E (описаны ниже в этом разделе) указаны одновременно, выдается сообщение об ошибке. Если после параметра -U указано более одного аргумента, выдается сообщение об ошибке и программа завершает работу.

-zновый_пароль
Сменить пароль:

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

-Zновый_пароль
Измените пароль и выйти:

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

Параметры ввода-вывода
-fкодовая_страница | i:кодовая_страница[,o:кодовая_страница] | o:кодовая_страница[,i:кодовая_страница]
Задает входные и выходные кодовые страницы. Номер кодовой страницы — это числовое значение, которое определяет установленную кодовую страницу Windows.

Правила преобразования кодовых страниц:

  • Если кодовые страницы не заданы, программа sqlcmd использует текущую кодовую страницу как для входных, так и для выходных файлов. Для входного файла в Юникоде преобразование не требуется.

  • Программа sqlcmd автоматически распознает входные файлы в Юникоде как с прямым, так и с обратным порядком следования байтов. Если задан параметр -u , выходные данные всегда будут в Юникоде с прямым порядком байтов.

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

  • Предполагается, что все входные файлы имеют одинаковую кодовую страницу. Входные файлы в Юникоде и не в Юникоде можно обрабатывать вместе.

Чтобы проверить кодовую страницу Cmd.exe, введите в командной строке команду chcp.

-iвходной_файл[,входной_файл_2...]
Указывает файл, содержащий пакет инструкций или хранимых процедур SQL. Можно указать несколько файлов, которые будут считываться и обрабатываться в указанном порядке. Не разделяйте имена файлов пробелами. Программа sqlcmd сначала производит проверку наличия всех указанных файлов. Если хотя бы один из файлов не найден, программа sqlcmd завершит работу. Параметры -i и -Q/-q являются взаимоисключающими.

Примеры пути:

-Я C:\<filename>

-i \\<Server>\<Share$>\<filename>

-Я "C:\Some Folder\<имя> файла"

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

Этот параметр можно использовать многократно: -iвходной_файл-II входной_файл.

-oвыходной_файл
Указывает файл, в который поступают выходные данные программы sqlcmd.

Если указан параметр -u , выходной_файл сохраняется в Юникоде. Если указано недопустимое имя файла, программа sqlcmd выдает сообщение об ошибке и завершает работу. sqlcmd не поддерживает одновременную запись нескольких sqlcmd процессов в один файл. В этом случае выводимые в файл данные будут неверны или повреждены. Дополнительные сведения о форматах файлов см. в описании параметра -f . Если этот файл не существует, он будет создан. Файл от предыдущего сеанса работы программы sqlcmd с тем же именем будет перезаписан. Указанный здесь файл не является файлом stdout . Если указан stdout-файл , этот файл не будет использоваться.

Примеры пути:

-O C:\< имя файла>

-o \\<Server>\<Share$>\<filename>

**-o "**C:\Some Folder\<file name>"

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

-r[0 | 1]
Перенаправляет вывод сообщений об ошибке на экран (stderr). Если параметр не указан или если указано значение 0, происходит перенаправление только сообщений об ошибках с уровнем серьезности 11 и выше. Если указать 1, то происходит перенаправление всех сообщений об ошибках (включая команду PRINT). Не имеет эффекта, если указан параметр -o. По умолчанию сообщения отправляются в stdout.

-R
Приводит к локализации числовых столбцовsqlcmd, столбцов валюты, даты и времени, полученных из SQL Server, на основе языкового стандарта клиента. По умолчанию эти столбцы отображаются с использованием региональных параметров сервера.

-u
Указывает, что выходной_файл хранится в Юникоде независимо от формата файла входной_файл.

Параметры выполнения запросов
-e
Выдает входные скрипты на стандартное устройство вывода (stdout).

-I
Устанавливает значение ON для параметра соединения SET QUOTED_IDENTIFIER. По умолчанию этот параметр имеет значение OFF. Дополнительные сведения см. в статье SET QUOTED_IDENTIFIER (Transact-SQL).

-q"запрос_командной_строки"
Выполняет запрос при sqlcmd запуске, но не завершает работу sqlcmd после завершения выполнения запроса. Может быть выполнено несколько запросов, разделенных точкой с запятой. Заключайте запрос в кавычки, как показано в следующем примере.

В командной строке введите:

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

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

Важно!

Не используйте в запросе признак конца GO.

Если вместе с этим параметром указан параметр -b, программа sqlcmd завершает работу при возникновении ошибки. Параметр -b описан ранее в этом разделе.

-Q"запрос cmdline"
При запуске программы sqlcmd выполняет запрос и немедленно завершает работу sqlcmd. Может быть выполнено несколько запросов, разделенных точкой с запятой.

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

В командной строке введите:

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

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

Важно!

Не используйте в запросе признак конца GO.

Если вместе с этим параметром указан параметр -b, программа sqlcmd завершает работу при возникновении ошибки. Параметр -b описан ранее в этом разделе.

-tвремя_ожижания_запроса
Указывает время ожидания команды (или инструкции SQL) в секундах. Этот параметр задает переменную скрипта sqlcmd SQLCMDSTATTIMEOUT. Если значение время_ожидания не указывается, то команда имеет неограниченное время ожидания. Значение время_ожидания**запроса должно быть числом в диапазоне от 1 до 65534. Если указанное значение не является числом или выходит за пределы указанного диапазона, программа sqlcmd выдает сообщение об ошибке.

Примечание

Фактическое время ожидания может отличаться от указанного значения время_ожидания на несколько секунд.

-vvar =value[ var =value...]
Создает переменную sqlcmdскрипта, которую можно использовать в скрипте sqlcmd . Если значение содержит пробелы, заключите его в кавычки. Можно указать несколько значений var="values". Если в каком-либо из указанных значений обнаружена ошибка, программа sqlcmd выдает сообщение и завершает работу.

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

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

-x
Указывает, что программа sqlcmd не должна обрабатывать переменные скрипта. Это может отказаться полезным в случае, если в скрипте содержится много инструкций INSERT, которые могут содержать строки, имеющие тот же формат, что и обычные переменные, т. е. "$(имя_переменной)".

Параметры форматирования
-hзаголовки
Указывает количество строк для печати между заголовками столбцов. По умолчанию заголовки печатаются один раз для каждого набора результатов запроса. Этот параметр устанавливает переменную скрипта SQLCMDHEADERS программы sqlcmd. Используйте значение -1 для отмены печати заголовков. Любое недопустимое значение приводит к тому, что программа sqlcmd создает сообщение об ошибке и завершает свою работу.

-k [1 | 2]
Удаляет из выходных данных все управляющие символы, такие как символы табуляции и символы новой строки. Это сохраняет формат столбцов при возврате данных. При указании значения 1 управляющие символы заменяются одиночным пробелом. Если указано значение 2, все последовательные управляющие символы заменяются одиночным пробелом. Параметр -k аналогичен параметру -k1.

-sразделитель_столбцов
Задает символ-разделитель столбцов. Значением по умолчанию является пробел. Этот параметр устанавливает переменную скрипта SQLCMDCOLSEP программы sqlcmd. Чтобы использовать символы, имеющие специальное значение для операционной системы, такие как амперсанд (&) или точка с запятой (;), заключайте этот символ в кавычки ("). Разделитель столбцов может быть любым 8-разрядным символом.

-wширина_столбца
Задает ширину экрана для вывода. Этот параметр устанавливает переменную скрипта SQLCMDCOLWIDTH программы sqlcmd. Ширина столбца должна находиться в диапазоне от 8 до 65 536. Если указанное значение ширины столбца выходит за пределы указанного диапазона, программа sqlcmd выдает сообщение об ошибке. Ширина по умолчанию составляет 80 символов. Когда строка вывода превышает указанную ширину столбца, вывод переносится на следующую строку.

-W
Этот параметр удаляет конечные пробелы в столбце. При подготовке данных для экспорта в другое приложение указывайте этот параметр вместе с параметром -s . Не может указываться одновременно с параметром -y или -Y .

-yизменяемая_ширина_отображения
Этот параметр устанавливает переменную скрипта SQLCMDMAXVARTYPEWIDTH программы sqlcmd. Значение по умолчанию равно 256. Ограничивает число символов, возвращаемых для больших типов данных переменной длины:

  • varchar(max)

  • nvarchar(max)

  • varbinary(max)

  • xml

  • UDT (user-defined data types)

  • text

  • ntext

  • image

Примечание

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

Важно!

Используйте параметр -y 0 с особой осторожностью, поскольку при большом объеме возвращаемых данных может значительно снизиться производительность сервера и сети.

-Yфиксированная_ширина_отображения
Этот параметр устанавливает переменную скрипта SQLCMDMAXFIXEDTYPEWIDTH программы sqlcmd. Значение по умолчанию 0 (неограниченно). Ограничивает число символов, возвращаемых для следующих типов данных:

  • char(n), где 1<=n<=8000

  • nchar(nn), где 1<=n<=4000

  • varchar(nn), где 1<=n<=8000

  • nvarchar(nn), где 1<=n<=4000

  • varbinary(nn), где 1<=n<=4000

  • variant

Параметры отчетов об ошибках
-b
Указывает, что в случае ошибки программа sqlcmd завершает работу и возвращает значение DOS ERRORLEVEL. Значение, возвращаемое в переменную DOS ERRORLEVEL, равно 1, если сообщение об ошибке SQL Server имеет степень серьезности выше 10. В противном случае возвращаемое значение равно 0. Если параметр -V был указан вместе с параметром -b, программа sqlcmd не будет выдавать сообщение об ошибках, степень серьезности которых ниже значения, заданного параметром -V. Пакетные файлы командной строки могут быть использованы для проверки значения ERRORLEVEL и для обработки ошибки соответствующим образом. Программа sqlcmd не выдает сообщений об ошибках со степенью серьезности 10 (информационные сообщения).

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

-mуровень_ошибки
Управляет сообщениями об ошибках, отправляемыми в stdout. Передаются сообщения со степенью серьезности, которая больше заданной или равна ей. Если это значение равно -1, передаются все сообщения, в том числе информационные. Пробелы между параметрами -m и -1не допускаются. Например, -m-1 является допустимым, а -m-1 — нет.

Этот параметр также задает переменную скрипта sqlcmd SQLCMDERRORLEVEL. По умолчанию ее значение равно 0.

-Verror_severity_level
Управляет степенью серьезности, используемой для задания переменной ERRORLEVEL. Сообщения об ошибках со степенями серьезности, большими этого значения или равными ему, устанавливают переменную ERRORLEVEL. Значения меньше 0 сообщаются как 0. Пакетные файлы и CMD-файлы могут быть использованы для проверки значения переменной ERRORLEVEL.

Прочие параметры
-aразмер_пакета
Запрашивает пакет другого размера. Этот параметр устанавливает переменную скрипта SQLCMDPACKETSIZE программы sqlcmd. Значениеразмер_пакета должно находиться в диапазоне от 512 до 32767. Значение по умолчанию = 4096. Увеличение размера пакета повышает производительность выполнения скриптов, содержащих большое количество инструкций SQL между командами GO. Можно запросить больший размер пакета. Однако в случае, если запрос будет запрещен, программа sqlcmd использует размер пакета по умолчанию для сервера.

-cконец_пакета
Задает признак конца пакета. По умолчанию команды завершаются и отправляются в SQL Server при вводе слова GO в отдельной строке. При сбросе признака конца пакета не используйте зарезервированные ключевые слова или символы Transact-SQL, которые имеют специальное значение для операционной системы, даже если перед ними присутствует символ обратной косой черты.

-L[c]
Выводит список локально настроенных серверов и имена серверов, осуществляющих передачу данных в сети. Этот параметр не может использоваться в сочетании с другими параметрами. Максимальное число компьютеров серверов, которое можно указать, составляет 3 000. При усечении списка серверов в связи с нехваткой размера буфера выдается предупреждающее сообщение.

Примечание

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

Если указан необязательный параметр c , выходные данные отображаются без строки заголовка Servers: и каждая строка сервера отображается без пробелов в начале. Это называется «чистым выводом». Чистый выход улучшает производительность обработки языков скриптов.

-p[1]
Выводит на печать статистику производительности для каждого результирующего набора. Далее представлен пример формата для статистики производительности:

Network packet size (bytes): n

x xact[s]:

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

Где:

x = количество транзакций, обработанных SQL Server.

t1 = Общее время обработки всех транзакций.

t2 = среднее время обработки одной транзакции.

t3 = среднее количество транзакций, обрабатываемых в секунду.

Все значения времени приведены в миллисекундах.

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

Если необязательный параметр имеет любое значение, отличное от 1, возникает ошибка и sqlcmd завершается.

-X[1]
Отключает команды, которые могут поставить под угрозу безопасность системы при выполнении программы sqlcmd из пакетного файла. Отключенные команды по-прежнему распознаются. Программа sqlcmd выдает предупреждающее сообщение и продолжает работу. Если указан необязательный параметр 1 , sqlcmd создает сообщение об ошибке, а затем завершает работу. При использовании параметра -X происходит отключение следующих команд:

  • ED

  • !!command

Указание параметра -X блокирует передачу переменных среды программе sqlcmd. Он также препятствует выполнению скрипта запуска, указанного с помощью переменной скрипта SQLCMDINI. Дополнительные сведения о sqlcmd переменных скриптов см. в разделе Использование sqlcmd с переменными скрипта.

-?
Отображает сводку по синтаксису параметров программы sqlcmd.

Remarks

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

Если возвращается несколько результатов, программа sqlcmd выводит между результирующими наборами в пакете пустую строку. Кроме того, сообщение "<Затронутые строки x> " не отображается, если оно не применяется к выполненной инструкции.

Чтобы использовать sqlcmd его в интерактивном режиме, введите sqlcmd в командной строке любой из параметров, описанных выше в этом разделе. Дополнительные сведения см. в статье Использование программы sqlcmd

Примечание

Параметры -L, -Q, -Z или -i приводят sqlcmd к выходу после выполнения.

Суммарная длина командной строки программы sqlcmd в командной среде (Cmd.exe), включая все аргументы и расширение переменных, соответствует длине для программы Cmd.exe и определяется операционной системой.

Приоритет переменных (от низкого к высокому)

  1. Переменные среды системного уровня.

  2. Переменные среды пользовательского уровня.

  3. Командная оболочка (SET X=Y) задается в командной строке перед запуском sqlcmd.

  4. sqlcmd-v X=Y

  5. :Setvar X Y

Примечание

Чтобы просмотреть переменные среды, на панели управленияоткройте компонент Системаи перейдите на вкладку Дополнительно .

Переменные скрипта sqlcmd

Переменная Связанный параметр Чтение-запись По умолчанию
SQLCMDUSER -U R ""
SQLCMDPASSWORD -P -- ""
SQLCMDSERVER -S R "DefaultLocalInstance"
SQLCMDWORKSTATION -H R "ComputerName"
SQLCMDDBNAME -d R ""
SQLCMDLOGINTIMEOUT -l Чтение-запись "8" (секунд)
SQLCMDSTATTIMEOUT -T Чтение-запись "0" = неограниченное время ожидания
SQLCMDHEADERS -H Чтение-запись "0"
SQLCMDCOLSEP -S Чтение-запись " "
SQLCMDCOLWIDTH -w Чтение-запись "0"
SQLCMDPACKETSIZE -a R "4096"
SQLCMDERRORLEVEL -M Чтение-запись 0
SQLCMDMAXVARTYPEWIDTH -y Чтение-запись «256»
SQLCMDMAXFIXEDTYPEWIDTH -y Чтение-запись "0" = неограниченное время ожидания
SQLCMDEDITOR Чтение-запись "edit.com"
SQLCMDINI R ""

Переменные SQLCMDUSER, SQLCMDPASSWORD и SQLCMDSERVER устанавливаются при использовании команды :Connect

.

Пометка «Чтение» означает, что значение может быть задано только один раз в процессе инициализации программы.

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

Команды sqlcmd

Помимо инструкций Transact-SQL в sqlcmd, также доступны следующие команды:
GO [число] :List
[ : ] RESET :Error
[ : ] ED :Out
[:] !! :Perftrace
[ : ] QUIT :Connect
[ : ] EXIT :On Error
:r :Help
:ServerList :XML [ON | OFF]
:Setvar :Listvar

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

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

    Важно!

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

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

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

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

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

Команды изменения
[ : ] ED
Производит запуск текстового редактора. Этот редактор может использоваться для изменения текущего пакета Transact-SQL или последнего выполненного пакета. Для изменения последнего выполненного пакета необходимо ввести команду ED сразу после выполнения последнего пакета.

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

SET SQLCMDEDITOR=notepad

[ : ] RESET
Очистка кэша инструкций.

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

Переменные
:Setvar<Var> [ "value" ]
Определяет переменные скрипта sqlcmd. Переменные скрипта имеют следующий формат: $(VARNAME).

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

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

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

  • Явным образом, с помощью команды :Setvar .

  • Путем установки переменной среды до запуска программы sqlcmd.

Примечание

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

Команды контроля выполнения
:On Error[ exit | ignore]
Установка действия, выполняемого при возникновении ошибки во время исполнения скрипта или пакета.

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

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

[ : ] QUIT
Вызывает закрытие sqlcmd.

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

:EXIT(query)

Пример:

:EXIT(SELECT @@ROWCOUNT)

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

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

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

Если указан неверный запрос, программа sqlcmd завершит работу, не возвращая значения.

Список форматов инструкции EXIT:

  • :EXIT

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

  • :EXIT( )

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

  • :EXIT(query)

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

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

RAISERROR(50001, 10, 127)

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

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

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

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

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

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

Примечание

<Имени файла> считывается относительно каталога запуска, в котором sqlcmd был выполнен запуск.

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

Примечание

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

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

:Connectимя_сервера[\имя_экземпляра] [-l время_ожидания] [-U имя_пользователя [-P password]]
Соединяется с экземпляром SQL Server. Также закрывает текущее соединение.

Параметры времени ожидания:
0 ждать бесконечно
n>0 ждать в течение n секунд

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

Если не указан параметр timeout , то берется значение переменной SQLCMDLOGINTIMEOUT по умолчанию.

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

:connect myserver\instance1

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

:setvar myusername test

:setvar myservername myserver

:connect $(myservername) $(myusername)

[ : ] !!<команда>
Исполнение команд операционной системы. Чтобы выполнить команду операционной системы, начните строку с двух восклицательных знаков ( !! ) и далее укажите команду операционной системы. Пример:

:!! Dir

Примечание

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

:XML [ON | OFF]
Дополнительные сведения см. в подразделе «Формат выходных XML-данных» далее в этом разделе.

:Help
Выводит список команд программы sqlcmd вместе с кратким описанием каждой из них.

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

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

  • Для команд :Error, :Out и :Perftrace должно быть указано отдельное <filename> . Одинаковое <filename> может привести к смешиванию входных данных команд.

  • Если входной файл, вызываемый из программы sqlcmd на локальном компьютере, расположен на удаленном сервере и путь к этому файлу содержит букву диска (например, «:out c:\OutputFile.txt»), то выходной файл будет создан на локальном компьютере, а не на удаленном сервере.

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

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

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

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

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

sqlcmd

At the sqlcmd prompt type:

USE AdventureWorks2012;

GO

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

Формат вывода результатов выполнения запросов Transact-SQL

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

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

Запустите среду sqlcmd. Введите в командной строке: sqlcmd.

USE AdventureWorks2012;

SELECT TOP (2) BusinessEntityID, FirstName, LastName

FROM Person.Person;

GO

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

BusinessEntityID FirstName LastName

---------------- ------------ ----------

285 Syed Abbas

293 Catherine Abel

(2 row(s) affected)

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

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

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

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

Примечание

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

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

Команда GO не должна указываться раньше команды XML OFF, поскольку последняя возвращает sqlcmd в режим вывода с построчным форматированием.

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

Примечание

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

Рекомендации по использованию sqlcmd

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

  • Используйте встроенную безопасность.

  • В автоматических средах указывайте параметр -X.

  • Обеспечьте защиту входных и выходных файлов при помощи соответствующих разрешений файловой системы NTFS.

  • В целях повышения производительности выполняйте как можно больше работы в одном сеансе программы sqlcmd.

  • Задайте значение времени ожидания для выполнения пакетов или запросов выше, чем ожидаемое время их выполнения.

См. также:

Запуск программы sqlcmd
Выполнение файлов скрипта Transact-SQL с использованием программы sqlcmd
Использование программы sqlcmd
Использование программы sqlcmd с переменными скрипта
Подключение к компоненту Database Engine при помощи программы sqlcmd
Изменение скриптов SQLCMD при помощи редактора запросов
Управление шагами задания
Create a CmdExec Job Step