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

Мақала
08/23/2024

На этой странице перечислены ключевые слова для строк подключения и имен 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
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	Ср.
FailoverPartnerSPN	SQL_COPT_SS_FAILOVER_PARTNER_SPN	Ср.
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	Ср.
QueryLogFile	SQL_COPT_SS_PERF_QUERY_LOG	Ср.
QueryLogTIme	SQL_COPT_SS_PERF_QUERY_INTERVAL	Ср.
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	Ср.
StatsLogFile	SQL_COPT_SS_PERF_DATA_LOG	Ср.
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	Ср.
	SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE	Ср.
	SQL_ATTR_ASYNC_DBC_PCALLBACK	Ср.
	SQL_ATTR_ASYNC_DBC_PCONTEXT	Ср.
	SQL_ATTR_ASYNC_ENABLE	Ср.
	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	Ср.
	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_CONCAT_NULL	LMW
	SQL_COPT_SS_CONNECTION_DEAD	LMW
	SQL_COPT_SS_DATACLASSIFICATION_VERSION (версия 17.4.2+)	LMW
	SQL_COPT_SS_ENLIST_IN_DTC	Ср.
	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	Ср.
	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

Ниже приведены некоторые ключевые слова для строк подключения и атрибуты подключения, которые не описаны в статьях Использование ключевых слов строки подключения с 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

Бөлісу құралы: