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

SQL_COPT_SS_AUTOBEGINTXN

Версия 17.6+. Когда автофиксация отключена, управляет автоматическим выполнением BEGIN TRANSACTION после ROLLBACK или COMMIT.

SQL_COPT_SS_FALLBACK_CONNECT

Управляет использованием резервных подключений SQL Server. Больше не поддерживается.

Новые ключевые слова для строк подключения и атрибуты подключения

Проверка подлинности — SQL_COPT_SS_AUTHENTICATION

Задает режим проверки подлинности для соединения с SQL Server. Дополнительные сведения см. в разделе "Использование идентификатора Microsoft Entra".

ColumnEncryption — SQL_COPT_SS_COLUMN_ENCRYPTION

Управляет прозрачным шифрованием столбцов (Always Encrypted). Дополнительные сведения см. в статье Использование функции Always Encrypted с драйвером ODBC.

Шифрование

Указывает, используется ли для подключений шифрование протокола TLS по сети. Возможные значения: yes/mandatory(18.0+), no/optional(18.0+) и strict(18.0+). Значение по умолчанию — yes в версии 18.0+ и no в предыдущих версиях.

Независимо от установленного значения Encrypt, учетные данные входа на сервер (имя пользователя и пароль) всегда шифруются.

Параметры Encrypt, TrustServerCertificate и Force Encryption на стороне сервера играют роль в том, шифруются ли подключения в сети. В следующих таблицах показано действие этих параметров.

ODBC Driver 18 и более поздних версий

ODBC Driver 17 и более ранних версий

TransparentNetworkIPResolution — SQL_COPT_SS_TNIR

Управляет функцией "Разрешение IP-адресов прозрачной сети", которая взаимодействует с MultiSubnetFailover для ускорения повторных попыток подключения. Дополнительные сведения см. в статье Использование разрешения IP-адресов прозрачной сети.

UseFMTONLY

Управляет использованием параметра SET FMTONLY для метаданных при подключении к SQL Server 2012 и более поздних версий.

Репликация

Задает использование имени входа для репликации в драйвере ODBC версии 17.8 и более поздних версий.

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

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

Если формат сертификата — PFX и закрытый ключ внутри PFX-сертификата защищен паролем, требуется ввести пароль-ключ. Для сертификатов в PEM и форматах DER требуется атрибут ClientKey

ClientKey

Указывает расположение файла закрытого ключа или PEM DER сертификатов, указанных атрибутом ClientCertificate. Формат:

Если файл закрытого ключа защищен паролем, необходимо ввести пароль-ключ. Если пароль содержит какие-либо , символы, добавляется дополнительный , символ сразу после каждого из них. Например, если пароль указан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".

SQL_COPT_SS_CEKEYSTOREDATA

Взаимодействует с загруженной библиотекой поставщика хранилища ключей. См. описание атрибута, управляющего прозрачным шифрованием столбцов (Always Encrypted). Этот атрибут не имеет значения по умолчанию. Дополнительные сведения см. в статье Пользовательские поставщики хранилища ключей.

SQL_COPT_SS_CEKEYSTOREPROVIDER

Загружает библиотеку поставщика хранилища ключей для Always Encrypted или получает имена загруженных библиотек поставщиков хранилища ключей. Дополнительные сведения см. в статье Пользовательские поставщики хранилища ключей. Этот атрибут не имеет значения по умолчанию.

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

Дополнительные сведения о транзакциях XA см. в статье Использование транзакций XA.

SQL_COPT_SS_LONGASMAX

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

SQL_COPT_SS_SPID

Возвращает идентификатор серверного процесса соединения. Это свойство эквивалентно переменной T-SQL @@SPID, за исключением того, что оно не требует дополнительного кругового пути на сервер.