Установите свойства подключения

Скачать драйвер JDBC

Свойства строка подключения можно указать различными способами:

• В качестве <name>=<value> свойств в URL-адресе подключения при подключении с помощью класса DriverManager. Синтаксис строки подключения описан в разделе Создание URL-адреса подключения.

• В качестве <name>=<value> свойств в параметре Propertiesметода Connect в классе DriverManager.

• С помощью аргумента соответствующего метода задания свойств источника данных драйвера. Например:

  datasource.setServerName(value)
  datasource.setDatabaseName(value)
  

Замечания

• Имена свойств не учитывает регистр. Драйвер разрешает повторяющиеся имена свойств в следующем порядке:

  1. Аргументы API, такие как user и password
  2. Коллекция свойств
  3. Последний экземпляр в строке подключения

• Для имен свойств можно использовать неизвестные значения. Драйвер JDBC не учитывает регистрозависимость.

• Синонимы можно использовать. Драйвер упорядочивает их в порядке, так же, как и в случае с повторяющимися именами свойств.

• Драйвер JDBC для Microsoft SQL Server принимает значения сервера по умолчанию для свойств подключения, за исключением ANSI_DEFAULTS и IMPLICIT_TRANSACTIONS. Драйвер JDBC для Microsoft SQL Server автоматически устанавливает ANSI_DEFAULTS в ON и IMPLICIT_TRANSACTIONS в OFF.

• Если вы установили аутентификацию ActiveDirectoryPassword [DEPRECATED], включите в путь к классам следующую библиотеку: microsoft-authentication-library-for-java. Найдите его в репозитории Maven. Самый простой способ скачать библиотеку и ее зависимости — использовать Maven:

  1. Установите Maven в системе.
  2. Перейдите на страницу GitHub драйвера.
  3. pom.xml Скачайте файл.
  4. Выполните следующую команду Maven, чтобы скачать библиотеку и ее зависимости: mvn dependency:copy-dependencies

Свойства

В следующих разделах описаны все доступные в настоящее время свойства строка подключения для драйвера JDBC.

accessToken

• Тип: String
• По умолчанию:null

(Начиная с версии 6.0) Используйте это свойство для подключения к базе данных, используя маркер доступа. Вы не можете установить accessToken, используя URL-адрес подключения.

accessTokenCallbackClass

• Тип: String
• По умолчанию:null

(Версия 12.4+) Имя класса, реализующего обратный вызов, используемый с маркером доступа.

applicationIntent

• Тип: String
• По умолчанию:ReadWrite

(Начиная с версии 6.0) Объявляет тип рабочей нагрузки приложения для соединения с сервером.

Возможные значения: ReadOnly и ReadWrite.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

applicationName

• Тип: String [<=128 char]
• По умолчанию:null

Имя приложения или "Microsoft JDBC Driver for SQL Server" (Драйвер JDBC для SQL Server), если вы не указали имя.

Используйте это имя для идентификации конкретного приложения в различных средствах профилирования и ведения журнала SQL Server.

аутентификация

• Тип: String
• По умолчанию:NotSpecified

(Начиная с версии 6.0) Это необязательное свойство указывает, какой метод проверки подлинности использовать для соединения.

Возможные значения: ActiveDirectoryIntegratedActiveDirectoryManagedIdentity(версия 12.2+), ActiveDirectoryMSI (версия 7.2+), ActiveDirectoryInteractive (версия 9.2+), ActiveDirectoryServicePrincipal (версия 9.2+), ActiveDirectoryPassword [DEPRECATED]SqlPasswordи значение по умолчаниюNotSpecified.

Используйте ActiveDirectoryIntegrated (версия 6.0+) для подключения к SQL, используя интегрированную Windows-аутентификацию.

Используйте ActiveDirectoryManagedIdentity (версия 12.2+) или ActiveDirectoryMSI (версия 7.2+) для подключения к SQL из Azure ресурса. Например, виртуальная машина Azure, служба приложений или функциональное приложение с использованием проверки подлинности управляемого удостоверения.

Два типа управляемых удостоверений, поддерживаемых драйвером при использовании режима проверки подлинности ActiveDirectoryManagedIdentity или ActiveDirectoryMSI:

• Системно назначенная управляемая идентификация: используется для получения accessToken по умолчанию.

• Пользовательское присвоенное управляемое удостоверение: используется для получения accessToken, если идентификатор клиента управляемого удостоверения указан через свойство подключения msiClientId.

Используется ActiveDirectoryInteractive для подключения к базе данных с помощью интерактивного потока проверки подлинности.

Используйте ActiveDirectoryServicePrincipal (версия 9.2+) для подключения к базе данных с помощью идентификатора клиента и секрета учетной записи службы. Укажите идентификатор клиента в свойстве userName и секрете в свойстве password (10.2+).

Используйте ActiveDirectoryServicePrincipalCertificate (версия 12.4+) для подключения к базе данных с помощью идентификатора клиента и сертификата учетной записи служб. Укажите идентификатор клиента в свойстве userName и пути к сертификату в свойстве clientCertificate .

Дополнительные параметры см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryServicePrincipalCertificate".

Используйте ActiveDirectoryPassword [DEPRECATED] для подключения к SQL с использованием имени и пароля Microsoft Entra principal.

ActiveDirectoryPassword устарел.

Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryPassword".

Используйте SqlPassword для подключения к SQL с помощью userName/user, и password свойствами.

Используйте, NotSpecified если ни один из этих методов проверки подлинности не нужен.

Если для свойства проверки подлинности задано любое значение, отличное от NotSpecified, драйвер использует протокол TLS, ранее известный как протокол SSL, включая шифрование по умолчанию.

Сведения о настройке проверки подлинности Microsoft Entra см. в разделе проверка подлинности Microsoft Entra для Azure SQL.

authenticationScheme

