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

Применимо: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure azure Synapse Analytics Analytics Platform System (PDW)

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

• В командной строке.
• В режиме SQLCMD в редакторе запросов.
• В файле скрипта Windows.
• На шаге задания операционной системы (cmd.exe) агент SQL Server задания.

Узнайте, какая версия установлена

Существует две версии sqlcmd:

• Sqlcmd на основе sqlcmd, иногда в стиле go-sqlcmd.go-mssqldb Эта версия является автономным инструментом, который можно скачать независимо от SQL Server.

• Sqlcmd на основе ODBC, доступный в SQL Server или служебных программах командной строки Майкрософт, а также часть mssql-tools пакета в Linux.

Чтобы определить установленную версию, выполните следующую инструкцию в командной строке:

sqlcmd "-?"

sqlcmd "-?"

sqlcmd -?

Version: 1.3.1

Microsoft (R) SQL Server Command Line Tool
Version 16.0.4025.1 NT
Copyright (C) 2022 Microsoft Corporation. All rights reserved.

Скачивание и установка sqlcmd

Предустанавливается

Azure Cloud Shell

Вы можете попробовать служебную программу sqlcmd из Azure Cloud Shell, так как она предварительно установлена по умолчанию:

• Запуск Cloud Shell

Azure Data Studio

Чтобы запустить инструкции SQLCMD в Azure Data Studio, выберите "Включить SQLCMD" на панели инструментов редактора.

SQL Server Management Studio (SSMS)

Чтобы запустить инструкции SQLCMD в SQL Server Management Studio (SSMS), выберите режим SQLCMD в раскрывающемся списке меню навигации.

SSMS использует microsoft платформа .NET Framework SqlClient для выполнения в обычном и SQLCMD режиме в Редактор запросов. Когда sqlcmd вызывается из командной строки, sqlcmd использует драйвер ODBC. Так как различные параметры по умолчанию могут применяться, при выполнении одного и того же запроса в SSMS в режиме SQLCMD и в служебной программе sqlcmd может отображаться другое поведение.

Синтаксис

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.

sqlcmd
   -a packet_size
   -A (dedicated administrator connection)
   -b (terminate batch job if there is an error)
   -c batch_terminator
   -C (trust the server certificate)
   -d db_name
   -D
   -e (echo input)
   -E (use trusted connection)
   -f codepage | i:codepage[,o:codepage] | o:codepage[,i:codepage]
   -g (enable column encryption)
   -G (use Azure Active Directory for authentication)
   -h rows_per_header
   -H workstation_name
   -i input_file
   -I (enable quoted identifiers)
   -j (Print raw error messages)
   -k[1 | 2] (remove or replace control characters)
   -K application_intent
   -l login_timeout
   -L[c] (list servers, optional clean output)
   -m error_level
   -M multisubnet_failover
   -N (encrypt connection)
   -o output_file
   -p[1] (print statistics, optional colon format)
   -P password
   -q "cmdline query"
   -Q "cmdline query" (and exit)
   -r[0 | 1] (msgs to stderr)
   -R (use client regional settings)
   -s col_separator
   -S [protocol:]server[instance_name][,port]
   -t query_timeout
   -u (unicode output file)
   -U login_id
   -v var = "value"
   -V error_severity_level
   -w screen_width
   -W (remove trailing spaces)
   -x (disable variable substitution)
   -X[1] (disable commands, startup script, environment variables, optional exit)
   -y variable_length_type_display_width
   -Y fixed_length_type_display_width
   -z new_password
   -Z new_password (and exit)
   -? (usage)

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

Параметры, связанные с именем входа

-A

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

C-

Этот параметр используется клиентом, чтобы настроить его для неявного доверия сертификату сервера без проверки. Этот параметр аналогичен параметру ADO.NET TRUSTSERVERCERTIFICATE = true.

Для служебной программы sqlcmd (Go) также применяются следующие условия:

• Если -N и -C не предоставлены, sqlcmd согласовывает проверку подлинности с сервером без проверки сертификата сервера.
• Если -N указано, но -C нет, sqlcmd требует проверки сертификата сервера. false Значение шифрования по-прежнему может привести к шифрованию пакета входа.
• -N Если оба и -C указано, sqlcmd использует их значения для согласования шифрования.

-d db_name

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

-D

Интерпретирует имя сервера, предоставленное -S как dsN, вместо имени узла. Дополнительные сведения см. в статье о поддержке DSN в sqlcmd и bcp в connecting with sqlcmd.

-l login_timeout

Задает время ожидания (в секундах) при подключении программы sqlcmd через драйвер ODBC при попытке соединения с сервером. Этот параметр задает переменную SQLCMDLOGINTIMEOUTскриптов sqlcmd. Время ожидания по умолчанию для входа в sqlcmd составляет 8 секунд. При использовании -G параметра подключения к База данных SQL Azure или Azure Synapse Analytics и аутентификации с помощью идентификатора Microsoft Entra рекомендуется время ожидания не менее 30 секунд. Время ожидания входа должно быть числом между 0 и 65534. Если указанное значение не является числовым или не попадает в этот диапазон, sqlcmd создает сообщение об ошибке. Значение, указывающее 0 время ожидания, которое должно быть бесконечным.

