用于 SQL Server 的 Microsoft JDBC 驱动程序

下载 JDBC 驱动程序

用于SQL Server的 Microsoft Java 数据库连接（JDBC）驱动程序是一种类型 4 JDBC 驱动程序（纯Java，直接讨论 SQL Server TDS 协议，无需本机库），允许任何Java应用程序或应用程序服务器连接到SQL Server，Microsoft Fabric中的Azure SQL 数据库、Azure SQL 托管实例和 SQL 数据库。 它实现标准 JDBC API，并与主要Java应用程序服务器（包括 IBM WebSphere 和 SAP NetWeaver）配合使用。

选择起点

• 若要设置Java开发环境并运行第一个查询，请从步骤 1 开始：配置开发环境、步骤 2：创建 SQL 数据库和步骤 3：使用Java连接到 SQL 的概念证明。
• 若要使用无密码身份验证连接到Azure SQL，请使用Microsoft Entra身份验证和生成连接 URL 开始连接。
• 若要将驱动程序添加到 Maven、Gradle 或其他构建工具中，请转到 下载适用于 SQL Server 的 Microsoft JDBC 驱动程序。
• 若要使现有应用具备应对瞬时故障的能力，请转到 连接复原能力 和 可配置的重试逻辑。
• 若要诊断连接或查询问题，请转到 诊断 JDBC 驱动程序的问题 并 排查连接问题。

Azure SQL的生产基线

将此代码片段用作面向生产Azure SQL连接的起点。 它从应用程序配置（如Azure 应用服务应用设置、环境变量或配置文件）加载服务器名称和数据库名称，并以编程方式设置其余连接属性。 该配置结合了传输层安全性（TLS）、托管身份、发生暂时性故障时的连接重试、故障转移组的快速恢复、用于应对冷启动故障转移的更长登录超时时间，以及针对遇到 Azure SQL 限流或查询中途发生故障转移的语句的可配置重试逻辑（CRL）。

为了提高安全性和更轻松的横向扩展，请将连接信息保留在代码之外。 在生产环境中，将连接信息存储在应用程序的配置系统中，并将Azure 密钥保管库用于敏感值和集中管理的连接设置。 有关详细信息，请参阅 保护连接字符串。

本文中的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));
    }
}

此代码片段针对Azure SQL 数据库故障转移组和Azure SQL 托管实例进行了优化。

仅当连接到故障转移组侦听器、可用性组侦听器或故障转移群集实例端点时，才设置 multiSubnetFailover=true。 对不是高可用性 (HA) 侦听器的终结点使用此属性可能会影响性能，并且不受支持。 有关详细信息，请参阅 JDBC 驱动程序对高可用性、灾难恢复的支持。

该代码片段未设置 retryConn，因为驱动程序默认就会对最常见的 Azure SQL 瞬态连接错误（包括 4060、40197、40501、40613、49918、49919、49920、10928 和 10929）自动进行重试，并且该机制受 connectRetryCount 和 connectRetryInterval 控制。 有关完整列表，请参阅 内置暂时性连接错误列表。 仅当您需要使用 +<errorNumber> 添加 retryConn 以通过某个尚未涵盖的错误来扩展列表时，才这样做；或者将其设置为 <errorNumber>（不带前导 +）以替换它。 如果在 JDBC URL 中放置相同的值，请将其包装为 retryConn={+<errorNumber>} 或 retryConn={<errorNumber>}。

retryExec 属性由两部分组成，当你通过编程方式设置它时，写作 rule1;rule2。 如果在 JDBC URL 中放置相同的值，请将每个规则用大括号包装为 {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 等待时间总和加上语句执行时间，否则最长的退避将不会生效。

对于 Azure SQL 数据库 故障转移组、Hyperscale 命名副本和读扩展，或者 Always On 可用性组侦听器，请在希望连接到可读的辅助副本时设置 applicationIntent=ReadOnly。 对于证书主题备用名称（SAN）不包含所连接主机的主权云，还应将 hostNameInCertificate 设置为与之匹配（例如，对于 Azure 政府，设置为 *.database.usgovcloudapi.net）。

有关此配置的每个部分的详细信息，请参阅：

• 生成连接 URL
• 设置连接属性
• 使用 Microsoft Entra 身份验证进行连接
• 连接复原能力
• 可配置的重试逻辑
• JDBC 驱动程序对高可用性和灾难恢复的支持
• 了解 JDBC 驱动程序中的超时属性

有关 Azure SQL 瞬态错误列表，请参阅排查瞬态连接错误。

主要功能

• 基于标准的 JDBC：类型 4 驱动程序。 JRE 11+ 构建版本实现了 JDBC 4.2，并支持 JDBC 4.3 的请求边界方法（beginRequest、endRequest）以及 Statement 引用辅助方法。 JDBC 4.3 分片 API（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：针对敏感列的客户端加密，并支持用于就地操作的可选安全隔离区。
• 批量复制：使用 SQLServerBulkCopy API 实现高吞吐量插入，并为 executeBatch 提供批量插入性能。
• 连接弹性：内置了针对瞬时错误的连接重试机制，并提供可选择启用的可配置重试逻辑，用于语句（retryExec）和可自定义的连接错误列表（retryConn）。
• 丰富的SQL Server数据类型支持：datetimeoffset、sql_variant、JSON、空间、向量、表值参数和用户定义的类型。

开始

配置和连接

Authenticate

Secure

处理数据

数据类型

事务和并发性

性能和可靠性

诊断和故障排除

相关任务

相关内容

• GitHub上的 Microsoft JDBC Driver for SQL Server
• Microsoft Maven Central 上用于SQL Server的 JDBC 驱动程序
• Microsoft JDBC Driver for SQL Server 发行说明
• 查找 JDBC 驱动程序的其他信息
• Microsoft SQL 数据库连接模块