• Тип: String
• По умолчанию:NativeAuthentication

Указывает, какой тип встроенной безопасности должен использоваться приложением.

Возможные значения: JavaKerberos( NTLM версия 7.4+) и значение по умолчанию NativeAuthentication.

NativeAuthentication вызывает загрузку драйвера mssql-jdbc_auth-<version>-<arch>.dll (например, mssql-jdbc_auth-8.2.2.x64.dll) на Windows, которая используется для получения сведений об интегрированной проверке подлинности.

(Загруженная собственная библиотека проверки подлинности называется sqljdbc_auth.dll при использовании драйверов версии 6.0–7.4.)

При использовании authenticationScheme=JavaKerberos необходимо указать полное доменное имя (FQDN) в свойстве serverName или serverSpn. В противном случае возникает ошибка (сервер не найден в базе данных Kerberos).

Дополнительные сведения об использовании authenticationScheme=JavaKerberos см. в разделе Использование интегрированной аутентификации Kerberos для подключения к SQL Server.

При использовании authenticationScheme=NTLM необходимо указать домен Windows с помощью свойства domain или domainName, учетных данных Windows в свойстве user или userName и свойстве password. В противном случае возникает ошибка (необходимо указать свойства подключения).

bulkCopyForBatchInsertAllowEncryptedValueModifications

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) Когда вы устанавливаете useBulkCopyForBatchInsert в true, задайте этот параметр как true, чтобы включить массовое копирование зашифрованных данных между таблицами или базами данных без расшифровки данных.

Дополнительные сведения и предупреждения об использовании этого свойства см. в параметре allowEncryptedValueModifications в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertBatchSize

• Тип: int
• По умолчанию:0

(Версия 12.10+) Если задано значение useBulkCopyForBatchInserttrue, это свойство указывает размер пакета для операций массового копирования, создаваемых драйвером из операций пакетной вставки.

Дополнительные сведения о влиянии этого параметра см. в параметре BatchSize в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertCheckConstraints (групповое копирование для пакетной вставки с проверкой ограничений)

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) При использовании useBulkCopyForBatchInsert=true задайте этот параметр на true, чтобы включить ограничения проверки при вставке данных. Установите этот параметр на false для отключения ограничений проверки.

Дополнительные сведения о влиянии этого параметра см. в параметре CheckConstraints в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertFireTriggers

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) При использовании useBulkCopyForBatchInsert=true задайте этот параметр равным true, чтобы включить запуск триггеров вставки при вставке строк в базу данных. Установите этот параметр в false, чтобы отключить триггеры вставки.

Дополнительные сведения о влиянии этого параметра см. в параметре FireTriggers в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertKeepIdentity

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) При использовании useBulkCopyForBatchInsert=true задайте этот параметр как true, чтобы сохранить идентификаторы исходных значений при вставке данных. Установите параметр false, чтобы назначать идентификационные значения по месту назначения.

Дополнительные сведения о влиянии этого параметра см. в параметре KeepIdentity в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertKeepNulls

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) При использовании useBulkCopyForBatchInsert=trueустановите этот параметр для true сохранения значений NULL в целевой таблице независимо от параметров значений по умолчанию. Установите этот параметр равным false, чтобы значения по умолчанию для назначения заменяли значения NULL.

Дополнительные сведения о влиянии этого параметра см. в параметре KeepNulls в SQLServerBulkCopyOptions.

bulkCopyForBatchInsertTableLock (массовая копия для пакетной вставки с блокировкой таблицы)

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.10+) Когда вы устанавливаете useBulkCopyForBatchInsert в true, задайте этот параметр, чтобы получить блокировку массового обновления true во время операции массового копирования. Установите этот параметр на false, чтобы использовать блокировки строк.

Дополнительные сведения о влиянии этого параметра см. в параметре TableLock в SQLServerBulkCopyOptions.

cacheBulkCopyMetadata

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.8+) При использовании useBulkCopyForBatchInsert=trueэто свойство сообщает драйверу, следует ли кэшировать метаданные целевого столбца на уровне подключения. Если задано значение true, убедитесь, что назначение не изменяется между массовыми вставками, так как драйвер не имеет способа обработки этого изменения.

calcBigDecimalPrecision

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.6+) Флаг, указывающий, должен ли драйвер вычислять точность для входных данных BigDecimal, а не использовать максимально допустимое значение для точности (38).

cancelQueryTimeout

• Тип: int
• По умолчанию:-1

(версия 6.4+) Используйте это свойство для отмены установки queryTimeout на соединении. Выполнение запроса прекращает отвечать и не выдает исключение, если tcp-подключение к серверу незаметно разрывается. Это свойство применимо только в том случае, если queryTimeout также задано в соединении.

Драйвер ожидает общего количества cancelQueryTimeout + queryTimeout секунд, чтобы удалить подключение и закрыть канал.

Значение этого свойства по умолчанию равно 1, а поведение имеет неограниченное время ожидания.

clientCertificate

• Тип: String
• По умолчанию:null

(версия 8.4+) Указывает расположение сертификата, используемого для проверки подлинности сертификата клиента. Драйвер JDBC поддерживает расширения файлов PFX, PEM, DER и CER.

Для получения более подробной информации см. Аутентификация клиентского сертификата для сценариев обратной связи.

clientKey

• Тип: String
• По умолчанию:null

(версия 8.4+) Указывает расположение закрытого ключа для сертификатов PEM, DER и CER, указанных атрибутом clientCertificate .

Для получения более подробной информации см. Аутентификация клиентского сертификата для сценариев обратной связи.

clientKeyPassword

• Тип: String
• По умолчанию:null

(версия 8.4+) Указывает необязательную строку пароля для доступа к закрытому ключу clientKey файла.

Для получения более подробной информации см. Аутентификация клиентского сертификата для сценариев обратной связи.

