Драйвер Microsoft JDBC для SQL Server

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

Драйвер Microsoft Java Database Connectivity (JDBC) для SQL Server — это драйвер JDBC типа 4 (чистый Java, напрямую использует протокол SQL Server TDS, не требуются нативные библиотеки), который позволяет любому Java приложению или серверу подключаться к Microsoft SQL ядро СУБД в База данных SQL Azure, SQL database в Fabric, Управляемый экземпляр SQL Azure и во всех поддерживаемых версиях и редакциях SQL Server (включая Express Editions). Он реализует стандартные API JDBC и работает с основными серверами приложений Java, включая IBM WebSphere и SAP NetWeaver.

Выберите начальную точку

Производственные базовые показатели для Azure SQL

Используйте этот фрагмент в качестве отправной точки для рабочего Azure SQL подключения. Он загружает имя сервера и имя базы данных из конфигурации приложения, например Служба приложений Azure параметры приложения, переменные среды или файл конфигурации, и задает остальные свойства подключения программным способом. Конфигурация сочетает Transport Layer Security (TLS), управляемое удостоверение, повторные попытки подключения при временных сбоях, быстрое восстановление группы аварийного переключения, увеличенный тайм-аут входа, чтобы учесть аварийное переключение после холодного запуска, и настраиваемую логику повторных попыток (CRL) для операторов, которые сталкиваются с троттлингом Azure SQL или аварийным переключением в середине выполнения запроса.

Для повышения безопасности и упрощения горизонтального масштабирования сохраните сведения о подключении за пределами кода. В рабочей среде храните сведения о подключении в системе конфигурации приложения и используйте Azure Key Vault для конфиденциальных значений и параметров централизованно управляемого подключения. Дополнительные сведения см. в разделе "Защита строк подключения".

В фрагментах кода Java в этой статье для краткости опущены импорты и объявления классов.

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
String serverName = System.getenv("SQL_SERVER_NAME");
String databaseName = System.getenv("SQL_DATABASE_NAME");
String port = System.getenv().getOrDefault("SQL_PORT", "1433");

if (serverName == null || databaseName == null) {
    throw new IllegalStateException(
            "Set SQL_SERVER_NAME and SQL_DATABASE_NAME in your application configuration.");
}

String url = "jdbc:sqlserver://" + serverName + ":" + port;

Properties props = new Properties();
props.setProperty("databaseName", databaseName);
props.setProperty("encrypt", "true");
props.setProperty("trustServerCertificate", "false");
props.setProperty("authentication", "ActiveDirectoryManagedIdentity");
props.setProperty("loginTimeout", "120");         // 90 is the minimum floor for this retry profile; 120 leaves practical failover margin
props.setProperty("connectRetryCount", "5");     // retry transient connection failures up to 5 times (default 1)
props.setProperty("connectRetryInterval", "15"); // 15 seconds between connection retries (default 10)
props.setProperty("multiSubnetFailover", "true"); // recommended for any Azure SQL HA listener
// props.setProperty("applicationIntent", "ReadOnly"); // uncomment to route to a readable secondary
// Retry deadlocks and lock timeouts, plus Azure SQL throttling and mid-query failover.
props.setProperty("retryExec", "1205,1222:3,5+5;40501,40613,40197,10928,10929,49918:4,5*2");

try (Connection conn = DriverManager.getConnection(url, props);
     Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT 1")) {
    while (rs.next()) {
        System.out.println(rs.getInt(1));
    }
}

Этот фрагмент предназначен для групп автоматического переключения База данных SQL Azure и Управляемый экземпляр SQL Azure.

Устанавливайте multiSubnetFailover=true только при подключении к прослушивателю группы аварийного переключения, прослушивателю группы доступности или к конечной точке экземпляра отказоустойчивого кластера. Использование этого свойства для конечных точек, не являющихся прослушивателями высокой доступности (HA), может снизить производительность и не поддерживается. Дополнительные сведения см. в статье о поддержке драйвера JDBC для обеспечения высокой доступности, аварийного восстановления.

Фрагмент кода не задает retryConn, так как драйвер уже по умолчанию повторяет попытки при наиболее распространенных временных ошибках подключения Azure SQL (в том числе 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 и 10929) при наличии connectRetryCount и connectRetryInterval. Полный список см. в списке встроенных временных ошибок подключения. Добавьте retryConn с +<errorNumber> только в том случае, если нужно добавить в список ошибку, которая ещё не охвачена, или задайте для него значение <errorNumber> (без начального +), чтобы заменить его. Если вы помещете то же значение в URL-адрес JDBC, заключите его как retryConn={+<errorNumber>} или retryConn={<errorNumber>}.

Свойство retryExec состоит из двух частей, написанных как rule1;rule2 при программном настройке. Если вы помещаете то же значение в URL-адрес JDBC, заключите каждое правило в фигурные скобки следующим образом {rule1};{rule2}:

  • {1205,1222:3,5+5} выполняет повторные попытки для запросов, завершившихся ошибкой «жертва взаимоблокировки» (1205), и тайм-аутом запроса блокировки (1222), три раза с линейной задержкой 5, 10 и 15 секунд. В 1205 году SQL Server откатывает транзакцию, прежде чем драйвер увидит ошибку, поэтому повторное выполнение одной инструкции безопасно. Если инструкция, ставшая жертвой взаимоблокировки, была частью транзакции из нескольких инструкций, то предыдущие инструкции тоже были отменены, а CRL не выполняет их повторно, поэтому оберните всю транзакцию в собственный цикл повторных попыток. 1222 оставляет транзакцию открытой, а повторный запуск инструкции на уровне инструкции выполняется только внутри исходной транзакции; Если вам также нужно привязать длительность транзакции, заключите всю транзакцию в собственный цикл повторных попыток.

  • {40501,40613,40197,10928,10929,49918:4,5*2} повторяет попытки при ошибках троттлинга Azure SQL, переключения на резервный ресурс в середине выполнения запроса и ограничения ресурсов четыре раза с экспоненциально увеличивающимися интервалами ожидания: 5, 10, 20 и 40 секунд. Эти ошибки входят во встроенный список временных ошибок для цикла connect, но именно retryExec перехватывает их, если они возникают в середине выполнения запроса при уже установленном соединении. Интервалы ожидания CRL ограничены значением queryTimeout. Если вы устанавливаете значение queryTimeout меньше, чем следующее запланированное время ожидания, драйвер прекращает попытки раньше времени и повторно выбрасывает исключение. Выберите параметр queryTimeout, который как минимум равен суммарному времени ожидания CRL плюс времени выполнения оператора, или смиритесь с тем, что самые длинные задержки при повторных попытках не сработают.

Для групп отработки отказа База данных SQL Azure, именованных реплик Hyperscale и масштабирования чтения, а также прослушивателей групп доступности Always On задайте applicationIntent=ReadOnly, если требуется подключаться к доступной для чтения вторичной реплике. Для суверенных облаков, в которых альтернативное имя субъекта сертификата (SAN) не содержит имя узла, к которому вы подключаетесь, также задайте hostNameInCertificate так, чтобы оно совпадало с ним (например, *.database.usgovcloudapi.net для Azure для государственных организаций).

Дополнительные сведения о каждой части этой конфигурации см. в следующей статье:

Каталог временных ошибок Azure SQL см. в разделе "Устранение временных ошибок подключения".

Ключевые особенности

  • JDBC на основе стандартов: драйвер типа 4. Сборка JRE 11+ реализует JDBC 4.2, а также методы границ запроса JDBC 4.3 (beginRequest, endRequest) и вспомогательные функции экранирования Statement. API сегментирования JDBC 4.3 (setShardingKey, семейство createConnectionBuilder) выдают исключение SQLFeatureNotSupportedException. JRE 8 поддерживает JDBC 4.2. Сведения о разбивке по версиям и полном списке поддерживаемых и неподдерживаемых методов версии 4.3 см. в Java и поддержке спецификаций JDBC.
  • Поддержка широкой платформы: выполняется на любой платформе с поддерживаемой Java виртуальной машины (JVM), включая Windows, Linux и macOS.
  • Зашифрованные по умолчанию подключения с шифрованием TLS в encrypt=true качестве значения по умолчанию для текущих драйверов.
  • Аутентификация Microsoft Entra ID: подключения без пароля с использованием управляемого удостоверения, субъекта-службы, интерактивного потока, интегрированного потока, цепочки учетных данных по умолчанию и потока токена доступа.
  • Kerberos: встроенная проверка подлинности для локальная служба Active Directory.
  • NTLM: проверка подлинности Windows по схеме запрос-ответ для сценариев вне домена или устаревших сценариев.
  • Always Encrypted: шифрование на стороне клиента для конфиденциальных столбцов с необязательными безопасными анклавами для операций на месте.
  • Массовое копирование: высокопроизводительная вставка с использованием API SQLServerBulkCopy и производительность пакетной вставки для executeBatch.
  • Устойчивость подключения: встроенные повторные попытки подключения для временных ошибок, а также настраиваемая логика повторных попыток для инструкций (retryExec) и настраиваемый список ошибок подключения (retryConn).
  • Поддержка расширенных SQL Server типов данных: datetimeoffset, sql_variant, JSON, пространственных, векторных, табличных параметров и определяемых пользователем типов.

Get started

Статья Description
Требования к системе Поддерживаемые версии Java, операционной системы и SQL Server.
Матрица поддержки Подробная матрица совместимости для выпусков драйверов JDBC.
Скачивание драйвера Microsoft JDBC для SQL Server Ссылки для скачивания, координаты Maven и артефакты релиза.
Начало работы с драйвером JDBC Установите драйвер, настройте среду и запустите первый запрос.
Общие сведения о JDBC Driver Архитектура, поддерживаемые функции и соответствие спецификации JDBC.

Настройка и подключение

Статья Description
Подключение к SQL Server с помощью JDBC Driver Откройте подключение к экземпляру SQL Server из Java.
Подключение к базе данных SQL Azure Подключите приложение Java к База данных SQL Azure.
Создание URL-адреса подключения Полный справочник по синтаксису и свойствам URL-адресов jdbc:sqlserver://.
Настройте свойства подключения Все свойства подключения, значения по умолчанию и их настройка.
Настройка свойств источника данных Настройте SQLServerDataSource для использования с JNDI и серверами приложений.
Работа с подключением Корректно открывайте, повторно используйте и закрывайте подключения.
Использование пулов подключений Источники данных JNDI и интеграция с внешними пулами.
Устойчивость подключения Встроенные повторные попытки подключения и обнаружение разрыва соединения.
Настраиваемая логика повторных попыток Повторите неудавшиеся инструкции с помощью retryExec и настройте список повторных попыток подключения с помощью retryConn.
Общие сведения о свойствах времени ожидания в драйвере JDBC loginTimeout, queryTimeout, тайм-ауты сокета и то, как они взаимодействуют.
Развертывание JDBC Driver Упаковайте и разверните драйвер с помощью приложения.

Authenticate

Статья Description
Аутентификация Microsoft Entra Аутентификация с помощью управляемой идентификации, субъекта-службы, интерактивная, интегрированная и с использованием маркера доступа.
Встроенная проверка подлинности Kerberos Подключитесь к Kerberos и Active Directory.
Проверка подлинности NTLM Используйте учетные данные NTLM для проверки подлинности.
Проверка подлинности сертификата клиента для сценариев обратного цикла Аутентификация клиентов с помощью сертификатов в loopback-подключениях.

Secure

Статья Description
Защита приложений JDBC Driver Руководство по безопасности для приложений Java, использующих драйвер.
Безопасность приложений Рекомендации по модели угроз и глубокой защите.
Защита строк подключений Сохраняйте учетные данные и строки подключения вне источника.
Настройка шифрования на клиенте Корневые сертификаты доверия, закрепление сертификатов и параметры TLS.
Подключение с шифрованием Принудительно выполните encrypt=true и проверьте сертификат сервера.
Основные сведения о поддержке шифрования Как драйвер согласовывает TLS с SQL Server.
Проверка данных, введенных пользователем Параметризируйте SQL и избегайте внедрения.
Режим FIPS Запустите драйвер в средах, совместимых с FIPS.
Всегда зашифрованный Настройте шифрование на стороне клиента для конфиденциальных столбцов.
Всегда зашифровано с безопасными анклавами Включить расширенные возможности работы с зашифрованными столбцами.
Справочник по API Always Encrypted Область API для поставщиков шифрования столбцов и хранилищ ключей.

Работа с данными

