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

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

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

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

Ключевое слово DSN / строки подключения Атрибут подключения Платформа
Addr LMW
Адрес LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
Аутентификация SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConcatNullYieldsNull (v18.6+) SQL_COPT_SS_CONCAT_NULL LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
База данных SQL_ATTR_CURRENT_CATALOG LMW
Description LMW
Драйвер LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (версия 18.0 и выше) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (версия 18.0 и выше) LMW
IpAddressPreference (версия 18.1 и выше) LMW
KeepAlive (версия 17.4+, DSN только до версии 17.8) LMW
KeepAliveInterval (версия 17.4+, DSN только до версии 17.8) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Язык LMW
LongAsMax (версия 18.0 и выше) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Сеть LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
Репликация LMW
RetryExec (версия 18.1 и выше) LMW
SaveFile LMW
Сервер LMW
ServerCertificate (версия 18.1 и выше) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.4.2+) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (версия 17.5+) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

Вот некоторые ключевые слова строки подключения и атрибуты подключения, которые не описаны в Using Connection String Keywords with SQL Server Native Client, SQLSetConnectAttr и SQLSetConnectAttr Function.

Описание

Описывает источник данных.

SQL_COPT_SS_ANSI_OEM

Управляет преобразованием данных из ANSI в OEM.

Значение атрибута Описание
SQL_AO_OFF (по умолчанию) Перевод не сделан.
SQL_AO_ON Перевод выполнен.

SQL_COPT_SS_AUTOBEGINTXN

Начиная с версии 17.6, когда автокоммит отключён, используйте эту опцию для управления автоматическим BEGIN TRANSACTION после ROLLBACK или COMMIT.

Значение атрибута Описание
SQL_AUTOBEGINTXN_ON (по умолчанию) Автоматически BEGIN TRANSACTION после ROLLBACK или COMMIT.
SQL_AUTOBEGINTXN_OFF Нет автоматического BEGIN TRANSACTION после ROLLBACK или COMMIT.

SQL_COPT_SS_FALLBACK_CONNECT

Контролирует использование запасных соединений SQL Server. Эта опция больше не поддерживается.

Значение атрибута Описание
SQL_FB_OFF (по умолчанию) Отключает запасные соединения.
SQL_FB_ON Включает резервные соединения.

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

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

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

Значение ключевого слова Значение атрибута Описание
SQL_AU_NONE (по умолчанию) Не установлено . Режим проверки подлинности определяется сочетанием других атрибутов.
SqlPassword SQL_AU_PASSWORD Проверка подлинности SQL Server (с использованием имени пользователя и пароля).
ActiveDirectoryIntegrated SQL_AU_AD_INTEGRATED Интегрированная аутентификация Microsoft Entra.
ActiveDirectoryInteractive SQL_AU_AD_INTERACTIVE Интерактивная аутентификация Microsoft Entra.
ActiveDirectoryMsi SQL_AU_AD_MSI Аутентификация с использованием управляемого удостоверения Microsoft Entra. Для назначаемого пользователем удостоверения UID задается как идентификатор объекта этого удостоверения.
ActiveDirectoryServicePrincipal SQL_AU_AD_SPA Проверка подлинности субъекта-службы Microsoft Entra. UID устанавливается на идентификатор клиента принципала сервиса. PWD имеет значение «клиентский секрет».
ActiveDirectoryPassword SQL_AU_AD_PASSWORD [УСТАРЕВШЕЕ] Аутентификация паролей Microsoft Entra.

ActiveDirectoryPassword не рекомендуется к использованию. Дополнительные сведения см. в статье ActiveDirectoryPassword устарел.
SQL_AU_RESET Не задано. Переопределяет любые параметры DSN или строки подключения.

Примечание.

При использовании ключевого слова или атрибута Authentication явно задайте для параметра Encrypt нужное значение в строке подключения, DSN или атрибуте подключения. Подробные сведения см. в статье Использование ключевых слов строки подключения в SQL Server Native Client.

ColumnEncryption — SQL_COPT_SS_COLUMN_ENCRYPTION

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

Значение ключевого слова Значение атрибута Описание
Enabled SQL_CE_ENABLED Включает функцию Always Encrypted.
Disabled (по умолчанию) SQL_CE_DISABLED Отключает Always Encrypted.
SQL_CE_RESULTSETONLY Включает только расшифровку (результатов и возвращаемых значений).

ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL

Управляет использованием обработки NULL по ISO при конкатенации строк. Дополнительные сведения см. в разделе SET CONCAT_NULL_YIELDS_NULL.

Значение ключевого слова Значение атрибута Описание
Yes (по умолчанию) 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 и новее

Параметр шифрования Надежный сертификат сервера Принудительное шифрование на стороне сервера Результат
Нет Нет Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, не шифруются.
Нет Да Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, не шифруются.
Да Нет Нет Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Да Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Нет Нет Да Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Нет Да Да Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Нет Да Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Да Да Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Строгий - - TrustServerCertificate не учитывается. Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.

Примечание.

Это Strict значение доступно только на серверах, поддерживающих соединения TDS 8.0.

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

Параметр шифрования Надежный сертификат сервера Принудительное шифрование на стороне сервера Результат
Нет Нет Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, не шифруются.
Нет Да Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, не шифруются.
Да Нет Нет Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Да Нет Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Нет Нет Да Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Нет Да Да Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Нет Да Сертификат сервера проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.
Да Да Да Сертификат сервера не проверяется.
Данные, передаваемые между клиентом и сервером, шифруются.

TransparentNetworkIPResolution — SQL_COPT_SS_TNIR