настройка шифрования столбца

• Тип: String [Enabled | Disabled]
• По умолчанию:Disabled

(версия 6.0+) Установите Enabled, чтобы использовать функцию Always Encrypted (AE). Когда функция Always Encrypted включена, драйвер JDBC прозрачно шифрует и расшифровывает конфиденциальные данные, хранящиеся в столбцах зашифрованной базы данных на сервере.

Дополнительные сведения о Always Encrypted см. в разделе "Использование Always Encrypted" с драйвером JDBC.

concatNullYieldsNull

• Тип: String [ON | OFF]
• По умолчанию:ON

(версия 13.2+) При установке этого параметра на OFF, драйвер задает переменную сеанса базы данных CONCAT_NULL_YIELDS_NULL при установлении соединения с OFF. Результатом является то, что объединение значения NULL со строкой дает саму строку (значение NULL рассматривается как пустая строка).

Дополнительную информацию см. в разделе SET CONCAT_NULL_YIELDS_NULL.

connectRetryCount

• Тип: int [0..255]
• По умолчанию:1

(Для версий 9.4 и выше) Число повторных попыток подключения в случае сбоя соединения.

connectRetryInterval

• Тип: int [1..60]
• По умолчанию:10

(Для версий 9.4 и выше) Число секунд между попытками подключения.

databaseName, база данных

• Тип: String [<=128 char]
• По умолчанию:null

Имя базы данных для соединения.

Если имя базы данных не указано, подключение использует базу данных по умолчанию.

datetimeParameterType

• Тип: String [datetime | datetime2 | datetimeoffset]
• По умолчанию:datetime2

(Версия 12.2+) Тип данных SQL, используемый для параметров даты и метки времени Java.

При подключении к SQL Server 2016 или более поздних версиях и взаимодействии с устаревшими значениями datetime задайте для этого свойства значение datetime. Этот параметр устраняет проблемы преобразования на стороне сервера между datetime и datetime2 значениями.

Дополнительные сведения см. в разделе Изменение поведения при преобразовании значений datetime в datetime2 начиная с SQL Server 2016.

delayLoadingLobs

• Тип: Boolean [true | false]
• По умолчанию:true

Флаг, чтобы указать, следует ли поточно передавать все LOB-объекты, полученные из ResultSet. Задание этого свойства для false загружает весь LOB-объект в память без потоковой передачи.

disableStatementPooling

• Тип: Boolean [true | false]
• По умолчанию:true

Флаг, указывающий, следует ли использовать пул запросов.

domainName, домен

• Тип: String
• По умолчанию:null

(версия 7.4+) Домен Windows для проверки подлинности при использовании NTLM.

enablePrepareOnFirstPreparedStatementCall (включить подготовку при первом вызове PreparedStatement)

• Тип: Boolean [true | false]
• По умолчанию:false

Установите true для включения создания дескриптора подготовленного выражения при вызове sp_prepexec во время первого выполнения подготовленного выражения.

Установите false, чтобы изменить первое выполнение подготовленной инструкции, вызвав sp_executesql, и не готовить инструкцию. В случае второго выполнения выполняется вызов sp_prepexec для инициализации обработчика подготовленного выражения.

протокол аттестации анклава

• Тип: String
• По умолчанию:null

(Начиная с версии 8.2+) Это необязательное свойство указывает протокол аттестации, который следует использовать для Always Encrypted с безопасными анклавами. В настоящее время единственными поддерживаемыми значениями этого поля являются HGS, AASи NONE (NONE поддерживается только в версии 11.2+).

Дополнительные сведения о Always Encrypted с безопасными анклавами см. в статье Использование Always Encrypted с безопасными анклавами с драйвером JDBC.

enclaveAttestationUrl

• Тип: String
• По умолчанию:null

(Начиная с версии 8.2) Это необязательное свойство указывает URL-адрес конечной точки службы аттестации, который следует использовать для Always Encrypted с безопасными анклавами.

Дополнительные сведения о Always Encrypted с безопасными анклавами см. в статье Использование Always Encrypted с безопасными анклавами с драйвером JDBC.

зашифровать

• Тип: String
• По умолчанию:null

Установите значение true, чтобы указать, что sql ядро СУБД использует шифрование TLS для всех данных, отправляемых между клиентом и сервером, если у сервера установлен сертификат. Значение по умолчанию используется true в версии 10.2 и более поздних версиях, а false также в версии 9.4 и более ранних версий.

В версии 6.0 и более поздних версий есть новый параметр authentication подключения, использующий шифрование TLS по умолчанию.

Дополнительные сведения об этом свойстве см. в свойстве authentication .

В версии 11.2.0 и более поздних encrypt был изменён с Boolean на string, что позволяет поддерживать TDS 8.0 при установке свойства strict.

Изменение по умолчанию в версии 10.2 является критическим изменением. Если вы обновляетесь с версии 9.4 или более ранней версии, а у сервера нет допустимого сертификата TLS, установите trustServerCertificatetrue или укажите действительный сертификат.

резервныйПартнер

• Тип: String
• По умолчанию:null

Имя резервного сервера, используемого в конфигурации зеркалирования базы данных. Это свойство используется при сбое начального подключения к основному серверу. После установления начального подключения это свойство игнорируется. Необходимо использовать с свойством databaseName .

Если указать имя виртуальная сеть в свойстве подключения Server, нельзя использовать зеркальное отображение базы данных.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

FIPS

• Тип: Boolean [true | false]
• По умолчанию:false

Задайте для этого свойства значение true для виртуальной машины Java с поддержкой FIPS (JVM).

fipsProvider

• Тип: String
• По умолчанию:null

Поставщик FIPS, настроенный в JVM, например BCFIPS или SunPKCS11-NSS. Удалено в версии 6.4.0.

Дополнительные сведения см. в задаче GitHub 460.

gsscredential

• Тип: org.ietf.jgss.GSSCredential
• По умолчанию:null

(Версия 6.2+) Укажите учетные данные пользователя для ограниченного делегирования Kerberos в этом свойстве.

Используйте этот параметр как integratedSecuritytrue и JavaKerberos как authenticationScheme.

hostNameInCertificate

• Тип: String
• По умолчанию:null

Имя узла, используемое для проверки SQL Server TLS/SSL-сертификата.

Этот hostNameInCertificate параметр можно использовать для указания имени узла в ситуациях, когда имя или имена, используемые в сертификате, не совпадают с именем, переданным свойству serverName . Однако если имеется совпадение, параметр hostNameInCertificate не следует использовать.

В ситуациях, когда свойство hostNameInCertificate не указано или имеет значение NULL, драйвер Microsoft JDBC для SQL Server использует значение свойства serverName в качестве имени хоста для проверки сертификата TLS/SSL SQL Server.

Используйте это свойство в сочетании с свойствами encrypt и authentication свойствами trustServerCertificate . Это свойство влияет на проверку сертификата, если подключение использует шифрование TLS и trustServerCertificate имеет значение false. Убедитесь, что значение, которое вы передаете в hostNameInCertificate, совпадает с общим именем (CN) или DNS-именем в альтернативном имени субъекта (SAN) в сертификате сервера, чтобы подключение TLS было успешным.

Дополнительные сведения о поддержке шифрования см. в разделе Основные сведения о поддержке шифрования.

Instancename

• Тип: String [<=128 char]
• По умолчанию:null

Имя экземпляра базы данных, к которому производится подключение. Если это свойство не указано, вы подключаетесь к экземпляру по умолчанию. Если вы указываете как instanceName, так и порт, обратитесь к примечаниям о порте.

Если указать имя виртуальная сеть в свойстве подключения Server, нельзя использовать свойство подключения instanceName.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

интегрированная безопасность

• Тип: Boolean [true | false]
• По умолчанию:false

Установите значение true, чтобы указать, что SQL Server использует учетные данные Windows на операционных системах Windows. Если true, драйвер JDBC ищет в кэше учетных данных местного компьютера учетные данные, предоставленные при входе пользователя в систему или сеть.

Задайте true (с authenticationscheme=JavaKerberos), чтобы указать, что учетные данные Kerberos используются в SQL Server.

Дополнительные сведения о проверке подлинности Kerberos см. в статье Использование встроенной проверки подлинности Kerberos для подключения к SQL Server.

Установите значение true (с authenticationscheme=NTLM), чтобы указать, что учетные данные NTLM используются в SQL Server.

Если falseнеобходимо указать имя пользователя и пароль.

ipaddresspreference

• Тип: String [<=128 char]
• По умолчанию:IPv4First

Предпочтительный тип IP-адресов, используемый клиентским приложением.

С помощью IPV4First драйвер сначала траверсирует IPv4-адреса. Если не удалось подключиться ни к одному IPv4-адресу, драйвер попытается использовать IPv6-адреса при их наличии.

Сначала IPV6Firstдрайвер проходит по IPv6-адресам. Если не удалось подключиться ни к одному IPv6-адресу, драйвер попытается использовать IPv4-адреса при их наличии.

С помощью UsePlatformDefault драйвер проходит по всем IP-адресам в их первоначальном порядке, полученном в результате разрешения DNS.

jaasConfigurationName

• Тип: String
• По умолчанию:SQLJDBCDriver

(версия 6.2+) Каждое подключение к SQL Server может использовать собственное имя конфигурации входа JAAS для установления подключения Kerberos. Имя элемента конфигурации можно передать через это свойство. Используйте это свойство при создании файла конфигурации Kerberos. По умолчанию драйвер ищет имя SQLJDBCDriver.

Если драйвер не находит внешнюю конфигурацию, он задает useDefaultCcache=true для виртуальных машин IBM JVMs и useTicketCache=true для других виртуальных машин JVM.

keyStoreAuthentication

• Тип: String
• По умолчанию:null

(Начиная с версии 6.0) Это свойство определяет, какое хранилище ключей можно использовать с Always Encrypted, и определяет механизм проверки подлинности, используемый для проверки подлинности в хранилище ключей. Драйвер поддерживает настройку хранилища ключей Java без проблем при настройке keyStoreAuthentication=JavaKeyStorePassword. Чтобы использовать это свойство, необходимо также задать свойства keyStoreLocation и keyStoreSecret для хранилища ключей Java.

Начиная с Microsoft JDBC Driver 8.4, можно задать keyStoreAuthentication=KeyVaultManagedIdentity или keyStoreAuthentication=KeyVaultClientSecret для проверки подлинности в Azure Key Vault с помощью управляемых удостоверений.

Дополнительные сведения о Always Encrypted см. в разделе "Использование Always Encrypted" с драйвером JDBC.

keyStoreLocation

• Тип: String
• По умолчанию:null

(версия 6.0+) При keyStoreAuthentication=JavaKeyStorePassword свойство keyStoreLocation определяет путь к файлу хранилища ключей Java, в котором хранится главный ключ столбца для использования с данными Always Encrypted. Путь должен включать имя файла хранилища ключей.

Дополнительные сведения о Always Encrypted см. в разделе "Использование Always Encrypted" с драйвером JDBC.

keyStorePrincipalId

• Тип: String
• По умолчанию:null

(версия 8.4+) При keyStoreAuthentication=KeyVaultManagedIdentity свойство keyStorePrincipalId указывает допустимый идентификатор клиента приложения Microsoft Entra.

Дополнительные сведения о Always Encrypted см. в разделе "Использование Always Encrypted" с драйвером JDBC.

keyStoreSecret

• Тип: String
• По умолчанию:null