Статья Description
Работа с инструкциями и результирующими наборами Основы Statement, PreparedStatement и наборов результатов.
Использование инструкций с JDBC Driver Запустите параметризованные и не параметризованные инструкции.
Обработка сложных инструкций Хранимые процедуры, несколько результатов и количество обновлений.
Работа с результирующими наборами Перебирайте, обновляйте и прокручивайте результаты запроса.
Использование нескольких результирующих наборов Обработка запросов, возвращающих несколько результирующих наборов.
Основные сведения о типах курсоров Однонаправленные, прокручиваемые и обновляемые курсоры.
Использование табличных параметров Передайте TABLE параметры в хранимые процедуры.
Использование массового копирования с помощью JDBC Driver Высокопроизводительная вставка с помощью SQLServerBulkCopy.
API массового копирования для пакетной вставки Ускорение executeBatch рабочих INSERT нагрузок.
Выполнение пакетных операций Пакетные вставки, обновления и удаления.

Типы данных

Статья Description
Работа с типами данных Сопоставление типов Java с типами SQL Server.
Общие сведения о типах данных драйвера JDBC Система типов драйвера и сопоставление с JDBC.
Преобразования типов данных Неявные и явные преобразования между Java и SQL Server.
Различия типов данных Крайние случаи при сопоставлении типов на границе.
Тип данных JSON Хранение и запрос столбцов JSON.
Типы пространственных данных Используйте геометрию и географию из Java.
Векторный тип данных Работа с типом SQL Server vector.
sql_variant Чтение и запись столбцов типа sql_variant.
Определяемые пользователем типы Используйте пользовательские типы CLR из Java.
Поддержка национального набора символов Обработка Unicode и столбцы nvarchar.
Международные функции Аспекты локали, сортировки и глобализации.

Транзакции и параллелизм

Статья Description
Выполнение транзакций commit, rollback, и семантика автоматической фиксации.
Основные сведения о транзакциях Жизненный цикл транзакций и рекомендации.
Уровни изоляции Снимок, чтение подтверждённых данных, сериализуемость и другие.
Управление параллелизмом Оптимистические и пессимистичные стратегии параллелизма.
Блокировка строк Как SQL Server принимает и освобождает блокировки строк.
Использование точек сохранения Частичный откат в рамках транзакции.
Управление размером транзакций Настройте область транзакции, чтобы избежать длительных блокировок.
Транзакции XA Двухфазная фиксация с SQLServerXADataSource.

Производительность и надежность

Статья Description
Повышение производительности и надежности Настройка индексов, запросов и параметров драйвера.
Кэширование метаданных подготовленной инструкции Повторно используйте подготовленные планы инструкций.
Производительность параметров подготовленного запроса Типизация параметров и повторное использование плана выполнения.
Адаптивная буферизация Передавайте большие столбцы в потоковом режиме без их полной загрузки в память.
Закрытие неиспользуемых объектов Незамедлительно освободите ресурсы Statement, ResultSet и Connection.
Высокий уровень доступности и аварийное восстановление Прослушиватели групп доступности и отработка отказа в нескольких подсетях.
Зеркалирование базы данных Используйте драйвер с партнерами по зеркалированию базы данных.

Диагностика и устранение неполадок

Статья Description
Диагностика проблем с JDBC Driver Трассировка, логирование и типичные сценарии сбоев.
Устранение неполадок с подключением Ошибки подключения, ошибки TLS-согласования и именованные экземпляры.
Трассировка работы драйвера Включите ведение журнала JDK для драйвера.
Регистратор производительности и функция обратного вызова Сбор метрик производительности для каждой инструкции.
Журнал расширенных событий Сопоставляйте ошибки клиента с расширенными событиями на стороне сервера.
Обработка ошибок SQLException, коды ошибок и подсказки повторных попыток.
Статья Description
Заметки о выпуске История версий и что нового в каждом выпуске.
Зависимости компонентов Необязательные зависимости для Entra ID, Kerberos, Always Encrypted и других.
Соответствие JDBC 4.3 Соответствие API JDBC 4.3.
Соответствие JDBC 4.2 Соответствие API JDBC 4.2.
Соответствие JDBC 4.1 Соответствие API JDBC 4.1.
Соответствие требованиям и юридическая информация Соответствие спецификациям и лицензированию.
Справочник по API JDBC Driver Классы, интерфейсы, методы и поля, предоставляемые драйвером.
Примеры приложений JDBC Driver Сквозные примеры кода.
FAQ Часто задаваемые вопросы.

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

  • Last updated on