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

На этой странице перечислены ключевые слова для строк подключения и имен DSN, а также атрибуты подключения для SQLSetConnectAttr и SQLGetConnectAttr, доступные в драйвере ODBC для SQL Server.

Поддерживаемые ключевые слова для имен DSN и строк подключения, а также атрибуты подключения

В следующей таблице перечислены доступные ключевые слова и атрибуты для каждой платформы (L: Linux; M: macOS; W: Windows). Чтобы получить дополнительные сведения, щелкните ключевое слово или атрибут.

Ниже приведены некоторые ключевые слова для строк подключения и атрибуты подключения, которые не описаны в статьях Использование ключевых слов строки подключения с SQL Server Native Client, SQLSetConnectAttr и Функция SQLSetConnectAttr.

Описание

Используется для описания источника данных.

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

ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL

Управляет использованием обработки NULL по стандарту ISO при объединении строк. Дополнительные сведения см. в разделе SET CONCAT_NULL_YIELDS_NULL (Transact-SQL).

Шифрование

Указывает, используется ли для подключений шифрование протокола 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

Управляет функцией Transparent Network IP Resolution, которая взаимодействует с 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, то есть соответствующее всему) помещается в конце, чтобы два более конкретных правила до него могли сопоставиться со своими запросами.

Сертификат клиента

Указывает сертификат, используемый для проверки подлинности при использовании loopback-подключений (доступно только в SQL Server для Linux). Доступные параметры:

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

ClientKey

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

Если файл закрытого ключа защищен паролем, необходимо ввести пароль-ключ. Если пароль содержит какие-либо , символы, добавляется дополнительный , символ сразу после каждого из них. Например, если пароль — a,b,c, экранированный пароль в строке подключения — a,,b,,c.

Имя узла в сертификате

Позволяет указать имя узла, ожидаемое в сертификате сервера при согласовании шифрования, если это имя отличается от значения по умолчанию, производного от Addr/Address/Server. Параметр HostnameInCertificate игнорируется при использовании параметра ServerCertificate.

Предпочтение IP-адреса

Этот параметр доступен начиная с версии 18.1. Он позволяет указать тип IP-адреса, который должен считаться приоритетным для подключений. Возможные варианты: "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]". UsePlatformDefault подключается к адресам в том порядке, в который они предоставляются системным вызовом для разрешения имени сервера. Значение по умолчанию — IPv4First (как и в предыдущих версиях).

Сертификат сервера

Этот параметр доступен начиная с версии 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-транзакций с диспетчером транзакций (TP), совместимым с 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

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

SQL_COPT_SS_SPID

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