(версия 6.0+) keyStoreAuthentication=JavaKeyStorePassword Когда keyStoreSecretсвойство определяет пароль, используемый для хранилища ключей и ключа. При использовании хранилища ключей Java хранилище ключей и пароль ключа должны совпадать.

Дополнительные сведения о Always Encrypted см. в разделе "Использование Always Encrypted" с драйвером JDBC.

LastUpdateCount

• Тип: Boolean [true | false]
• По умолчанию:true

Значение true возвращает только последнее число обновлений из инструкции SQL, передаваемой серверу. Используйте это значение только с одним из операторов SELECT, INSERT или DELETE, чтобы игнорировать другие счетчики обновлений, которые могут вызвать триггеры сервера. Задайте этому свойству значение для false возврата всех счетчиков обновлений, включая возвращаемые триггерами сервера.

lockTimeout

• Тип: int
• По умолчанию:-1

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

Кроме того, можно Statement.setQueryTimeout() задать время ожидания запроса для определенных инструкций. Значение может быть равным 0 — время ожидания отсутствует.

loginTimeout

• Тип: int [0..65535]
• По умолчанию: 30 (версия 11.2 и более поздняя) или 15 (версия 10.2 и более ранние версии)

Время в секундах, которое драйвер должен ожидать до истечения времени ожидания неудачного подключения. Нулевое значение указывает, что время ожидания по умолчанию совпадает с системным временем ожидания. Это значение равно 30 секунд (по умолчанию в версии 11.2 и более поздней версии) или 15 секунд (значение по умолчанию в версии 10.2 и более ранних версиях). Ненулевое значение — это количество секунд, которое драйвер должен ждать до истечения времени ожидания сбоя подключения.

Если вы указываете виртуальная сеть Name в свойстве подключения Server, установите время ожидания на три минуты или более, чтобы обеспечить достаточно времени для успешного выполнения резервного подключения.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

maxResultBuffer

• Тип: String
• По умолчанию:null

(версия 9.2+) Используйте maxResultBuffer для задания максимального количества байтов при чтении результирующего набора. Если это значение не указано, драйвер считывает весь результирующий набор. Размер можно указать в двух стилях:

• Размер в байтах (например, 100, 150M, 300K, 400G).
• В процентах от максимального объема памяти кучи (например, 10p, 15pct, 20percent).

msiClientId

• Тип: String
• По умолчанию:null

(не рекомендуется) (Версия 7.2+) Идентификатор клиента управляемого удостоверения (MSI), используемый для получения accessToken, чтобы установить подключение с использованием ActiveDirectoryManagedIdentity или ActiveDirectoryMSI режима проверки подлинности.

multiSubnetFailover

• Тип: Boolean [true | false]
• По умолчанию:false

Всегда указывайте multiSubnetFailover=true для подключения к прослушивателю группы доступности SQL Server или экземпляру отказоустойчивого кластера SQL Server. multiSubnetFailover=true настраивает драйвер для ускорения обнаружения и подключения к активному серверу.

Возможные значения: true и false.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

Вы можете программно получить доступ к свойству multiSubnetFailover подключения с помощью getPropertyInfo, getMultiSubnetFailover и setMultiSubnetFailover.

packetSize

• Тип: int [-1 | 0 | 512..32767]
• По умолчанию:8000

Размер (в байтах) сетевого пакета, используемого для обмена данными с сервером. Значение -1 указывает на использование размера сетевого пакета сервера по умолчанию. Значение 0 указывает на использование максимального значения 32767. Если для этого свойства задано значение за пределами допустимого диапазона, возникает исключение.

Дополнительные сведения об этом свойстве см. в описании метода setPacketSize класса SQLServerDataSource.

пароль

• Тип: String [<=128 char]
• По умолчанию:null

Пароль базы данных, если вы подключаетесь с использованием пользователя и пароля SQL.

Для подключения Kerberos с главным именем и паролем задайте для этого параметра пароль главного имени Kerberos.

(версия 10.2+) При authentication=ActiveDirectoryServicePrincipal свойство password определяет пароль, используемый для субъекта Active Directory.

номер порта, порт

• Тип: int [0..65535]
• По умолчанию:1433

Порт, на котором сервер слушает. Если указать номер порта в строка подключения, запрос на SQLbrowser не выполняется. При указании порта и instanceName, подключение осуществляется к указанному порту. Однако instanceName валидируется, и возникает ошибка, если instanceName не соответствует порту.

prepareMethod

• Тип: String [prepexec | prepare | scopeTempTablesToConnection | none]
• По умолчанию:prepexec

(Версия 11.2.0+) Указывает базовый метод подготовки, используемый драйвером с подготовленными инструкциями.

Установите prepare для использования sp_prepare в качестве метода подготовки. Установка prepareMethod этого значения приводит к отдельному начальному запросу к базе данных, чтобы подготовить заявление без каких-либо начальных значений, учитываемых в плане выполнения. Установите prepexec для использования sp_prepexec в качестве метода подготовки. Этот метод объединяет действие подготовки с первым выполнением, уменьшая количество круговых путей. Он также предоставляет базу данных с начальными значениями параметров, которые база данных может рассмотреть в плане выполнения.

(Версия 13.4.0+) Установите scopeTempTablesToConnection, чтобы временные таблицы, создаваемые в подготовленных операторах, были ограничены для соединения с помощью подстановки литеральных параметров вместо использования подготовленных дескрипторов на стороне сервера. Установите none для принудительного применения замены литеральных параметров при пакетном выполнении SQL, обходя маркеры подготовленных операторов на стороне сервера (sp_prepexec / sp_prepare).

Ограничения и отказ от ответственности за scopeTempTablesToConnection и none:

Эти prepareMethod параметры предназначены для сценариев совместимости и миграции, а не для общего использования производительности.

