Microsoft JDBC-Treiber für SQL Server

JDBC-Treiber herunterladen

Der Microsoft Java Database Connectivity (JDBC)-Treiber für SQL Server ist ein JDBC-Treiber vom Typ 4 (reines Java, verwendet das SQL Server-TDS-Protokoll direkt, keine nativen Bibliotheken erforderlich), der es jeder Java-Anwendung und jedem Anwendungsserver ermöglicht, eine Verbindung mit SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance und der SQL-Datenbank in Microsoft Fabric herzustellen. Es implementiert die Standard-JDBC-APIs und arbeitet mit wichtigen Java-Anwendungsservern, darunter IBM WebSphere und SAP NetWeaver.

Auswählen des Startpunkts

• Um eine Java Entwicklungsumgebung einzurichten und Ihre erste Abfrage auszuführen, beginnen Sie mit Schritt 1: Konfigurieren der Entwicklungsumgebung, Schritt 2: Erstellen einer SQL-Datenbank und Schritt 3: Machbarkeitsstudie für die Verbindung mit SQL mithilfe von Java.
• Um eine Verbindung mit Azure SQL mit kennwortloser Authentifizierung herzustellen, beginnen Sie mit Connect mithilfe Microsoft Entra Authentifizierung und Erstellen der Verbindungs-URL.
• Wenn Sie den Treiber zu einem Maven-, Gradle- oder anderen Build-Prozess hinzufügen möchten, rufen Sie Microsoft JDBC-Treiber für SQL Server herunterladen auf.
• Um eine vorhandene App widerstandsfähig gegenüber vorübergehenden Fehlern zu machen, gehen Sie zu Verbindungsresilienz und Konfigurierbare Wiederholungslogik.
• Um ein Verbindungs- oder Abfrageproblem zu diagnostizieren, gehen Sie zu Diagnose von Problemen mit dem JDBC-Treiber und Fehlerbehebung bei Verbindungsproblemen.

Produktionsbasisplan für Azure SQL

Verwenden Sie diesen Codeausschnitt als Ausgangspunkt für eine produktionsorientierte Azure SQL Verbindung. Er lädt den Servernamen und den Datenbanknamen aus der Anwendungskonfiguration, z. B. Azure App Service App-Einstellungen, Umgebungsvariablen oder eine Konfigurationsdatei, und legt die restlichen Verbindungseigenschaften programmgesteuert fest. Die Konfiguration kombiniert Transport Layer Security (TLS), verwaltete Identität, Wiederholungsversuche bei vorübergehenden Verbindungsfehlern, eine schnelle Wiederherstellung von Failovergruppen, ein längeres Anmeldezeitlimit, um ein Failover bei einem Kaltstart abzudecken, und konfigurierbare Wiederholungslogik (CRL) für SQL-Anweisungen, die von Azure SQL-Drosselung oder einem Failover während der Abfrage betroffen sind.

Um eine höhere Sicherheit und eine einfachere Skalierung zu gewährleisten, behalten Sie Verbindungsinformationen außerhalb Des Codes bei. Speichern Sie in der Produktion Verbindungsinformationen im Konfigurationssystem Ihrer Anwendung, und verwenden Sie Azure Key Vault für vertrauliche Werte und zentral verwaltete Verbindungseinstellungen. Weitere Informationen finden Sie unter Sichern von Verbindungszeichenfolgen.

Die Java Codeausschnitte in diesem Artikel lassen Importe und Klassenwrapper aus Platzgründen weg.

// 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));
    }
}

Dieser Codeausschnitt ist für Azure SQL-Datenbank Failovergruppen und Azure SQL Managed Instance optimiert.

