Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
В этой статье перечислены ключевые слова для строк соединения и DSN, а также атрибуты соединения для SQLSetConnectAttr и SQLGetConnectAttr, доступные в драйвере ODBC для SQL Server.
Поддерживаемые ключевые слова DSN и строка подключения и атрибуты соединения
В следующей таблице перечислены доступные ключевые слова и атрибуты для каждой платформы (L: Linux; M: macOS; W: Windows). Чтобы получить дополнительные сведения, щелкните ключевое слово или атрибут.
Вот некоторые ключевые слова строки подключения и атрибуты подключения, которые не описаны в 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 |