• Нет подготовленных на стороне сервера инструкций; SQL всегда выполняется как пакет.
• Для эффективного повторного использования плана требуется FORCED_PARAMETERIZATION.
• Параметры встраиваются как литералы, а не привязанные типы.
• Числовая точность и масштабирование могут отличаться от привязки параметров на стороне сервера.
• Значения даты и времени форматируются в виде строк драйвером.
• Большие строковые параметры увеличивают размер текста SQL и использование памяти.
• Параметры BLOB и CLOB могут привести к высокой нагрузке на память или нехватке памяти.
• SQL Server определяет типы данных параметров во время синтаксического анализа SQL.
• Планы запросов могут отличаться из-за различий в литеральных значениях.
• Ошибки обнаруживаются во время выполнения, а не во время привязки.
• Исполняемый SQL включает литеральные значения и отображается в трассировках и журналах сервера.

queryTimeout

• Тип: int
• По умолчанию:-1

Количество секунд, ожидаемых до истечения времени ожидания в запросе. Значение по умолчанию — 1, что означает бесконечное время ожидания. Установка этого значения в 0 также предполагает неограниченное время ожидания.

цитируемыйИдентификатор

• Тип: String [ON | OFF]
• По умолчанию:ON

(версия 13.2+) При установке этого параметра на OFF, драйвер задает переменную сеанса базы данных QUOTED_IDENTIFIER при установлении соединения с OFF. База данных обрабатывает двойные кавычки как строковые разделители для символьных литералей, и нельзя заключать идентификаторы в двойные кавычки.

Дополнительные сведения см. в разделе SET QUOTED_IDENTIFIER.

Realm

• Тип: String
• По умолчанию:null

(Для версий 9.4 и выше) Область проверки подлинности Kerberos. Установка этого значения переопределит область проверки подлинности Kerberos, которую драйвер автоматически определит на основе области сервера.

репликация

• Тип: Boolean [true | false]
• По умолчанию:false

(Для версий 9.4 и выше) Этот параметр сообщает серверу, используется ли соединение для репликации. При включении триггеры с параметром NOT FOR REPLICATION не срабатывают на соединении.

буферизация ответа

• Тип: String [full | adaptive]
• По умолчанию:adaptive

Если для этого свойства задано значение adaptive, драйвер буферизирует минимальный объем данных при необходимости. Режим по умолчанию — adaptive.

Если это свойство fullзадано, драйвер считывает весь результирующий набор с сервера при выполнении инструкции.

Selectmethod

• Тип: String [direct | cursor]
• По умолчанию:direct

Если задать это свойство как cursor, драйвер создает курсор базы данных для каждого запроса, который он создает в соединении для курсоров TYPE_FORWARD_ONLY и CONCUR_READ_ONLY. Как правило, это свойство требуется только в том случае, если приложение создает большие результирующие наборы, которые не могут полностью разместиться в памяти клиента. Если вы устанавливаете это свойство в cursor, драйвер сохраняет лишь ограниченное количество строк из результирующего набора в памяти клиента.

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

sendStringParametersAsUnicode

• Тип: Boolean [true | false]
• По умолчанию:true

Задав для свойства sendStringParametersAsUnicode значение true, драйвер отправляет строковые параметры серверу в формате Юникода.

Если для свойства sendStringParametersAsUnicode задано значение false, драйвер отправляет строковые параметры серверу в форматах, не относящихся к Unicode, таких как ASCII или MBCS, а не в формате Unicode.

Значение свойства sendStringParametersAsUnicode по умолчанию — true.

Для оптимальной производительности с CHAR, VARCHAR и LONGVARCHAR типами данных JDBC приложение должно установить для свойства sendStringParametersAsUnicode значение false и использовать методы setString, setCharacterStream и setClob, работающие с ненативными символами, классов SQLServerPreparedStatement и SQLServerCallableStatement.

Когда приложение задает sendStringParametersAsUnicode свойство false и использует метод ненациональных символов для доступа к типам данных Юникода на стороне сервера (например, nchar, nvarchar и ntext), некоторые данные могут быть потеряны, если сортировка базы данных не поддерживает символы в параметрах String, передаваемых методом ненациональных символов.

Приложение должно использовать методы национальных символов setNString, setNCharacterStream и setNClob классов SQLServerPreparedStatement и SQLServerCallableStatement для типов данных NCHAR, NVARCHAR и LONGNVARCHAR JDBC.

Изменение этого значения может повлиять на сортировку результатов из базы данных. Различия сортировки обусловлены различными правилами сортировки для юникодов и символов, отличных от Юникода.

sendTemporalDataTypesAsStringForBulkCopy

• Тип: Boolean [true | false]
• По умолчанию:true

(версия 8.4+) При установке этого свойства falseподключения драйвер отправляет DATE, DATETIMEDATETIME2, DATETIMEOFFSETSMALLDATETIMEи TIME типы данных в качестве соответствующих типов, а не отправляет их какString.

При установке этого свойства falseподключения драйвер принимает строковый литеральный формат каждого темпорального типа данных по умолчанию, например:

• DATE: YYYY-MM-DD
• DATETIME: YYYY-MM-DD hh:mm:ss[.nnn]
• DATETIME2: YYYY-MM-DD hh:mm:ss[.nnnnnnn]
• DATETIMEOFFSET: YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]
• SMALLDATETIME: YYYY-MM-DD hh:mm:ss
• TIME: hh:mm:ss[.nnnnnnn]

sendTimeAsDatetime

• Тип: Boolean [true | false]
• По умолчанию:true

Это свойство добавлено в SQL Server JDBC Driver 3.0.

• Установите значение true для отправки значений java.sql.Time на сервер в виде значений SQL Server datetime.

• Установите значение false для отправки значений java.sql.Time на сервер в виде значений SQL Server time.

Значение по умолчанию для этого свойства в настоящее время true может измениться в будущем выпуске.

