Quickstart: Herstellen einer Verbindung mit SQL Server mit Java und Maven

Verwenden Sie den Microsoft Java Database Connectivity (JDBC)-Treiber für SQL Server, um eine Java-Anwendung mit SQL Server, Azure SQL-Datenbank oder einer SQL-Datenbank in Fabric zu verbinden. Dieser Quickstart verwendet Maven, um Abhängigkeiten herunterzuladen, liest Verbindungseinstellungen aus Umgebungsvariablen und überprüft ein parametrisiertes Abfrageergebnis. Du brauchst kein AdventureWorks oder irgendwelche Beispieltabellen.

Für Azure SQL-Datenbank oder SQL-Datenbank in Fabric verwenden Sie Microsoft Entra ID-Authentifizierung, ohne ein Passwort in Ihrer Anwendung zu speichern. Melden Sie sich während der lokalen Entwicklung über einen Browser an. Für eine in Azure gehostete Anwendung verwenden Sie eine verwaltete Identität.

Voraussetzungen

• Java Entwicklungskit (JDK) 21. Überprüfe deine Installation mit java -version.
• Apache-Maven. Führe mvn -version aus und bestätige, dass Maven JDK 21 verwendet.
• Eine Datenbank und die Berechtigung, sich darauf zu verbinden. Wählen Sie eine gehostete Datenbank oder einen SQL Server-Container in Choose your database. Die Abfrage liest einen berechneten Wert und erstellt oder ändert keine Datenbankobjekte.
• Netzwerkzugang zu deinem Datenbank-Endpunkt. Für Azure SQL konfigurieren Sie den Netzwerkzugang. Für Fabric folgen Sie den Anweisungen unter Herstellen einer Verbindung mit Ihrer SQL-Datenbank. Für SQL Server aktivieren Sie das Transmission Control Protocol/Internet Protocol (TCP/IP) und verwenden Sie den konfigurierten Port.
• Ein Serverzertifikat, dem dein Java-Runtime vertraut. Die Anwendung benötigt eine Verschlüsselung und validiert das Serverzertifikat. Für eine private Zertifizierungsstelle siehe Einer privaten Zertifizierungsstelle vertrauen.

Auswählen Ihrer Datenbank

Verwenden Sie eine bestehende Datenbank oder erstellen Sie eine mit den folgenden Anleitungen. Eine leere Datenbank reicht aus.

SQL Server Linux-Container-Images benötigen einen unterstützten x86-64-Host. Auf einem ARM64-Entwicklungscomputer kann diese Java-Anwendung auf einer gehosteten Datenbank oder einem Container auf einem unterstützten entfernten Host ausgeführt werden, anstatt auf Container-Emulation zu setzen.

Ein neuer Container könnte ein Zertifikat verwenden, dem dein JDK nicht vertraut. Bevor Sie dieses Beispiel ausführen, konfigurieren Sie ein Serverzertifikat und für einen privaten Ausgeber den Java-Vertrauensspeicher. Halte die Zertifikatsvalidierung auch für Containerverbindungen aktiviert.

Erstellen Sie das Maven-Projekt

Erstelle ein Verzeichnis namens jdbc-quickstart. Erstellen Sie in diesem Verzeichnis pom.xml mit folgendem Inhalt. Maven verwaltet den Klassenpfad; du musst keine Java Archive (JAR)-Dateien manuell herunterladen.

<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>

Das jre11 Treiberartefakt funktioniert mit JDK 21. Die explizite azure-identity Abhängigkeit liefert die Authentifizierungsbibliotheken, die für die Microsoft Entra-Modi in diesem Quickstart benötigt werden; diese Bibliotheken sind optionale Abhängigkeiten des Treibers und werden nicht automatisch zu Ihrer Anwendung hinzugefügt.

Diese Versionen entsprechen dem veröffentlichten JDBC 13.6.0 Maven Project Object Model (POM). Die explizite azure-core-http-netty-Abhängigkeit behält die mit diesem Treiber-Release ausgewählte Transportversion bei.

