Ескертпе
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Жүйеге кіруді немесе каталогтарды өзгертуді байқап көруге болады.
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Каталогтарды өзгертуді байқап көруге болады.
На этой странице перечислены ключевые слова для строк подключения и имен 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 | Включает только расшифровку (результатов и возвращаемых значений). |
ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL
Управляет использованием обработки NULL по стандарту ISO при объединении строк. Дополнительные сведения см. в разделе SET CONCAT_NULL_YIELDS_NULL (Transact-SQL).
| Значение ключевого слова | Значение атрибута | Description |
|---|---|---|
| Да | SQL_CN_ON | (по умолчанию) Объединение NULL дает значение NULL. |
| No | SQL_CN_OFF | Сцепление NULL дает строку. |
Шифрование
Указывает, используется ли для подключений шифрование протокола 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 | Да | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| No | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | No | Да | Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Да | Да | Да | Сертификат сервера не проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
| Strict | - | - | TrustServerCertificate игнорируется. Сертификат сервера проверяется. Данные, передаваемые между клиентом и сервером, шифруются. |
Примечание.
Режим Strict доступен только для серверов, поддерживающих подключения по протоколу TDS 8.0.
ODBC Driver 17 и более ранних версий
| Параметр шифрования | Надежный сертификат сервера | Принудительное шифрование на стороне сервера | Результат |
|---|---|---|---|
| No | No | 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
Указывает сертификат, используемый для проверки подлинности с подключениями обратного цикла (доступен только в SQL Server в Linux). Доступные параметры:
| Значение параметра | Description |
|---|---|
sha1:<hash_value> |
Для поиска сертификата в Хранилище Сертификатов Windows драйвер ODBC использует хэш SHA1. |
subject:<subject> |
Для поиска сертификата в Хранилище Сертификатов Windows драйвер ODBC использует тему. |
file:<file_location>[,password:<password>] |
Драйвер ODBC использует файл сертификата. |
Если формат сертификата — PFX и закрытый ключ внутри PFX-сертификата защищен паролем, требуется ввести пароль-ключ. Для сертификатов в PEM и форматах DER требуется атрибут ClientKey
ClientKey
Указывает расположение файла закрытого ключа или PEMDER сертификатов, указанных атрибутом 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);
| значение | Description | Платформы |
|---|---|---|
| Объект 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 |