Дополнительные сведения о том, как драйвер JDBC для Microsoft SQL Server настраивает значения java.sql.Time перед отправкой на сервер, см. в статье Настройка отправки значений java.sql.Time.

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

• Тип: String
• По умолчанию:null

(Версия 11.2.0 и выше) Путь к файлу сертификата сервера. Драйвер использует этот сертификат для проверки, когда вы устанавливаете encrypt на strict. Драйвер поддерживает файлы сертификатов, использующие формат PEM-файла.

имя сервера, сервер

• Тип: String
• По умолчанию:null

Компьютер, на котором работает SQL Server или База данных SQL Azure.

Можно также указать имя виртуальной сети в группе доступности.

Дополнительные сведения об аварийном восстановлении см. в статье о поддержке высокой доступности и аварийного восстановления в JDBC Driver.

serverNameAsACE

• Тип: Boolean [true | false]
• По умолчанию:false

(версия 6.0+) Установите true, чтобы указать, что драйвер должен перевести имя сервера в Юникоде в совместимую кодировку ASCII (Punycode) для подключения. Если этот параметр задан false, драйвер использует имя сервера, как указано для подключения.

Дополнительные сведения о международных функциях см. в статье Международные функции драйвера JDBC.

serverPreparedStatementDiscardThreshold

• Тип: int
• По умолчанию:10

(версия 6.2+) Используйте это свойство для управления количеством невыполненных действий отмены инструкции (sp_unprepare) для каждого подключения, прежде чем драйвер очищает выдающиеся дескрипторы на сервере.

Если для этого свойства задано значение <= 1, драйвер немедленно выполняет неподготовленные действия при закрытии подготовленной инструкции. Если для свойства задано значение > 1, драйвер пакетирует эти вызовы вместе, чтобы избежать слишком частого вызова sp_unprepare .

serverSpn

• Тип: String
• По умолчанию:null

(версия 4.2+) Используйте это необязательное свойство, чтобы указать имя субъекта-службы (SPN) для подключения Java Kerberos. Используйте его с authenticationScheme.

Чтобы указать SPN, используйте форму: MSSQLSvc/fqdn:port@REALM, где fqdn — это полное доменное имя, port — номер порта, а REALM — область Kerberos для SQL Server прописными буквами.

Дополнительные сведения об использовании serverSpn с Java Kerberos см. в статье Использование интегрированной аутентификации Kerberos для подключения к SQL Server.

socketFactoryClass

• Тип: String
• По умолчанию:null

(версия 8.4+) Указывает имя класса для пользовательской фабрики сокетов, используемой вместо фабрики сокетов по умолчанию.

socketTimeout

• Тип: int
• По умолчанию:0

Количество миллисекунд, которое ожидает, прежде чем произойдет тайм-аут на операции чтения или принятия на сокете. Значение по умолчанию — 0, что означает бесконечное время ожидания.

statementPoolingCacheSize

• Тип: int
• По умолчанию:0

(версия 6.4+) Это свойство позволяет включить кэширование подготовленной инструкции в драйвере.

Это свойство определяет размер кэша для создания пула инструкций.

Используйте это свойство только со свойством disableStatementPooling подключения, которому необходимо задать значение false. Установка disableStatementPooling в true или statementPoolingCacheSize в 0 отключает кэширование дескрипторов подготовленных операторов.

sslProtocol

• Тип: String
• По умолчанию:TLS

(версия 6.4+) Используйте это свойство, чтобы указать протокол TLS для рассмотрения во время безопасного подключения.

Возможные значения: TLS, TLSv1, TLSv1.1 и TLSv1.2.

Дополнительные сведения о протоколе SSL см. в разделе SSLProtocol.

transparentNetworkIPResolution

• Тип: Boolean [true | false]
• По умолчанию:true

(версия 6.0+) Это свойство обеспечивает быстрое обнаружение и подключение к активному серверу. Установите это в true или false. Значение по умолчанию — true.

До выхода Microsoft JDBC Driver 6.0 для SQL Server, приложение должно было установить строку подключения, чтобы включить multiSubnetFailover=true, чтобы указать, что оно подключается к группе доступности Always On. Без задания ключевого слова multiSubnetFailovertrue подключения приложение может столкнуться с временем ожидания при подключении к Группе Доступности Always On. Начиная с версии 6.0, приложению больше нет необходимости устанавливать multiSubnetFailover на true.

При transparentNetworkIPResolution=trueпервой попытке подключения в качестве времени ожидания используется 500 мс. Любые последующие попытки будут использовать такую же логику ожидания, что и свойство multiSubnetFailover.

trustManagerClass

• Тип: String
• По умолчанию:null

(Начиная с версии 6.4) Полное имя класса пользовательской реализации javax.net.ssl.TrustManager.

trustManagerConstructorArg

• Тип: String
• По умолчанию:null

(Начиная с версии 6.4) Необязательный аргумент, передающийся конструктору TrustManager. Если вы указали свойство trustManagerClass и запросили зашифрованное соединение, драйвер использует пользовательский TrustManager вместо системного TrustManager по умолчанию, основанного на хранилище ключей JVM.

trustServerCertificate

• Тип: Boolean [true | false]
• По умолчанию:false

Установите true чтобы указать, что драйвер не проверяет сертификат TLS/SSL сервера.

• Если значение равно true, TLS/SSL-сертификат сервера автоматически считается доверенным, когда для шифрования уровня связи используется TLS.

• Если значение — false, то драйвер выполнит проверку TLS-сертификата сервера. Если проверка сертификата сервера завершается ошибкой, драйвер вызовет ошибку и закроет подключение. Значение по умолчанию — false. Убедитесь, что значение, которое передано в serverName, точно совпадает с общим именем (CN) или DNS-именем, указанным в поле альтернативного имени субъекта в сертификате сервера, чтобы соединение TLS/SSL было успешным.