Für Treiber-Updates schauen Sie auf die Download-Seite, die veröffentlichten Maven-Versionen und die Java-Unterstützungsmatrix. Wenn Sie den Treiber aktualisieren, gleichen Sie die Authentifizierungsabhängigkeiten mit dem veröffentlichten POM des Treibers ab. Siehe Funktionsabhängigkeiten. Verwenden Sie explizite Release-Versionen anstelle von Maven-Versionsbereichen oder LATEST.

Konfigurieren Sie die Verbindung

Setze die Umweltvariablen im selben Terminal, in dem du Maven ausführst. Ersetzen Sie <server> und <database> durch Ihren Endpunkt- und Datenbanknamen. Setzen Sie SQL_SERVER_NAME nur auf den Hostnamen, ohne JDBC-URL oder Port.

Wenn der kopierte Serverwert tcp:<server>,1433 lautet, verwenden Sie nur <server> für SQL_SERVER_NAME und setzen Sie SQL_PORT auf 1433. Geben Sie das ,1433Präfix oder das tcp:Suffix nicht im Hostnamen an.

Azure SQL oder Fabric mit Microsoft Entra-Authentifizierung

Verwenden Sie für die lokale Entwicklung ActiveDirectoryInteractive. Der Treiber öffnet einen Browser zur Anmeldung und unterstützt Multifaktor-Authentifizierung. Melden Sie sich mit der Identität an, die Zugriff auf Ihre Datenbank hat. Setzen Sie für diesen Modus weder SQL_USER noch SQL_PASSWORD.

Für Azure SQL-Datenbank ersetzen <server> Sie durch den vollständigen Hostnamen, zum Beispiel contoso.database.windows.net. Für Fabric kopieren Sie den Hostnamen aus den Verbindungseinstellungen der SQL-Datenbank; bauen Sie ihn nicht aus dem Datenbanknamen und fügen Sie kein Azure SQL-Suffix hinzu. Fabric erfordert Microsoft Entra-Authentifizierung; verwenden Sie nicht das SQL-Authentifizierungsbeispiel für Fabric.

$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "ActiveDirectoryInteractive"

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="ActiveDirectoryInteractive"

Für eine headlose Anwendung, die auf einer Azure-Ressource mit einer systemzugewiesenen verwalteten Identität gehostet wird:

1. Aktivieren Sie die verwaltete Identität der Ressource.
2. Bitten Sie Ihren Administrator, dieser Identität Zugriff auf die Datenbank zu gewähren. Für Azure SQL erstellen Sie einen Datenbankbenutzer für die Identität. Für Fabric folgen Sie den Fabric-Authentifizierungs- und Zugriffsanforderungen, einschließlich der entsprechenden Mietereinstellungen für Service-Principals.
3. Legen Sie SQL_AUTHENTICATION in der Anwendungskonfiguration des Hosts auf ActiveDirectoryManagedIdentity fest. Behalte die Server-, Datenbank- und Porteinstellungen. Die gleiche Java-Anwendung läuft ohne Browser oder Passwort.

Managed Identity erfordert einen unterstützten Azure-Host; es ist kein Ersatz für interaktive Anmeldung auf deiner Arbeitsstation. Für benutzerzugewiesene Identitäten und andere Authentifizierungsmodi siehe Verbinden mit Microsoft Entra-Authentifizierung.

SQL Server mit SQL-Authentifizierung

Für einen SQL Server-Container oder eine vorhandene Instanz, die für die SQL-Authentifizierung konfiguriert ist, legen Sie SQL_AUTHENTICATION auf SqlPassword fest und geben Sie eine SQL-Anmeldung mit Zugriff auf Ihre Datenbank an. Verwenden Sie für dieses Beispiel kein Serveradministrator-Konto. Der PowerShell-Passwortprompt benötigt PowerShell 7.1 oder neuer.

$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

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
read -r -s -p "SQL password: " SQL_PASSWORD
printf '\n'
export SQL_PASSWORD