Управляет функцией Transparent Network IP Resolution — устаревшей много-IP резервной версией драйвера ODBC. Этот параметр не влияет на последовательность установления соединения при использовании MultiSubnetFailover=Yes, что рекомендуется для База данных SQL Azure, Управляемый экземпляр SQL Azure, баз данных SQL в Microsoft Fabric, прослушивателей групп доступности и экземпляров отказоустойчивого кластера. Для получения дополнительной информации см . Использование прозрачного сетевого IP-разрешения с драйвером ODBC или Высокая доступность и аварийное восстановление.

Значение ключевого слова Значение атрибута Описание
Enabled (по умолчанию) SQL_IS_ON Обеспечивает прозрачное разрешение сетевых IP-адресов.
Disabled SQL_IS_OFF Отключает разрешение IP-адресов для прозрачной сети.

UseFMTONLY

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

Значение ключевого слова Описание
No (по умолчанию) Используйте sp_describe_first_result_set для метаданных, если они доступны.
Yes Используется SET FMTONLY для метаданных.

Репликация

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

Значение ключевого слова Описание
No (по умолчанию) Репликационный логин не используется.
Yes Триггеры с параметром NOT FOR REPLICATION не запускают подключение.

RetryExec

Настраиваемая логика повторных попыток доступна начиная с версии 18.1. Она автоматически повторно выполняет определенные вызовы функций ODBC на основе настраиваемых условий. Включите эту функцию через строка подключения, используя RetryExec ключевое слово вместе со списком правил повторных попыток. Каждое правило повторной попытки состоит из трёх компонентов, разделённых двоеточием: совпадения ошибок, политики повторной попытки и совпадения запроса.

Соответствие запросу определяет правило повторной попытки, используемое для заданного выполнения. Он совпадает с входящим текстом команды (SQLExecDirect) или подготовленным текстом команды в объекте инструкции (SQLExecute). Если совпадает более одного правила, используется первое правило сопоставления в списке. Такое поведение позволяет перечислять правила в порядке возрастания степени общности. Если ни одно правило не совпало, повторная попытка не выполняется.

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

Значение RetryExec ключевого слова — это список правил повторных попыток с точками с запятой.
RetryExec={rule1;rule2}

Правило повторной попытки выглядит так: <errormatch>:<retrypolicy>:<querymatch>

  • Совпадение ошибок: список кодов ошибок, разделённый запятой. Например, указание 1000,2000 перечисляет коды ошибок, которые вы хотите попробовать снова.

  • Политика повторных попыток: указывает задержку до следующей попытки. Первый параметр — это количество повторов, второй — задержка. Например, 3,10+7 означает три попытки, начинающиеся с 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}

Разместите наиболее общее правило (подходящее для всех случаев) в конце, чтобы два более конкретных правила до него могли сопоставиться каждое со своим запросом.

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

Задает сертификат, используемый для аутентификации при локальных (loopback) соединениях. Эта опция доступна только в SQL Server на Linux. Доступные параметры:

Значение параметра Описание
sha1:<hash_value> Драйвер ODBC использует хэш SHA1 для поиска сертификата в хранилище сертификатов Windows.
subject:<subject> Драйвер ODBC использует объект для поиска сертификата в Хранилище сертификатов Windows.
file:<file_location>[,password:<password>] Драйвер ODBC использует файл сертификата.

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

ClientKey

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

Значение параметра Описание
file:<file_location>[,password:<password>] Указывает местоположение файла приватного ключа.

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

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

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

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

Начиная с версии 18.1, используйте эту опцию для указания типа IP-адреса для приоритетов для соединений.

Возможные варианты: IPv4First, IPv6First, и UsePlatformDefault. UsePlatformDefault Подключается к адресам в порядке, в котором они предоставляются системным вызовом, чтобы разрешить имя сервера. Значение по умолчанию — IPv4First, что соответствует поведению в предыдущих версиях.

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

Начиная с версии 18.1, используйте эту опцию с строгим режимом шифрования. Используйте ключевое слово ServerCertificate, чтобы указать путь к файлу сертификата для сопоставления с сертификатом TLS/SSL SQL Server. Сопоставление происходит вместо стандартной проверки сертификатов (срок действия, имя хоста, цепочка доверия и т.д.). Допустимые форматы сертификатов: PEMи DERCER. Если указан этот параметр, сертификат SQL Server проверяется на предмет того, является ли значение, указанное в ServerCertificate, точным совпадением.

SQL_COPT_SS_ACCESS_TOKEN

Используйте токен доступа Microsoft Entra для аутентификации. Дополнительные сведения см. в разделе Использование Microsoft Entra ID с драйвером ODBC.

Значение атрибута Описание
NULL (по умолчанию) Токен доступа не предоставляется.
ACCESSTOKEN* Указатель на маркер доступа.

SQL_COPT_SS_CEKEYSTOREDATA

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

Значение атрибута Описание
CEKEYSTOREDATA * Структура данных взаимодействия для библиотеки поставщика хранилища ключей.

SQL_COPT_SS_CEKEYSTOREPROVIDER

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

Значение атрибута Описание
char * Путь к библиотеке поставщика хранилища ключей

SQL_COPT_SS_ENLIST_IN_XA

Чтобы включить транзакции XA с XA-совместимым процессором транзакций (TP), приложению необходимо вызвать 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

Отправляет длинные типы данных на серверы как максимальные типы данных.

Значение атрибута Описание
No (по умолчанию) Не конвертируйте длинные типы в максимальные при отправке.
Yes Конвертируйте данные из длинных типов в максимальные при отправке.

SQL_COPT_SS_SPID

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

Значение атрибута Описание
DWORD SPID