Дополнительные сведения о поддержке шифрования см. в разделе Основные сведения о поддержке шифрования.

trustStore

• Тип: String
• По умолчанию:null

Путь (включая имя файла) к файлу сертификата trustStore . Файл trustStore содержит список сертификатов, которыми доверяет клиент.

Если вы не укажете это свойство или зададите для него значение NULL, драйвер использует правила выбора фабрики доверительных менеджеров для определения, какое хранилище сертификатов использовать.

По умолчанию SunX509 TrustManagerFactory пытается найти доверенный материал в следующем порядке поиска:

1. Файл, указанный системным свойством javax.net.ssl.trustStore JVM.
2. Файл <java-home>/lib/security/jssecacerts.
3. Файл <java-home>/lib/security/cacerts.

Дополнительные сведения об интерфейсе SUNX509 TrustManager см. в документации по нему на веб-сайте компании Sun Microsystems.

trustStorePassword

• Тип: String
• По умолчанию:null

Пароль, используемый для проверки целостности trustStore данных.

Если вы задаете свойство trustStore, но не задаете свойство trustStorePassword, драйвер не проверяет целостность trustStore.

Если не указать свойства trustStore и trustStorePassword, драйвер использует системные свойства JVM javax.net.ssl.trustStore и javax.net.ssl.trustStorePassword. Если системное javax.net.ssl.trustStorePassword свойство не указано, драйвер не проверяет целостность объекта trustStore.

Если вы не зададите свойство trustStore, но зададите свойство trustStorePassword, драйвер JDBC использует файл, который javax.net.ssl.trustStore указывает в качестве хранилища доверия. Драйвер проверяет целостность хранилища сертификатов с помощью указанного trustStorePassword. Этот параметр требуется в случае, если клиентское приложение не желает сохранять пароль в системном свойстве виртуальной машины Java.

trustStoreType

• Тип: String
• По умолчанию:JKS

Установите это свойство, чтобы указать тип хранилища доверия, который будет использоваться для режима FIPS.

Возможные значения — это либо PKCS12, либо тип, определенный поставщиком FIPS.

useBulkCopyForBatchInsert (использование метода Bulk Copy для пакетных вставок)

• Тип: Boolean [true | false]
• По умолчанию:false

(версия 9.2+) При включении этого свойства подключения драйвер прозрачно использует API массового копирования для операций пакетной вставки, которые используют java.sql.PreparedStatement. Эта функция может обеспечить более высокую производительность.

По умолчанию эта функция выключена. Установите это свойство на true, чтобы его включить.

Дополнительные сведения об использовании этого свойства см. в разделе Использование API массового копирования для операции пакетной вставки.

useDefaultGSSCredential

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.6+) Флаг, чтобы указать, должен ли драйвер создать GSSCredential от имени пользователя для использования собственного GSS-API для верификации Kerberos.

использовать по умолчанию JaasConfig

• Тип: Boolean [true | false]
• По умолчанию:false

(Версия 12.6+) Если приложение существует вместе с библиотеками, которые настраивают JAAS на уровне системы, задайте это свойство, чтобы true разрешить драйверу использовать ту же конфигурацию для выполнения проверки подлинности Kerberos.

useFmtOnly

• Тип: Boolean [true | false]
• По умолчанию:false

(Начиная с версии 7.4) Предоставляет альтернативный способ запроса метаданных параметров с сервера. Установите это свойство в true, чтобы указать, что драйвер должен использовать логику SET FMTONLY при запросе метаданных параметра. По умолчанию это свойство отключено, и использовать его не рекомендуется, так как SET FMTONLY помечено для удаления. useFmtOnly доступно только в качестве обходного решения для известных ограничений и проблем в sp_describe_undeclared_parameters.

В настоящее время эта функция поддерживает только одиночные SELECT/INSERT/UPDATE/DELETE запросы. Попытка использовать эту функцию с неподдерживаемыми или несколькими запросами вызовет попытку драйвера проанализировать запрос, но, скорее всего, может привести к исключению.

Дополнительные сведения об этом свойстве см. в разделе "Извлечение ParameterMetaData с помощью useFmtOnly".

userName, пользователь

• Тип: String [<=128 char]
• По умолчанию:null

Пользователь базы данных, если вы подключаетесь с помощью пользователя и пароля SQL.

Для подключения с использованием Kerberos через основное имя и пароль задайте значение этого свойства на основное имя Kerberos.

(версия 10.2+) При authentication=ActiveDirectoryServicePrincipal свойство userName указывает допустимый идентификатор безопасного клиента Microsoft Entra.

vectorTypeSupport

• Тип: String [v2 | v1 | off]
• По умолчанию:v1

(версия 13.2+) Установите для off, чтобы указать, что сервер отправляет типы векторов как строковые данные в формате JSON, и для v1, чтобы указать, что сервер отправляет типы векторов FLOAT32 в виде векторных данных. Значение по умолчанию — v1.

(версия 13.4+) Установите v2, чтобы включить поддержку собственного векторного типа как для FLOAT32, так и для FLOAT16. FLOAT16 векторы используют сериализацию IEEE-754 с половинной точностью на проводе и предоставляются как массивы Float[] в Java.

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

идентификатор рабочей станции

• Тип: String [<=128 char]
• По умолчанию:<empty string>

Идентификатор рабочей станции. Используйте этот идентификатор для идентификации конкретной рабочей станции в различных средствах профилирования и ведения журнала.

Если значение не указано, по умолчанию используется <empty string>.

xopenStates

• Тип: Boolean [true | false]
• По умолчанию:false

Установите true, чтобы указать, что драйвер возвращает коды состояния, совместимые с XOPEN, в исключительных ситуациях.

Значение по умолчанию — возвращать коды состояний SQL 99.

Связанный контент

• Подключение к SQL Server с помощью JDBC Driver
• Режим FIPS