快速入门:使用 Java 和 Maven 连接到 SQL Server

使用适用于 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 资源上且具有系统分配的托管标识的无头应用:

  1. 启用资源的托管身份。
  2. 请让管理员授予该身份对数据库的访问权限。 对于 Azure SQL,创建一个数据库用户来识别身份。 对于 Fabric,请遵循 Fabric 身份验证和访问要求中的要求,其中包括适用于服务主体的租户设置。
  3. 在主机的应用程序配置中,将 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> 替换为项目外的新绝对路径。 把信任存储放在一个其他无权限用户无法修改的目录里。 如果有任何命令失败就停止。

  1. 检查CA证书,并将其SHA-256指纹与管理员提供的数值进行比较。

    keytool -printcert -file "<ca-certificate-file>"
    
  2. 通过复制 JDK 的公网根节点,创建一个专用的 PKCS12 信任存储库。 不要修改已安装的 JDK 的 cacerts 文件,也不要覆盖现有的信任库。

    keytool -importkeystore -srckeystore "<jdk-home>/lib/security/cacerts" -destkeystore "<trust-store-file>" -deststoretype PKCS12
    

    在提示中输入新的目的地存储密码。 对于源存储密码,请使用你的JDK提供商或管理员提供的值。 复制公共根证书可保留对使用公共 CA 的服务器的信任。

  3. 将已验证的 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 绕过验证。

如需更多诊断信息,请参阅 连接故障排查。