E-

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

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

g-

Задает для параметра Enabledшифрования столбцов значение . Дополнительные сведения см. в разделе Постоянное шифрование. Поддерживаются только главные ключи, хранящиеся в хранилище сертификатов Windows. Для -g этого параметра требуется по крайней мере sqlcmd версии 13.1. Чтобы определить версию, выполните sqlcmd -?.

-G

Этот параметр используется клиентом при подключении к База данных SQL Azure или Azure Synapse Analytics, чтобы указать, что пользователь прошел проверку подлинности с помощью проверки подлинности Microsoft Entra. Этот параметр задает переменную SQLCMDUSEAAD = trueскриптов sqlcmd. Для -G этого параметра требуется по крайней мере sqlcmd версии 13.1. Чтобы определить версию, выполните sqlcmd -?. Дополнительные сведения см. в статье "Подключение к База данных SQL или Azure Synapse Analytics с помощью проверки подлинности Microsoft Entra". Параметр -A не поддерживается с параметром -G .

Параметр -G применяется только для Базы данных SQL Azure и Azure Synapse Analytics.

Интерактивная проверка подлинности Microsoft Entra в настоящее время не поддерживается в Linux или macOS. Для интегрированной проверки подлинности Microsoft Entra требуется Microsoft ODBC Driver 17 для SQL Server версии 17.6.1 или более поздней версии и правильно настроенная среда Kerberos.

Дополнительные сведения о проверке подлинности Microsoft Entra см. в разделе "Проверка подлинности Microsoft Entra" в sqlcmd.

-H workstation_name

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

-j

Выводит необработанные сообщения об ошибках на экран.

-K application_intent

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

-M multisubnet_failover

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

N-

Этот параметр используется клиентом для запроса зашифрованного подключения.

Для служебной -N программы sqlcmd (Go) теперь принимает строковое значение, которое может быть одним из trueвариантов falseшифрования.disable (default совпадает с пропуском параметра):

• Если -N и -C не предоставлены, sqlcmd согласовывает проверку подлинности с сервером без проверки сертификата сервера.
• Если -N указано, но -C нет, sqlcmd требует проверки сертификата сервера. false Значение шифрования по-прежнему может привести к шифрованию пакета входа.
• -N Если оба и -C указано, sqlcmd использует их значения для согласования шифрования.

-P password

Указанный пользователем пароль. В паролях учитывается регистр символов. -U Если параметр используется и -P параметр не используется, а SQLCMDPASSWORD переменная среды не задана, sqlcmd запрашивает у пользователя пароль. Мы не рекомендуем использовать пароль NULL (пустой), но можно указать пароль NULL с помощью пары смежных двойных кавычки для значения параметра ("").

Рекомендуется выбрать надежный пароль.

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

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

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

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

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

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

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

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

Пароль, содержащий специальные символы, может создать сообщение об ошибке. Вместо этого следует экранировать специальные символы при использовании -Pили использовать SQLCMDPASSWORD переменную среды.

-S [протокол:]server[\instance_name][,port]

Указывает экземпляр SQL Server, к которому выполняется подключение. Он задает переменную SQLCMDSERVERскрипта sqlcmd.

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

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

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

-U login_id

Имя входа или имя пользователя автономной базы данных. Для пользователей автономной базы данных необходимо указать параметр имени базы данных (-d).

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

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

-z new_password

Измените пароль:

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 new_password

Изменение пароля и выход:

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

Параметры ввода и вывода

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

Задает входные и выходные кодовые страницы. Номер кодовой страницы — это числовое значение, которое определяет установленную кодовую страницу Windows.

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

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

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

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

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

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

-i input_file[,input_file2...]

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

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

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

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

Этот параметр может использоваться несколько раз:

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

sqlcmd -i <input_file1> -i <input_file2>

-o output_file

Указывает файл, получающий выходные данные программы sqlcmd.

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

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

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

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

-r[0 | 1]

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

-R

Применяется только к ODBC sqlcmd .

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

u

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

Параметры выполнения запроса

-e

Записывает входные скрипты на стандартное выходное устройство (stdout).

I-

Применяется только к ODBC sqlcmd .

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

-q "cmdline query"

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

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

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;"

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

-Q "запрос cmdline"

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

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

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

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;"

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

-t query_timeout

Указывает время ожидания команды (или инструкции Transact-SQL). Этот параметр задает переменную SQLCMDSTATTIMEOUTскриптов sqlcmd. Если значение query_timeout не указано, команда не истекает. Query_timeout должен быть числом между 1 и 65534. Если указанное значение не является числовым или не попадает в этот диапазон, sqlcmd создает сообщение об ошибке.

-v var = value [ var = value... ]

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

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

Указывает, что программа sqlcmd не должна обрабатывать переменные скрипта. Этот параметр полезен, если скрипт содержит множество INSERT инструкций, которые могут содержать строки, которые имеют тот же формат, что и обычные переменные, например $(<variable_name>).

Параметры формата

-h заголовки

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