Legen Sie multiSubnetFailover=true nur fest, wenn Sie eine Verbindung zu einem Failovergruppenlistener, Verfügbarkeitsgruppenlistener oder Endpunkt einer Failoverclusterinstanz herstellen. Die Verwendung dieser Eigenschaft bei Endpunkten, die keine HA-Listener (High Availability) sind, kann die Leistung beeinträchtigen und wird nicht unterstützt. Weitere Informationen finden Sie unter JDBC-Treiberunterstützung für Hochverfügbarkeit und Notfallwiederherstellung.

Der Codeausschnitt setzt retryConn nicht, da der Treiber die häufigsten vorübergehenden Azure SQL-Verbindungsfehler (einschließlich 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 und 10929) bereits standardmäßig wiederholt, gesteuert durch connectRetryCount und connectRetryInterval. Die vollständige Liste finden Sie in der Liste der integrierten vorübergehenden Verbindungsfehler. Fügen Sie retryConn mit +<errorNumber> nur dann hinzu, wenn Sie die Liste um einen Fehler ergänzen müssen, der noch nicht erfasst ist, oder setzen Sie es auf <errorNumber> (ohne führendes +), um es zu ersetzen. Wenn Sie denselben Wert in eine JDBC-URL einfügen, umschließen Sie ihn mit retryConn={+<errorNumber>} bzw. retryConn={<errorNumber>}.

Die retryExec Eigenschaft verfügt über zwei Teile, die wie rule1;rule2 beim programmgesteuerten Festlegen geschrieben werden. Wenn Sie den gleichen Wert in einer JDBC-URL angeben, setzen Sie jede Regel wie folgt in geschweifte Klammern: {rule1};{rule2}

• {1205,1222:3,5+5} wiederholt Deadlockopfer (1205) und Zeitüberschreitungen bei Sperranforderungen (1222) dreimal mit einem linearen Warteintervall von 5, 10 und 15 Sekunden. Für 1205 setzt SQL Server die Transaktion zurück, bevor der Treiber den Fehler sieht. Daher ist das erneute Ausführen einer einzelnen Anweisung sicher. Wenn die von einem Deadlock betroffene Anweisung Teil einer Transaktion mit mehreren Anweisungen war, wurden auch frühere Anweisungen zurückgerollt, und CRL führt sie nicht erneut aus. Deshalb sollten Sie die gesamte Transaktion in Ihre eigene Wiederholungsschleife einschließen. 1222 lässt die Transaktion offen, und die Wiederholung auf Anweisungsebene führt nur die Anweisung innerhalb der ursprünglichen Transaktion erneut aus; wenn Sie auch die Dauer der Transaktion begrenzen müssen, umschließen Sie die gesamte Transaktion mit Ihrer eigenen Wiederholungsschleife.

• {40501,40613,40197,10928,10929,49918:4,5*2} wiederholt Drosselungsfehler in Azure SQL, Failover während einer Abfrage und Fehler aufgrund von Ressourcenlimits viermal mit exponentiell zunehmenden Wartezeiten von 5, 10, 20 und 40 Sekunden. Diese Fehler stehen in der integrierten Liste vorübergehender Fehler für die connect-Schleife, aber retryExec fängt sie ab, wenn sie mitten in einer Abfrage bei einer bereits bestehenden Verbindung auftreten. CRL-Backoffs sind durch queryTimeout begrenzt. Wenn Sie queryTimeout niedriger als die nächste geplante Wartezeit festlegen, gibt der Treiber vorzeitig auf und löst die Ausnahme erneut aus. Wählen Sie ein queryTimeout, das mindestens so groß ist wie die Summe Ihrer CRL-Wartezeiten und der Laufzeit der Anweisung, oder akzeptieren Sie, dass die längsten Backoffs nicht ausgelöst werden.

Legen Sie für Azure SQL-Datenbank-Failovergruppen, benannte Hyperscale-Replikate und Read Scale-Out oder Always On-Verfügbarkeitsgruppenlistener applicationIntent=ReadOnly fest, wenn Sie bei einem lesbaren sekundären Replikat landen möchten. Für souveräne Clouds, bei denen der Subject Alternative Name (SAN) des Zertifikats den Host, mit dem Sie eine Verbindung herstellen, nicht enthält, legen Sie auch hostNameInCertificate entsprechend fest (zum Beispiel *.database.usgovcloudapi.net für Azure Government).

Weitere Informationen zu den einzelnen Teilen dieser Konfiguration finden Sie unter:

• Erstellen der Verbindungs-URL
• Festlegen der Verbindungseigenschaften
• Herstellen einer Verbindung mit der Microsoft Entra-Authentifizierung
• Verbindungsresilienz
• Konfigurierbare Wiederholungslogik
• JDBC-Treiber-Unterstützung für hohe Verfügbarkeit, Notfallwiederherstellung
• Grundlagen zu Timeout-Eigenschaften im JDBC-Treiber

Informationen zum Katalog der vorübergehenden Azure SQL-Fehler finden Sie unter Problembehandlung bei vorübergehenden Verbindungsfehlern.

Wichtigste Funktionen

• Standardbasiertes JDBC: Typ-4-Treiber. Der JRE-11+-Build implementiert JDBC 4.2 sowie die Request-Boundary-Methoden (beginRequest, endRequest) und die Hilfsfunktionen für die Quotierung mit Statement. JDBC 4.3 Sharding-APIs (setShardingKey, die createConnectionBuilder-Familie) werfen SQLFeatureNotSupportedException. Der JRE-8-Build unterstützt JDBC 4.2. Die Aufschlüsselung pro Version und die vollständige Liste der unterstützten und nicht unterstützten 4.3-Methoden finden Sie unter Unterstützung der Java- und JDBC-Spezifikation.
• Breite Plattformunterstützung: Läuft auf jeder Plattform mit einem unterstützten Java Virtual Machine (JVM), einschließlich Windows, Linux und macOS.
• Standardmäßig verschlüsselt: TLS-verschlüsselte Verbindungen encrypt=true als Standard für aktuelle Treiber.
• Microsoft Entra ID-Authentifizierung: Kennwortlose Verbindungen mit verwalteter Identität, Dienstprinzipal, interaktiven, integrierten, Standard-Anmeldeinformationsketten- und Zugriffstoken-Abläufen.
• Kerberos: Integrierte Authentifizierung für lokales Active Directory.
• NTLM: Windows Abfrage-/Antwortauthentifizierung für Nichtdomänen- oder Legacyszenarien.
• Always Encrypted: clientseitige Verschlüsselung für vertrauliche Spalten mit optionalen sicheren Enklaven für Vorgänge direkt an Ort und Stelle.
• Massenkopieren: Einfügevorgänge mit hohem Durchsatz mit der SQLServerBulkCopy-API und Leistung bei Stapeleinfügungen für executeBatch.
• Verbindungsresilienz: Integrierte Verbindungsversuche für vorübergehende Fehler sowie konfigurierbare Wiederholungslogik für Anweisungen (retryExec) und eine anpassbare Verbindungsfehlerliste (retryConn).
• Umfassende Unterstützung für SQL Server-Datentypen: datetimeoffset, sql_variant, JSON, räumliche Daten, Vektoren, tabellenwertige Parameter und benutzerdefinierte Typen.

Get started

Konfigurieren und Verbinden

Authenticate

Absichern

Mit Daten arbeiten

Datentypen

Transaktionen und Parallelität

Leistung und Zuverlässigkeit

Diagnostizieren und Problembehandlung

Verwandte Aufgaben

Zugehöriger Inhalt

• Microsoft JDBC-Treiber für SQL Server auf GitHub
• Microsoft JDBC-Treiber für SQL Server auf Maven Central
• Versionshinweise für den Microsoft JDBC-Treiber für SQL Server
• Suchen von zusätzlichen Informationen zum JDBC-Treiber
• Verbindungsmodule für microsoft SQL-Datenbank