Benutze den TCP-Port deiner Instanz, falls er nicht 1433 ist. Umgebungsvariablen halten Zugangsdaten aus dem Quellcode heraus, aber sie sind kein geheimer Speicher. Protokolliere sie nicht und binde sie nicht in die Versionskontrolle. Aktivieren Sie die Maven-Debug-Protokollierung (-X) nicht, wenn Passwortvariablen gesetzt sind: Das Exec-Plugin protokolliert die Werte der Umgebungsvariablen des untergeordneten Prozesses. Für bereitgestellte Anwendungen nutzen Sie die Geheimnisverwaltungs- und Sicherheitsverbindungseinstellungen Ihrer Plattform.

Vertrauen Sie einer privaten Zertifizierungsstelle

Überspringe diesen Abschnitt, wenn dein JDK bereits dem Zertifikatsaussteller des Servers vertraut. Ansonsten holen Sie sich das öffentliche Zertifikat und den SHA-256-Fingerabdruck der ausstellenden Zertifizierungsstelle (CA) von Ihrem Administrator über einen vertrauenswürdigen Kanal. Vertraue einem Zertifikat nicht, nur weil der Server es während einer fehlgeschlagenen Verbindung angezeigt hat.

Setze SQL_SERVER_NAME auf einen DNS-Namen, der vom Serverzertifikat abgedeckt ist und von deinem Computer aus auflösbar ist. Die Anwendung überschreibt hostNameInCertificatenicht, daher validiert der Treiber den konfigurierten Servernamen. Das Hinzufügen einer vertrauenswürdigen CA behebt keinen Namenskonflikt bei Zertifikaten.

Verwende die keytool aus derselben JDK 21-Installation, die Maven verwendet. Ersetzen Sie <ca-certificate-file> durch den Pfad des verifizierten CA-Zertifikats, <jdk-home> durch das Verzeichnis dieses JDK und <trust-store-file> durch einen neuen absoluten Pfad außerhalb Ihres Projekts. Halte den Vertrauensspeicher in einem Verzeichnis, das andere unprivilegierte Nutzer nicht ändern können. Hör auf, wenn ein Kommando fehlschlägt.

1. Überprüfen Sie das CA-Zertifikat und vergleichen Sie seinen SHA-256-Fingerabdruck mit dem von Ihrem Administrator angegebenen Wert.

   keytool -printcert -file "<ca-certificate-file>"
   

2. Erstelle einen dedizierten PKCS12-Treuhandspeicher, indem du die öffentlichen Wurzeln des JDK kopierst. Ändere nicht die installierte JDK-Datei cacerts und überschreibe auch keinen bestehenden Trust Store.

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

   Geben Sie bei den entsprechenden Eingabeaufforderungen ein neues Passwort für den Zielspeicher ein. Für das Source-Store-Passwort verwenden Sie den von Ihrem JDK-Anbieter oder Administrator bereitgestellten Wert. Das Kopieren der Public Roots bewahrt das Vertrauen in Server, die öffentliche CAs verwenden.

3. Füge die verifizierte CA dem dedizierten Store hinzu.

   keytool -importcert -alias sql-server-ca -file "<ca-certificate-file>" -keystore "<trust-store-file>" -storetype PKCS12
   

   Geben Sie das Passwort für den Zielspeicher ein. Überprüfen Sie vor der Bestätigung des Imports, ob der angezeigte Fingerabdruck mit dem verifizierten Wert übereinstimmt.

Setze diese beiden optionalen Variablen im Terminal, in dem du Maven spielst. Verwenden Sie das Passwort für den Zielspeicher, das Sie gerade erstellt haben. Der PowerShell-Passwortprompt benötigt PowerShell 7.1 oder neuer.

$env:SQL_TRUST_STORE = "<trust-store-file>"
$env:SQL_TRUST_STORE_PASSWORD = Read-Host "Trust-store password" -MaskInput

export SQL_TRUST_STORE="<trust-store-file>"
read -r -s -p "Trust-store password: " SQL_TRUST_STORE_PASSWORD
printf '\n'
export SQL_TRUST_STORE_PASSWORD

