Ключевые слова и атрибуты строки подключения и имени DSN
На этой странице перечислены ключевые слова для строк подключения и имен DSN, а также атрибуты подключения для SQLSetConnectAttr и SQLGetConnectAttr, доступные в драйвере ODBC для SQL Server.
Поддерживаемые ключевые слова для имен DSN и строк подключения, а также атрибуты подключения
В следующей таблице перечислены доступные ключевые слова и атрибуты для каждой платформы (L: Linux; M: macOS; W: Windows). Чтобы получить дополнительные сведения, щелкните ключевое слово или атрибут.
Ниже приведены некоторые ключевые слова для строк подключения и атрибуты подключения, которые не описаны в статьях Использование ключевых слов строки подключения с SQL Server Native Client, SQLSetConnectAttr и Функция SQLSetConnectAttr.
Description
Используется для описания источника данных.
SQL_COPT_SS_ANSI_OEM
Управляет преобразованием данных из ANSI в OEM.
| Значение атрибута | Description |
|---|---|
| SQL_AO_OFF | (По умолчанию) Преобразование не выполнено. |
| SQL_AO_ON | Преобразование выполнено. |
SQL_COPT_SS_AUTOBEGINTXN
Версия 17.6+. Когда автофиксация отключена, управляет автоматическим выполнением BEGIN TRANSACTION после ROLLBACK или COMMIT.
| Значение атрибута | Description |
|---|---|
| SQL_AUTOBEGINTXN_ON | (По умолчанию.) BEGIN TRANSACTION выполняется автоматически после ROLLBACK или COMMIT. |
| SQL_AUTOBEGINTXN_OFF | BEGIN TRANSACTION не выполняется автоматически после ROLLBACK или COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Управляет использованием резервных подключений SQL Server. Больше не поддерживается.
| Значение атрибута | Description |
|---|---|
| SQL_FB_OFF | (По умолчанию) Резервные подключения отключены. |
| SQL_FB_ON | Резервные подключения включены. |
Новые ключевые слова для строк подключения и атрибуты подключения
Проверка подлинности — SQL_COPT_SS_AUTHENTICATION
Задает режим проверки подлинности для соединения с SQL Server. Дополнительные сведения см. в разделе "Использование идентификатора Microsoft Entra".
| Значение ключевого слова | Значение атрибута | Description |
|---|---|---|
| SQL_AU_NONE | (По умолчанию) Не задано. Режим проверки подлинности определяется сочетанием других атрибутов. | |
| SqlPassword | SQL_AU_PASSWORD | Проверка подлинности SQL Server (с использованием имени пользователя и пароля). |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Встроенная проверка подлинности Microsoft Entra. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Проверка подлинности паролей Microsoft Entra. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Интерактивная проверка подлинности Microsoft Entra. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Проверка подлинности управляемого удостоверения Microsoft Entra. Для назначенного пользователем удостоверения в качестве идентификатора пользователя задается идентификатор объекта удостоверения пользователя. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Проверка подлинности субъекта-службы Microsoft Entra. В качестве UID задается идентификатор клиента субъекта-службы. В качестве PWD задается секрет клиента. |
| SQL_AU_RESET | Сброс. Переопределяет любой параметр имени DSN или строки подключения. |
Примечание.
При использовании ключевого слова или атрибута Authentication явно присвойте параметру Encrypt нужное значение в строке подключения, имени DSN или атрибуте подключения. Подробные сведения см. в статье Использование ключевых слов строки подключения с собственным клиентом SQL Server.
ColumnEncryption — SQL_COPT_SS_COLUMN_ENCRYPTION
Управляет прозрачным шифрованием столбцов (Always Encrypted). Дополнительные сведения см. в статье Использование функции Always Encrypted с драйвером ODBC.
| Значение ключевого слова | Значение атрибута | Description |
|---|---|---|
| Включено | SQL_CE_ENABLED | Включает функцию Always Encrypted. |
| Выключено | SQL_CE_DISABLED | (По умолчанию) Отключает функцию Always Encrypted. |
| SQL_CE_RESULTSETONLY | Включает только расшифровку (результатов и возвращаемых значений). |
Шифрование
Указывает, используется ли для подключений шифрование протокола TLS по сети. Возможные значения: yes/mandatory(18.0+), no/optional(18.0+) и strict(18.0+). Значение по умолчанию — yes в версии 18.0+ и no в предыдущих версиях.
Независимо от установленного значения Encrypt, учетные данные входа на сервер (имя пользователя и пароль) всегда шифруются.
Параметры Encrypt, TrustServerCertificate и Force Encryption на стороне сервера играют роль в том, шифруются ли подключения в сети. В следующих таблицах показано действие этих параметров.
ODBC Driver 18 и более поздних версий
| Параметр шифрования | Надежный сертификат сервера | Принудительное шифрование на стороне сервера | Результат |
|---|---|---|---|
| No | No | No | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, не шифруются. |
| No | Да | Нет | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, не шифруются. |
| Да | No | No | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | Да | Нет | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| No | No | Да | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| No | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | No | Да | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Strict | - | - | TrustServerCertificate игнорируется. Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
Примечание.
Режим Strict доступен только для серверов, поддерживающих подключения по протоколу TDS 8.0.
ODBC Driver 17 и более ранних версий
| Параметр шифрования | Надежный сертификат сервера | Принудительное шифрование на стороне сервера | Результат |
|---|---|---|---|
| No | No | No | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, не шифруются. |
| No | Да | Нет | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, не шифруются. |
| Да | No | No | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | Да | Нет | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| No | No | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| No | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | No | Да | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
TransparentNetworkIPResolution — SQL_COPT_SS_TNIR
Управляет функцией "Разрешение IP-адресов прозрачной сети", которая взаимодействует с MultiSubnetFailover для ускорения повторных попыток подключения. Дополнительные сведения см. в статье Использование разрешения IP-адресов прозрачной сети.
| Значение ключевого слова | Значение атрибута | Description |
|---|---|---|
| Включено | SQL_IS_ON | (По умолчанию). Включает разрешения IP-адресов прозрачной сети. |
| Выключено | SQL_IS_OFF | Отключает разрешения IP-адресов прозрачной сети. |
UseFMTONLY
Управляет использованием параметра SET FMTONLY для метаданных при подключении к SQL Server 2012 и более поздних версий.
| Значение ключевого слова | Description |
|---|---|
| No | (По умолчанию) Для метаданных (при их наличии) используется процедура sp_describe_first_result_set. |
| Да | Для метаданных используется параметр SET FMTONLY. |
Репликация
Задает использование имени входа для репликации в драйвере ODBC версии 17.8 и более поздних версий.
| Значение ключевого слова | Description |
|---|---|
| No | (по умолчанию) Имя входа репликации не используется. |
| Да | Триггеры с параметром NOT FOR REPLICATION не запускают подключение. |
RetryExec
Настраиваемая логика повторных попыток доступна начиная с версии 18.1. Она автоматически повторно выполняет определенные вызовы функций ODBC на основе настраиваемых условий. Эту функцию можно включить в строке подключения, используя ключевое слово RetryExec и список правил повторных попыток. Каждое правило повторных попыток содержит три компонента, разделенных двоеточием: сопоставляемая ошибка, политика повтора и сопоставляемый запрос.
Сопоставляемый запрос определяет, какое правило повторных попыток будет использоваться для определенного выполнения, и сопоставляется с входящим текстом команды (SQLExecDirect) или подготовленным текстом команды в объекте инструкции (SQLExecute). В случае соответствия нескольким правилам будет использоваться первое соответствие в списке. Это поведение позволяет перечислять правила в порядке увеличения общего характера. В случае несоответствия ни одному из правил повторная попытка не применяется.
Если выполнение приводит к ошибке, и существует применимое правило повторных попыток, его совпадение с ошибкой используется для определения необходимости извлечения выполнения.
Значение ключевого слова RetryExec — это список правил с запятой, разделенных повторными попытками.
RetryExec={rule1;rule2}
Правило повторной попытки выглядит так: <errormatch>:<retrypolicy>:<querymatch>
Совпадение ошибок: разделенный запятыми список кодов ошибок. Например, значение 1000,2000 будет указывать на коды ошибок, для которых следует выполнить повторную попытку.
Политика повтора — указывает задержку до выполнения следующей повторной попытки. Первый параметр определяет число повторных попыток, а второй — задержку. Например, 3,10+7 будет 3 попытки, начиная с 10, и каждая следующая повторная попытка будет увеличиваться на 7 секунд. Если значение +7 не указано, каждая следующая повторная попытка экспоненциально удвоится.
Сопоставляемый запрос — позволяет указать запрос для сопоставления. Если ничего не указано, то правило применяется ко всем запросам. Указание SELECT будет означать, что правило применяется ко всем запросами, которые начинаются с SELECT.
Объединение всех трех перечисленных выше компонентов для использования в строка подключения будет следующим:
RetryExec={1000,2000:3,10+7:SELECT}
Это означает следующее: для ошибок 1000 и 2000 в запросе, который начинается с SELECT, Повторите попытку дважды с начальной задержкой в 10 секунд и добавьте 7 секунд для каждой следующей попытки"
Примеры
40501,40540:4,5
Для ошибок 40501 и 40540 повторите попытку до четырех раз с начальной задержкой в 5 секунд и экспоненциальным удвоением между каждой повторной попыткой. Это правило применяется ко всем запросам.
49919:2,10+:CREATE
Для ошибки 49919 в запросе, который начинается с CREATE, повторите попытку не более двух раз, сначала после 10 секунд, а затем 20 секунд.
49918,40501,10928:5,10+5:SELECT c1
Для ошибок, 49918, 40501 и 10928 для запросов, начиная с SELECT c1, повторите попытку до пяти раз, ожидая 10 секунд на первом повторе и увеличивая ожидание на 5 секунд после этого.
Приведенные выше три правила можно указать вместе в строка подключения следующим образом:
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
Наиболее общее правило (match-all) помещается в конец, чтобы разрешить два более конкретных правила, прежде чем он будет соответствовать соответствующим запросам.
ClientCertificate
Указывает сертификат, который будет использоваться для аутентификации. Доступные параметры:
| Значение параметра | Description |
|---|---|
sha1:<hash_value> |
Для поиска сертификата в Хранилище Сертификатов Windows драйвер ODBC использует хэш SHA1. |
subject:<subject> |
Для поиска сертификата в Хранилище Сертификатов Windows драйвер ODBC использует тему. |
file:<file_location>[,password:<password>] |
Драйвер ODBC использует файл сертификата. |
Если формат сертификата — PFX и закрытый ключ внутри PFX-сертификата защищен паролем, требуется ввести пароль-ключ. Для сертификатов в PEM и форматах DER требуется атрибут ClientKey
ClientKey
Указывает расположение файла закрытого ключа или PEM DER сертификатов, указанных атрибутом ClientCertificate. Формат:
| Значение параметра | Description |
|---|---|
file:<file_location>[,password:<password>] |
Указывает расположение файла закрытого ключа. |
Если файл закрытого ключа защищен паролем, необходимо ввести пароль-ключ. Если пароль содержит какие-либо , символы, добавляется дополнительный , символ сразу после каждого из них. Например, если пароль указанa,b,c, экранированный пароль присутствует в строка подключенияa,,b,,c.
HostnameInCertificate
Позволяет указать имя узла, ожидаемое в сертификате сервера при согласовании шифрования, если это имя отличается от значения по умолчанию, производного от Addr/Address/Server. Параметр HostnameInCertificate игнорируется при использовании параметра ServerCertificate.
IpAddressPreference
Этот параметр доступен начиная с версии 18.1. Он позволяет указать тип IP-адреса, который должен считаться приоритетным для подключений. Возможные варианты: "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]". UsePlatformDefault подключается к адресам в том порядке, в который они предоставляются системным вызовом для разрешения имени сервера. Значение по умолчанию — IPv4First (как и в предыдущих версиях).
ServerCertificate
Этот параметр доступен начиная с версии 18.1. Его можно использовать со строгим режимом шифрования. Ключевое слово ServerCertificate используется для указания пути к файлу сертификата, который будет сравниваться с TLS/SSL-сертификатом SQL Server. Совпадение выполняется вместо стандартной проверки сертификата (срок действия, имя узла, цепочка доверия и т. д.) Допустимые форматы сертификатов : PEM, DER и CER. Если этот параметр указан, проверяется, полностью ли соответствует предоставленный сертификат ServerCertificate сертификату SQL Server.
SQL_COPT_SS_ACCESS_TOKEN
Позволяет использовать маркер доступа Microsoft Entra для проверки подлинности. Дополнительные сведения см. в разделе "Использование идентификатора Microsoft Entra".
| Значение атрибута | Description |
|---|---|
| NULL | (По умолчанию) Маркер доступа не предоставлен. |
| ACCESSTOKEN* | Указатель на маркер доступа. |
SQL_COPT_SS_CEKEYSTOREDATA
Взаимодействует с загруженной библиотекой поставщика хранилища ключей. См. описание атрибута, управляющего прозрачным шифрованием столбцов (Always Encrypted). Этот атрибут не имеет значения по умолчанию. Дополнительные сведения см. в статье Пользовательские поставщики хранилища ключей.
| Значение атрибута | Description |
|---|---|
| CEKEYSTOREDATA * | Структура данных взаимодействия для библиотеки поставщика хранилища ключей. |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Загружает библиотеку поставщика хранилища ключей для Always Encrypted или получает имена загруженных библиотек поставщиков хранилища ключей. Дополнительные сведения см. в статье Пользовательские поставщики хранилища ключей. Этот атрибут не имеет значения по умолчанию.
| Значение атрибута | Description |
|---|---|
| char * | Путь к библиотеке поставщика хранилища ключей |
SQL_COPT_SS_ENLIST_IN_XA
Чтобы включить транзакции XA с совместимым с XA обработчиком транзакций, приложение должно вызвать функцию SQLSetConnectAttr с атрибутом SQL_COPT_SS_ENLIST_IN_XA и указателем на объект XACALLPARAM. Этот параметр поддерживается в Windows (17.3+), Linux и macOS.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Чтобы связать транзакцию XA только с подключением ODBC, при вызове функции SQLSetConnectAttr укажите значение TRUE или FALSE с атрибутом SQL_COPT_SS_ENLIST_IN_XA вместо указателя. Этот параметр действует только в Windows. Таким образом, нельзя настроить операции XA через клиентское приложение.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| значение | Описание | Платформы |
|---|---|---|
| Объект XACALLPARAM * | Указатель на объект XACALLPARAM. |
Windows, Linux и macOS |
| TRUE | Связывает транзакцию XA с подключением ODBC. Все связанные действия базы данных выполняются под защитой транзакции XA. | Windows |
| FALSE | Отменяет связь транзакции с подключением ODBC. | Windows |
Дополнительные сведения о транзакциях XA см. в статье Использование транзакций XA.
SQL_COPT_SS_LONGASMAX
Позволяет отправлять на серверы данные с типом "длинное целое" как данные с типом max.
| Значение атрибута | Description |
|---|---|
| No | (По умолчанию) Типы данных "длинное целое" не преобразовываются в типы данных max при отправке. |
| Да | Данные с типом "длинное целое" преобразовываются в данные с типом max при отправке. |
SQL_COPT_SS_SPID
Возвращает идентификатор серверного процесса соединения. Это свойство эквивалентно переменной T-SQL @@SPID, за исключением того, что оно не требует дополнительного кругового пути на сервер.
| Значение атрибута | Description |
|---|---|
| DWORD | SPID |