-k [1 | 2]

Удаляет из выходных данных все управляющие символы, такие как символы табуляции и символы новой строки. Этот параметр сохраняет формат столбцов при возврате данных.

• -k удаляет управляющие символы.
• -k1 заменяет каждый символ элемента управления пробелом.
• -k2 заменяет последовательные символы элемента управления одним пробелом.

-s col_separator

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

-w screen_width

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

-W

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

-y variable_length_type_display_width

Задает переменную скрипта sqlcmdSQLCMDMAXVARTYPEWIDTH. Значение по умолчанию — 256. Ограничивает число символов, возвращаемых для больших типов данных переменной длины:

• varchar(max)
• nvarchar(max)
• varbinary(max)
• xml
• определяемые пользователем типы данных (определяемые пользователем)
• text
• ntext
• Изображение

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

-Y fixed_length_type_display_width

Задает переменную скрипта sqlcmdSQLCMDMAXFIXEDTYPEWIDTH. Значение по умолчанию — ( 0 неограниченно). Ограничивает число символов, возвращаемых для следующих типов данных:

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

Параметры отчетов об ошибках

-b

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

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

-m error_level

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

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

-V error_severity_level

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

Прочие параметры

-a packet_size

Запрашивает пакет другого размера. Этот параметр задает переменную SQLCMDPACKETSIZEскриптов sqlcmd. packet_size должно быть значением между 512 и 32767. Значение по умолчанию — 4096. Больший размер пакета может повысить производительность выполнения скриптов с большим количеством инструкций Transact-SQL между GO командами. Можно запросить больший размер пакета. Но в случае отклонения запроса программа sqlcmd использует размер пакета по умолчанию для сервера.

-c batch_terminator

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

-L[c]

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

Если указан необязательный параметр 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
• !! команда

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

-?

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

Замечания

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

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

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

Общая длина командной строки sqlcmd в командной среде (например cmd.exe , или bash), включая все аргументы и развернутые переменные, определяется базовой операционной системой.

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

1. Переменные среды на уровне системы
2. Переменные среды пользовательского уровня.
3. Командная оболочка (SET X=Y) устанавливается в командной строке перед выполнением sqlcmd
4. sqlcmd -v X=Y
5. :Setvar X Y

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

SQLCMDUSER, SQLCMDPASSWORDи SQLCMDSERVER задаются при :Connect использовании.

R указывает, что значение может быть задано только один раз во время инициализации программы.

R/W указывает, что значение может быть изменено с помощью :setvar команды и последующих команд зависит от нового значения.

sqlcmd, команды

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

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

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

  Внимание

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

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

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

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

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

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

[:] ЭД

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

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

SET SQLCMDEDITOR=notepad

[:] СБРОС

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

Списки:

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

Переменные

:Setvar <var> [ "value" ]

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

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

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

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

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

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

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

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

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

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

:Listvar

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

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

: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 может отображаться несколько раз в скрипте.

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

:On Error [ exit | ignore ]

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

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

ignore При использовании параметра 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 определяет следующие дополнительные возвращаемые значения:

GO [число]

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

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

:r <filename>

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

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

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

:ServerList

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

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]]

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

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

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

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

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

:connect myserver\instance1

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

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

[:]!! command

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

:!! dir

:XML [ ON | OFF ]

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

Справка:

Перечисляет команды 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 перезаписывает существующие файлы с одинаковыми именами.

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

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

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

USE AdventureWorks2022;
GO

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

Changed database context to 'AdventureWorks2022'.

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

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

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

Запустите программу 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

Рекомендации по sqlcmd

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

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

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

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

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

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

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

• Используется -V16 для регистрации сообщений уровня серьезности 16. Сообщения серьезности 16 указывают на общие ошибки, которые могут быть исправлены пользователем.

• Проверьте код выхода и DOS ERRORLEVEL переменную после завершения процесса. sqlcmd возвращается 0 обычно, в противном случае он задает ERRORLEVEL значение, настроенное в соответствии с параметром -V. Другими словами, не должно быть того же значения, что и номер ошибки, ERRORLEVEL сообщаемого из SQL Server. Номер ошибки — это конкретное значение SQL Server, соответствующее системной функции @@ERROR. ERRORLEVEL— это значение, зависящее от sqlcmd, указывающее, почему sqlcmd завершен, и его значение зависит от указания -b аргумента командной строки.

Использование -V16 в сочетании с проверкой кода выхода и DOS ERRORLEVEL может помочь перехватывать ошибки в автоматизированных средах, особенно качественные шлюзы перед выпуском рабочей среды.

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

• Дополнительные сведения о новой служебной программе go-sqlcmd на GitHub
• Краткое руководство. Запуск образов контейнеров SQL Server Linux с помощью Docker
• sqlcmd — запуск служебной программы
• sqlcmd — выполнение файлов скриптов Transact-SQL
• sqlcmd — использование служебной программы
• sqlcmd — использование с переменными скриптов
• sqlcmd — подключение к ядру СУБД
• Изменение скриптов SQLCMD при помощи редактора запросов
• Управление шагами задания
• Create a CmdExec Job Step