使用适用于 SQL Server 的 Microsoft Java 数据库连接 (JDBC) 驱动程序,将 Java 应用程序连接到 SQL Server、Azure SQL 数据库 或 Fabric 中的 SQL 数据库。 该快速入门使用Maven下载依赖,读取环境变量中的连接设置,并验证参数化查询结果。 你不需要AdventureWorks或任何示例表。
对于Azure SQL 数据库或Fabric中的SQL数据库,使用Microsoft Entra ID认证,无需在应用中存储密码。 在本地开发期间,请通过浏览器登录。 对于托管在 Azure 中的应用,可以使用管理身份。
先决条件
-
Java开发工具包(JDK)21. 使用
java -version检查您的安装情况。 -
Apache Maven。 运行
mvn -version并确认 Maven 使用 JDK 21。 - 一个数据库和连接权限。 在“选择你的数据库”中选择托管数据库或 SQL Server 容器。 查询读取的是计算值,不会创建或修改数据库对象。
- 对您的数据库端点的网络访问。 对于 Azure SQL,配置网络访问。 对于 Fabric,请参阅 Connect to your SQL database。 对于 SQL Server,启用传输控制协议/互联网协议(TCP/IP),并使用配置好的端口。
- 你的 Java 运行时信任的服务器证书。 该应用程序需要加密并验证服务器证书。 对于私有证书颁发机构,请参阅 信任私有证书颁发机构。
选择数据库
可以使用现有数据库,或按照以下指南创建一个。 一个空的数据库就足够了。
| Database | 设置和访问 |
|---|---|
| Fabric 中的 SQL 数据库 | 创建一个SQL数据库,然后遵循Fabric的认证和访问要求。 从 设置>中的连接字符串复制数据库的服务器和数据库名称。 使用SQL数据库连接,而不是它的SQL分析端点。 |
| Azure SQL 数据库 | 创建单一数据库。 请你的管理员配置一个 Microsoft Entra 管理员,并为你的身份创建一个数据库用户。 仅靠Azure订阅访问并不能授予数据库访问权。 |
| SQL Server 容器 | 通过使用 Docker、sqlcmd 或 Visual Studio Code 的 MSSQL 扩展创建容器。 使用容器主机的DNS名称和已发布的TCP端口,并使用带有访问权限的SQL登录权限连接到你的数据库。 |
| 现有的 SQL Server | 使用实例的DNS名称、TCP端口和现有数据库。 向你的管理员请求一个带有连接权限的SQL登录。 |
SQL Server Linux 容器镜像需要支持的 x86-64 主机。 在ARM64开发计算机上,可以对托管数据库或支持的远程主机上的容器运行该Java应用,而非依赖容器仿真。
新容器可能使用你的JDK不信任的证书。 在运行此示例之前,先配置服务器证书,并为私有发行方配置 Java 信任存储。 容器连接时也保持证书验证功能开启。
创建Maven项目
创建名为 jdbc-quickstart 的目录。 在该目录中,创建 pom.xml,内容如下。 Maven 管理类路径;你不需要手动下载 Java 归档(JAR)文件。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>jdbc-quickstart</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>com.microsoft.sqlserver</groupId>
<artifactId>mssql-jdbc</artifactId>
<version>13.6.0.jre11</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-netty</artifactId>
<version>1.16.6</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.4</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.0</version>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.5.0</version>
<configuration>
<executable>${java.home}/bin/java</executable>
<arguments>
<argument>-classpath</argument>
<classpath />
<argument>Quickstart</argument>
</arguments>
</configuration>
</plugin>
</plugins>
</build>
</project>
jre11驱动构件可与 JDK 21 配合使用。 显式azure-identity依赖提供了本快速入门中 Microsoft Entra 模式所需的认证库;这些库是驱动程序的可选依赖,不会自动添加到你的应用程序中。
这些版本与 已发布的JDBC 13.6.0 Maven项目对象模型(POM)相匹配。 显式 azure-core-http-netty 依赖保留了该驱动程序释放时选择的传输版本。
关于驱动更新,请查看下载页面、已发布的 Maven 版本和 Java 支持矩阵。 更新驱动时,将认证依赖与驱动发布的POM匹配。 参见 特征依赖。 请使用明确指定的发布版本,而不要使用 Maven 版本区间或 LATEST。
配置连接
在运行Maven的同一个终端里设置环境变量。 用你的端点和数据库名称替换 <server> 和 <database> 。 只设置 SQL_SERVER_NAME 主机名,不使用JDBC的URL或端口。
如果复制得到的服务器值为 tcp:<server>,1433,则仅将 <server> 用于 SQL_SERVER_NAME,并将 SQL_PORT 设置为 1433。 主机名中不要包含 tcp: 前缀或 ,1433 后缀。
使用 Microsoft Entra 身份验证的 Azure SQL 或 Fabric
对于局部开发,使用 ActiveDirectoryInteractive。 驱动会打开浏览器登录,并支持多因素认证。 用有权限访问数据库的身份登录。 不要为此模式设置 SQL_USER 或 SQL_PASSWORD 。
对于 Azure SQL 数据库,请用完整的主机名替换<server>,例如 contoso.database.windows.net。 对于 Fabric,从 SQL 数据库的连接设置中复制主机名;不要从数据库名称构建,也不要附加 Azure SQL 后缀。 Fabric 需要 Microsoft Entra 认证;不要使用 Fabric 的 SQL 认证示例。
$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "ActiveDirectoryInteractive"
对于托管在 Azure 资源上且具有系统分配的托管标识的无头应用:
- 启用资源的托管身份。
- 请让管理员授予该身份对数据库的访问权限。 对于 Azure SQL,创建一个数据库用户来识别身份。 对于 Fabric,请遵循 Fabric 身份验证和访问要求中的要求,其中包括适用于服务主体的租户设置。
- 在主机的应用程序配置中,将
SQL_AUTHENTICATION设置为ActiveDirectoryManagedIdentity。 保留服务器、数据库和端口设置。 同一个Java应用无需浏览器或密码即可运行。
托管身份需要支持的 Azure 主机;它不能替代你工作站上的交互式登录。 关于用户分配身份及其他认证方式,请参见使用 Microsoft Entra 认证连接。
SQL Server 与 SQL 认证
对于配置为 SQL 身份验证的 SQL Server 容器或现有实例,请将 SQL_AUTHENTICATION 设置为 SqlPassword,并提供一个有权访问你的数据库的 SQL 登录名。 请不要使用服务器管理员账户来获取这个示例。 PowerShell密码提示需要PowerShell 7.1或更高版本。
$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "SqlPassword"
$env:SQL_USER = "<user_id>"
$env:SQL_PASSWORD = Read-Host "SQL password" -MaskInput
如果不是1433端口,就用你实例的TCP端口。 环境变量会阻止凭证进入源代码,但它们不是秘密存储。 不要把它们写入日志,也不要将它们提交到源代码管理中。 在设置密码变量时不要启用 Maven 调试日志-X(),执行插件会记录子进程的环境值。 对于已部署的应用,请使用所在平台的机密管理和 安全连接设置。
信任私人证书授权中心
如果你的JDK已经信任服务器的证书发行方,可以跳过这一部分。 否则,通过可信渠道从管理员那里获取发布证书授权机构(CA)的公开证书和SHA-256指纹。 不要仅仅因为服务器在连接失败时给出了证书就信任它。
将 SQL_SERVER_NAME 设置为与服务器证书匹配且可从你的计算机解析的 DNS 名称。 应用程序不会覆盖 hostNameInCertificate,所以驱动会验证配置的服务器名称。 添加一个受信任的CA并不能解决证书名称不匹配的问题。
使用 Maven 所使用的同一 JDK 21 安装中的 keytool。 将 <jdk-home> 替换为已验证的 CA 证书的路径,将 <trust-store-file> 替换为该 JDK 的目录,并将 <ca-certificate-file> 替换为项目外的新绝对路径。 把信任存储放在一个其他无权限用户无法修改的目录里。 如果有任何命令失败就停止。
检查CA证书,并将其SHA-256指纹与管理员提供的数值进行比较。
keytool -printcert -file "<ca-certificate-file>"通过复制 JDK 的公网根节点,创建一个专用的 PKCS12 信任存储库。 不要修改已安装的 JDK 的
cacerts文件,也不要覆盖现有的信任库。keytool -importkeystore -srckeystore "<jdk-home>/lib/security/cacerts" -destkeystore "<trust-store-file>" -deststoretype PKCS12在提示中输入新的目的地存储密码。 对于源存储密码,请使用你的JDK提供商或管理员提供的值。 复制公共根证书可保留对使用公共 CA 的服务器的信任。
将已验证的 CA 证书添加到专用存储区中。
keytool -importcert -alias sql-server-ca -file "<ca-certificate-file>" -keystore "<trust-store-file>" -storetype PKCS12输入目的地存储密码。 在确认导入前,检查显示的指纹是否与验证值相符。
在运行Maven的终端里设置这两个可选变量。 使用你刚创建的目标存储区密码。 PowerShell密码提示需要PowerShell 7.1或更高版本。
$env:SQL_TRUST_STORE = "<trust-store-file>"
$env:SQL_TRUST_STORE_PASSWORD = Read-Host "Trust-store password" -MaskInput
Java 应用程序读取这些变量并明确配置其 JDBC 信任存储。 省略这两个变量,以使用Java虚拟机(JVM)默认的信任配置。 保持 encrypt=true 和 trustServerCertificate=false。
Maven 为该应用启动了一个独立的 Java 进程。 将 Java 安全套接字扩展(JSSE)属性(例如 javax.net.ssl.trustStore)设置为使用 mvn -D... 或 MAVEN_OPTS,并不会对该子进程进行配置。
JAVA_TOOL_OPTIONS 和 JDK_JAVA_OPTIONS 都能获取到它,但 JVM 会在启动时回显这些选项。 密码不要放在任何变量里。 请改用本节中的应用程序变量。 关于信任配置的更多信息,请参见 “配置客户端加密”。
添加Java应用
从该jdbc-quickstart目录创建 Java 源代码目录。
New-Item -ItemType Directory -Path src\main\java -Force | Out-Null
将以下完整的应用程序保存为 Quickstart.java,并保存到 src/main/java 中。
Transact-SQL(T-SQL)查询 SELECT CAST(? AS int) + 1 AS answer 接受一个参数。
setInt 将值 41 与SQL文本分开绑定。 预期结果恰好是一行,其中包含 42。
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import com.microsoft.sqlserver.jdbc.SQLServerDataSource;
public class Quickstart {
public static void main(String[] args) throws SQLException {
SQLServerDataSource dataSource = new SQLServerDataSource();
dataSource.setServerName(required("SQL_SERVER_NAME"));
dataSource.setDatabaseName(required("SQL_DATABASE_NAME"));
dataSource.setPortNumber(Integer.parseInt(required("SQL_PORT")));
dataSource.setEncrypt("true");
dataSource.setTrustServerCertificate(false);
dataSource.setLoginTimeout(30);
String authentication = required("SQL_AUTHENTICATION");
switch (authentication) {
case "ActiveDirectoryInteractive":
case "ActiveDirectoryManagedIdentity":
break;
case "SqlPassword":
dataSource.setUser(required("SQL_USER"));
dataSource.setPassword(required("SQL_PASSWORD"));
break;
default:
throw new IllegalArgumentException(
"SQL_AUTHENTICATION must be ActiveDirectoryInteractive, "
+ "ActiveDirectoryManagedIdentity, or SqlPassword.");
}
dataSource.setAuthentication(authentication);
if (System.getenv("SQL_TRUST_STORE") != null
|| System.getenv("SQL_TRUST_STORE_PASSWORD") != null) {
dataSource.setTrustStore(required("SQL_TRUST_STORE"));
dataSource.setTrustStorePassword(required("SQL_TRUST_STORE_PASSWORD"));
dataSource.setTrustStoreType("PKCS12");
}
String sql = "SELECT CAST(? AS int) + 1 AS answer";
try (Connection connection = dataSource.getConnection();
PreparedStatement statement = connection.prepareStatement(sql)) {
statement.setInt(1, 41);
statement.setQueryTimeout(30);
try (ResultSet results = statement.executeQuery()) {
if (!results.next() || results.getInt("answer") != 42 || results.next()) {
throw new SQLException("Expected exactly one row with answer = 42.");
}
}
}
System.out.println("Verified result: 42");
}
private static String required(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("Set environment variable " + name + ".");
}
return value;
}
}
应用程序将登录和查询超时设置为30秒。 交互式身份验证有单独的令牌等待时限,详见首次运行疑难解答。 应用程序使用 try-with-resources 关闭结果集、预处理语句和连接,即使在发生异常时也是如此。 错误会传播,导致进程以非零状态退出。
运行并验证
在 jdbc-quickstart 目录中,运行:
mvn -q compile exec:exec
Maven 下载依赖,编译应用程序,并启动一个独立的 Java 进程。 对于 ActiveDirectoryInteractive,完成浏览器登录并返回终端。
查询成功且应用程序关闭资源后,会打印:
Verified result: 42
浏览器提示认证已完成并不能证明数据库连接成功。 检查该应用程序的结果以及退出状态是否为零:在 PowerShell 中使用 $LASTEXITCODE,或在 Bash 中使用 $?。 查询不依赖于任何现有表,也不留下数据需要清理。
如果你用过SQL认证,完成后就从终端环境移除 SQL_PASSWORD 。 在 PowerShell 中运行 Remove-Item Env:\SQL_PASSWORD。 在 Bash 中,运行 unset SQL_PASSWORD。
如果你配置了私有CA信任存储,也要移除它的环境变量。 在 PowerShell 中运行 Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD。 在 Bash 中,运行 unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD。 仅在需要时保留信任存储。
对首次运行进行故障排除
| 症状 | Action |
|---|---|
Set environment variable ... |
在运行Maven的终端中设置命名变量。 集成开发环境(IDE)可能需要自己的运行配置。 |
| Java编译或类版本错误 | 运行 mvn -version 并检查 Maven 是否使用 JDK 21。 如果 Maven 和 java -version 报告的运行时不同,请检查 JAVA_HOME。 |
| 缺少身份验证库 | 将 azure-identity 依赖保留在 pom.xml 中,并通过 Maven 运行该应用程序,以便其包含传递依赖。 |
| 登录超时或连接被拒绝 | 检查服务器主机名、TCP端口、数据库可用性和网络访问。 |
| 交互式登录超时 | 司机最多等待20秒以接收交互令牌请求。 请及时完成登录。 如果请求超时,请重新运行该命令。 增加 loginTimeout 不会延长此令牌等待限制。 |
| Microsoft Entra登录成功,但数据库访问失败 | 确认你登录的是正确的租户,并且你的身份有权访问所选数据库。 检查 Azure SQL 数据库用户或 Fabric 权限(如适用)。 |
证书验证失败,包括 PKIX path building failed 在内 |
遵循针对专用颁发者的信任专用证书颁发机构。 使用服务器证书覆盖的DNS名称连接。 不要使用 trustServerCertificate=true 绕过验证。 |
如需更多诊断信息,请参阅 连接故障排查。