Die Java-Anwendung liest diese Variablen und konfiguriert explizit ihren JDBC-Vertrauensspeicher. Beide Variablen werden weggelassen, um die Standard-Vertrauenskonfiguration der Java Virtual Machine (JVM) zu verwenden. Behalten Sie encrypt=true und trustServerCertificate=false bei.

Maven startet für diese Anwendung einen separaten Java-Prozess. Das Setzen einer Java Secure Socket Extension (JSSE)-Eigenschaft wie javax.net.ssl.trustStore mit mvn -D... oder MAVEN_OPTS konfiguriert diesen untergeordneten Prozess nicht. JAVA_TOOL_OPTIONS und JDK_JAVA_OPTIONS erreichen es, aber die JVM gibt diese Optionen beim Start aus. Gib keine Passwörter in eine der beiden Variablen ein. Verwenden Sie stattdessen die Anwendungsvariablen in diesem Abschnitt. Mehr zur Vertrauenskonfiguration finden Sie unter Konfigurieren des Clients für Verschlüsselung.

Füge die Java-Anwendung hinzu

Aus dem jdbc-quickstart Verzeichnis erstellen Sie das Java-Quellverzeichnis.

New-Item -ItemType Directory -Path src\main\java -Force | Out-Null

mkdir -p src/main/java

Speichern Sie die folgende vollständige Anwendung wie Quickstart.java in src/main/java.

Die Transact-SQL (T-SQL)-Abfrage SELECT CAST(? AS int) + 1 AS answer akzeptiert einen Parameter. setInt bindet den Wert 41 separat vom SQL-Text. Das erwartete Ergebnis ist genau eine Zeile, die enthält 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;
    }
}

Die Anwendung setzt die Anmelde- und Abfragezeitlimits auf 30 Sekunden. Die interaktive Authentifizierung hat ein separates Token-Wartelimit, das in Troubleshoot the First Run beschrieben ist. Die Anwendung schließt die Ergebnismenge, das vorbereitete Statement und die Verbindung mithilfe von try-with-resources, auch dann, wenn eine Ausnahme auftritt. Fehler pflanzen sich fort und führen dazu, dass der Prozess mit einem Exit-Status ungleich null beendet wird.

Durchführen und überprüfen

Führen Sie im Verzeichnis jdbc-quickstart Folgendes aus:

mvn -q compile exec:exec

Maven lädt die Abhängigkeiten herunter, kompiliert die Anwendung und startet einen separaten Java-Prozess. Für ActiveDirectoryInteractive schließen Sie die Anmeldung im Browser ab und kehren Sie zu Ihrem Terminal zurück.

Nachdem die Abfrage erfolgreich ist und die Anwendung die Ressourcen schließt, druckt sie:

Verified result: 42

Eine Browser-Meldung, dass die Authentifizierung abgeschlossen ist, beweist nicht, dass die Datenbankverbindung erfolgreich war. Überprüfen Sie das Ergebnis der Anwendung und einen Null-Ausgangsstatus: $LASTEXITCODE in PowerShell oder $? in Bash. Die Abfrage hängt nicht von vorhandenen Tabellen ab oder lässt die Daten zur Bereinigung stehen.

Wenn du SQL-Authentifizierung verwendet hast, entferne SQL_PASSWORD sie aus der Terminalumgebung, wenn du fertig bist. Führen Sie in PowerShell Remove-Item Env:\SQL_PASSWORD aus. Führen Sie in Bash unset SQL_PASSWORD aus.

Wenn Sie einen privaten CA-Trust Store konfiguriert haben, entfernen Sie auch dessen Umweltvariablen. Führen Sie in PowerShell Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD aus. Führen Sie in Bash unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD aus. Behalte den Treuhandspeicher nur so lange, wie du ihn brauchst.

Fehlerbehebung beim ersten Durchlauf

Für weitere Diagnosen siehe Fehlerbehebung der Konnektivität.

Verwandte Inhalte

• Herstellen einer Verbindung mit der Microsoft Entra-Authentifizierung
• Verwenden einer SQL-Anweisung mit Parametern
• Verwendung automatisch generierter Schlüssel
• Verbindungsresilienz
• Beispiele für JDBC-Treiberanwendungen